# ENG-3270 — Contrato operacional do backend após fechamento

## Aprovação e escopo

Desenho aprovado pelo responsável do backend em 2026-11-13. Implementar as dependências de backend que permitem ao Rex-Estoque concluir a ENG-3270, preservando a base das ENG-3116/3117/3118. Não modificar o app, schema, estoque, ERP, bloqueios WMS ou ações gerenciais.

A abordagem aprovada combina uma consulta operacional dedicada de contexto com extensões aditivas nas consultas existentes. Apenas ampliar a listagem de tarefas tornaria a leitura do ciclo de vida dependente dessas tarefas; criar uma API paralela completa duplicaria projeções e regras. Manter `available-rounds` como descoberta em inventários iniciados, sem transformá-la em uma consulta histórica.

## Problema atual

- `available-rounds` omite o status do inventário e o ingresso individual; não retorna capacidades.
- As leituras de tarefas exigem inventário `iniciado` e passam a retornar 404 em conferência, aprovação pendente ou decisão terminal.
- O replay idempotente recupera a revisão do comando, mas o app ainda precisa consultar a contagem vigente. A consulta atual deixa de funcionar após o fechamento.
- Uma nova contagem em rodada concluída/desconsiderada pode receber `inventory_round_not_started`.

## Consulta de contexto

Adicionar `GET /api/v1/inventory/rounds/{round}/context`, autenticado e operacional, sem middleware/projeção gerencial. Resposta `data`:

- `inventory`: `id`, `code`, `description`, `status`.
- `round`: `id`, `number`, `status`, `started_at`, `ended_at`.
- `participant`: `has_entered`, `first_entered_at`, referentes exclusivamente ao operador autenticado.
- `capabilities`: `can_enter`, `can_claim`, referentes à rodada/contexto do operador.

Não retornar saldos, quantidades alheias, resultados oficiais, motivos/comparações gerenciais nem dados de outros participantes. Uma leitura não inicia rodada, registra ingresso, assume tarefa ou cria evento.

O contexto é legível para participante ainda autorizado nos estados pós-início usados pelo fluxo local: `iniciado`, `conferencia`, `aguardando`, `aprovado`, `reprovado`. Exigir `started_at`; rascunho e estados desconhecidos não se tornam contextos operacionais válidos.

## Extensões aditivas

- `available-rounds` preserva seus campos, filtro de inventário iniciado e ordenação. Acrescentar `inventory.status`, `ended_at`, `participant` e capacidades da rodada. Rodadas concluídas/desconsideradas de um inventário ainda iniciado permanecem listadas com escrita indisponível, como no contrato anterior.
- Lista e detalhe operacionais de tarefas preservam seus campos e paginação. Acrescentar `context` com a mesma projeção da nova consulta.
- Cada tarefa operacional recebe `capabilities`: `can_claim`, `can_count`, `can_correct`.
- Permitir essas leituras após fechamento para participantes ainda autorizados. Manter os escopos `mine`/`open` e a recusa de acesso direto a tarefa de outra pessoa.
- `count` continua sendo apenas a contagem vigente da tarefa própria, e também deve pertencer ao autor autenticado. Uma autoria incompatível não expõe quantidade e não habilita nova contagem/correção.
- As projeções de gestão/distribuição não recebem capacidades operacionais nem passam a revelar contagens por essa extensão.

## Capacidades e comandos

Centralizar as condições de operação para que projeção e comandos não divirjam:

- Ingresso/assunção: inventário iniciado, `started_at` presente e rodada pendente/em andamento.
- A tarefa assumível precisa estar aberta ou já pertencer ao operador; o segundo caso representa a repetição idempotente existente.
- Contagem: além das condições anteriores, rodada em andamento/iniciada, ingresso individual confirmado, modalidade congelada válida e propriedade da tarefa. Só habilitar `can_count` quando ainda não houver contagem.
- Correção: mesmas condições de escrita, contagem existente e autoria do operador. Versão e justificativa continuam sendo validadas no comando.
- `can_enter` pode continuar verdadeiro para ingresso já realizado: o comando é idempotente. `participant.has_entered` distingue a necessidade de ingresso da possibilidade de repeti-lo.
- Capacidades refletem o instante da leitura. Não são autorização fornecida pelo cliente nem garantem que uma escrita futura vencerá o fechamento. Todas as validações e locks transacionais continuam obrigatórios.

## Fechamento e idempotência

Separar leitura autorizada de capacidade de escrita. Aprovar/reprovar ou concluir/desconsiderar não concede escrita nem torna automaticamente inexistente o contexto do participante autorizado.

Preservar a ordem do comando de contagem: autenticar/contextualizar, revalidar participação/propriedade, verificar comando já persistido e então validar uma nova escrita. Um replay autorizado da mesma chave/payload/autor retorna a revisão original, sem revisão/evento novo. A leitura da tarefa fornece a versão vigente, que pode ser posterior ao recibo recuperado.

Usar conflitos específicos `inventory_round_completed` e `inventory_round_discarded` nas operações de ingresso, assunção e contagem/correção. Reservar `inventory_round_not_started` para rodada que ainda não iniciou contagem. Preservar `inventory_not_operable` para inventário sem escrita; a consulta operacional distingue sua situação atual. Preservar códigos existentes de versão, propriedade, ingresso e reutilização de comando.

## Autorização e cegueira

- Contexto deve corresponder ao setor/depósito resolvidos pelo servidor.
- Usuário deve conservar o acesso cadastral e o nível ativo permitidos, além da participação selecionada na rodada.
- Admin/Master não têm bypass de participação, propriedade ou autoria no fluxo operacional.
- Contexto ausente/fora do contexto ou sem fotografia operacional: 404. Acesso atual revogado/não participante: 403. Tarefa de outra pessoa: 409 sem identificar o proprietário.
- Não usar Resource administrativo para construir respostas operacionais ou erros.

## Testes e validação

Cobrir os cinco estados pós-início, rodada pendente/em andamento/concluída/desconsiderada, duas rodadas com capacidades independentes, ingresso individual e leitura sem efeitos. Validar tarefa aberta/própria/alheia, modalidade ausente, autoria e proteção de quantidades.

Cobrir gravação seguida de fechamento e replay; fechamento vencedor seguido de comando novo; replay de revisão antiga seguido de leitura da contagem vigente; acesso revogado; isolamento de contexto e Admin/Master. Verificar ausência de novas revisões, leituras e eventos nos GETs/replays.

Executar regressões de inventário e testes reais de concorrência em PostgreSQL descartável exclusivo, após `test:database-safety`. Não usar o PostgreSQL/banco de desenvolvimento compartilhado nem copiar seu `.env`. Rodar Pint nos arquivos modificados. Documentar os contratos e registrar resultados/limitações de execução.

## Preservação do trabalho existente

Existem alterações locais preexistentes em catálogo/configuração/busca de participantes. Não sobrescrever, reverter ou incluir essas alterações em commits desta implementação. Mudanças no documento de API compartilhado devem ser pontuais e preservar a documentação anterior.
