# ENG-3270 — Plano de implementação do contrato operacional

Referência aprovada: `2026-11-13-eng-3270-backend-operational-context-design.md`.

## 1. Regressão e ambiente seguro

- [x] Criar `tests/Feature/Inventory/InventoryOperationalContextTest.php` com fixture real de inventário, duas rodadas e tarefas própria/alheia/aberta.
- [x] Testar consulta dedicada, capacidades, ingresso individual, cinco estados pós-início, autorizações e ausência de efeitos nos GETs.
- [x] Testar fechamento real por comandos de gestão, replay de revisão antiga e consulta da versão vigente, sem duplicar eventos/evidências.
- [x] Preparar cópia isolada do código/dependências e PostgreSQL 16 descartável, em rede Docker interna e sem `.env` da aplicação principal.
- [x] Rodar `php artisan --env=testing test:database-safety` antes de Pest e registrar RED dos testes novos.

## 2. Regras compartilhadas

- [x] Criar `Domain/Inventory/Services/InventoryOperationalPolicy.php` para capacidades de rodada/tarefa e validação de situação de novas escritas.
- [x] Compartilhar os predicados entre projeções e comandos. Autorização contextual/participação/propriedade e validação de payload/versão continuam nos serviços existentes.
- [x] Distinguir `inventory_round_completed`, `inventory_round_discarded`, `inventory_round_not_started` e indisponibilidade do inventário.
- [x] Preservar a posição do replay em `InventoryCountCommandService`, anterior à validação de nova escrita.

## 3. Consultas operacionais

- [x] Adicionar rota e ação `context` em `routes/api.php` e `InventoryRoundExecutionController.php`.
- [x] Estender `InventoryRoundExecutionService`: contexto mínimo, participação individual e capacidades; leitura autorizada pós-início sem exigir escrita.
- [x] Construir contexto/lista/detalhe sob transação de leitura e shared locks na ordem inventário → rodada, evitando misturar estado do fechamento com capacidades antigas durante a projeção.
- [x] Enriquecer `available-rounds` em uma consulta SQL, sem N+1, mantendo filtro/ordenação/listagem anteriores.
- [x] Reutilizar a paginação de `InventoryRoundTaskProjection`, permitindo um mapper operacional de linha sem afetar a projeção de gestão.
- [x] Retornar `count` apenas quando propriedade e autoria correspondem ao operador; calcular capacidades a partir da linha bruta, mesmo quando uma contagem alheia deve ser ocultada.

## 4. Comandos e concorrência

- [x] Usar a policy compartilhada em ingresso/assunção e novas contagens/correções, preservando ordem de locks e idempotência.
- [x] Atualizar `InventoryReviewConcurrencyTest.php` para o conflito correto quando o fechamento vence.
- [x] Executar testes focais novos e regressões de rodadas, contagem e conferência/fechamento.
- [x] Executar as suítes de inventário Feature/Unit, serializadas no banco exclusivo, incluindo workers PostgreSQL reais.

## 5. Documentação e entrega

- [x] Documentar payloads, capacidades, erros, fluxos de recuperação e limites em `docs/inventory-operational-api.md`.
- [x] Atualizar pontualmente os contratos existentes de rodadas/contagem, preservando os trechos locais preexistentes.
- [x] Rodar Pint somente nos PHP modificados e `git diff --check`.
- [x] Registrar comandos, resultados e limitações em `docs/validation/eng-3270/backend.md`.
- [x] Revisar diffs e confirmar que alterações locais anteriores não foram revertidas ou incluídas indevidamente.

Sem deploy ou alterações no Rex-Estoque. O documento/contrato deve bastar para Gabriel adaptar o consumidor nativo. Após a validação, o responsável autorizou o commit e o push da implementação.

Implementação e validação concluídas. Resultados e ressalva da falha preexistente de concorrência estão em [backend.md](../validation/eng-3270/backend.md). A implementação fica em commit próprio, separado do desenho e sem incluir o trabalho local anterior.
