# ENG-3118 — API web de conferência e encerramento local

Todas as rotas abaixo exigem Sanctum e acesso Admin/Master contextual da Expedição. O backend calcula resultados, abrangência e elegibilidade; a gestão envia somente a intenção, justificativa, confirmação explícita e a versão da prévia. Nenhuma rota deste fluxo consulta saldo WMS/ERP, atualiza estoque ou envia ajuste ao ERP.

## Revisão de rodadas

- `GET /api/v1/inventory/{inventory}/rounds/{round}/review-preview` — prévia por produto/endereço, com quantidade somente quando todos os endereços têm revisão confirmada; `0.00` é confirmação válida. Retorna `review_version`.
- `POST /api/v1/inventory/{inventory}/rounds/{round}/complete`

```json
{
  "command_id": "8e0397c5-4088-45bd-83e4-9a9f27b9b261",
  "review_version": "<sha256 da revisão>",
  "allow_partial": true
}
```

Uma rodada aberta é materializada uma vez. Produtos completos recebem resultado imutável; os incompletos, quando o encerramento parcial foi confirmado, ficam `aborted` sem quantidade final. A rodada deixa de aceitar contagens.

- `POST /api/v1/inventory/{inventory}/rounds/{round}/discard` — permite desconsiderar rodadas pendentes, em andamento ou concluídas; exige `command_id`, `review_version`, `reason` (após trim) e `confirm_official_invalidation`. A desconsideração preserva revisões e resultados concluídos no histórico, retira apenas a oficialização dessa rodada com reconhecimento explícito e exclui a rodada da elegibilidade.

## Resultados, recontagem e fonte oficial

- `GET /api/v1/inventory/{inventory}/results` — fontes por produto/rodada, unidade fotografada, evidência por endereço, fonte oficial atual, histórico relacional de decisões oficiais (`manual_selection`, `consensus`, `invalidated`) e nova `review_version`. É leitura sem efeitos.
- `GET /api/v1/inventory/{inventory}/recounts/preview?mode=total|divergences` — retorna produtos, endereços fotografados, resultados oficiais afetados e a versão que deve ser confirmada. `divergences` inclui produtos cujos dois resultados completos elegíveis mais recentes divergem.
- `POST /api/v1/inventory/{inventory}/recounts`

```json
{
  "command_id": "8e0397c5-4088-45bd-83e4-9a9f27b9b261",
  "review_version": "<sha256 da revisão>",
  "mode": "divergences",
  "reason": "Divergência entre as duas últimas rodadas completas.",
  "confirm_official_invalidation": true
}
```

A abrangência é resolvida no servidor. Não existe seleção de produtos ou endereços arbitrários. Resultados oficiais afetados só são retirados na transação que cria a nova rodada.

- `PUT /api/v1/inventory/{inventory}/products/{inventoryProduct}/official-result` — recebe `command_id`, `review_version`, `result_id` e `reason`. Só aceita fonte completa do mesmo produto e rodada concluída. Uma fonte única ou divergente exige decisão justificada; o GET não oficializa automaticamente.

## Consulta paginada para Produtos e resultados

O `GET /api/v1/inventory/{inventory}/results` **sem parâmetros** mantém o contrato completo acima, usado pelos diálogos de comandos. Com parâmetros, retorna uma projeção paginada própria para a tabela do detalhe:

| Parâmetro | Regra |
| --- | --- |
| `search` | Até 150 caracteres; código/descrição congelados, sem diferenciar caixa/acentos; `%`, `_` e `\` são literais. Também aceita o ID exato do produto. |
| `result` | `all` (padrão), `divergent`, `pending` ou `aborted`. |
| `page` | Inteiro positivo; padrão 1. |
| `per_page` | 1–100; padrão 30. |

Exemplo: `GET /api/v1/inventory/{inventory}/results?result=pending&page=1&per_page=30`.

A resposta contém `data.inventory_id`, `status`, `review_version`, `rounds`, `products` e `meta` (`current_page`, `per_page`, `total`, `last_page`). Cada produto inclui ID da fotografia (`inventory_product_id`), ID/código/descrição/unidade congelados, depósito, endereços, resultados materializados (`rounds`), fonte `official`, `progress` por rodada, flags `pending`/`aborted`/`terminal_aborted` e `comparison` quando existem duas fontes completas elegíveis.

- Busca e situação são aplicadas **antes** da paginação. Ordenação estável pelo ID da fotografia; apenas os produtos da página têm modelos/evidências detalhadas hidratados. O cálculo de `review_version` continua consultando a projeção mínima integral de concorrência.
- `divergent` usa a diferença decimal entre as duas últimas fontes **completas** de rodadas concluídas; rodadas desconsideradas e abortos não participam. `comparison` informa `difference`, `latest_round` e `previous_round`. Diferença zero indica coincidência, não uma oficialização em GET.
- `pending` encontra ao menos uma tarefa sem confirmação em rodada pendente/em andamento. `aborted` encontra um resultado abortado em rodada concluída ou um aborto terminal; isso não transforma a ausência de quantidade em zero.
- `progress` pode conter resultados imutáveis (`projected: false`) ou leituras de tarefas de rodadas abertas (`projected: true`, `id: null`). A quantidade agregada só existe quando todos os endereços do produto foram confirmados, somados com precisão de centésimos. A soma acima do limite de resultado é `status: overflow`, com quantidade nula. Uma projeção aberta não é uma fonte oficial selecionável.
- Os estados `not_included`, `incomplete`, `complete`, `aborted` e `discarded`/rodada `desconsiderada` permanecem distintos. Zero explícito é a string `0.00`; pendência é `null`.
- As evidências por endereço incluem quantidade/confirmado, identidade congelada, operador atribuído, autor da revisão e horário da confirmação. O catálogo atual não substitui a fotografia.
- A versão continua sendo a revisão **integral**, não o hash de uma página/filtro; os comandos existentes mantêm as mesmas validações. A leitura é protegida pelo mesmo contexto gerencial e não materializa resultados, decisões, eventos ou bloqueios.
- Saldo de referência/diferença de estoque não fazem parte desta resposta.

## Lançamentos e histórico gerencial

`GET /api/v1/inventory/{inventory}/events` continua paginado e mantém `id`, `type`, `actor`, `occurred_at`, `message` e `context`. Parâmetros adicionais:

| Parâmetro | Regra |
| --- | --- |
| `view` | `all` (padrão/contrato legado), `counts` (confirmações/correções) ou `history` (demais eventos). |
| `search` | Até 150 caracteres; produto congelado, ID, endereço, autor ou mensagem; caixa/acentos ignorados e curingas literais. |
| `round_number` | Número inteiro positivo da rodada. |
| `actor_id` | ID inteiro positivo do autor. |
| `type` | `count_recorded` ou `count_corrected`. |
| `page`, `per_page` | Página positiva e tamanho 1–100, padrão 1/30. |

Filtros combinam-se no servidor antes da paginação. `counts` ordena mais recentes primeiro, com desempate por ID; `all`/`history` preservam a ordem cronológica crescente. `view=counts` acrescenta `filters.rounds` e `filters.actors`, restritos aos eventos deste inventário e independentes da página/filtro corrente.

Eventos de contagem recebem `count`: identificação de produto/endereço congelados, unidade, rodada, quantidade, confirmação de zero, justificativa, número de revisão e `current`. Uma correção é uma linha própria; `current: false` identifica uma revisão substituída e **não deve ser somada** à quantidade vigente. Outros eventos têm `count: null`.

Confirmações/correções são gravadas atomicamente pelo comando de contagem e ficam consultáveis **com a rodada aberta**, sem depender da materialização de resultados. A gestão acessa esta consulta; não há exposição de quantidades nas rotas cegas do operador. Parâmetros não suportados ou valores inválidos retornam 422. O contexto/autor continuam obrigatórios.

## Consolidação e decisão terminal

- `GET /api/v1/inventory/{inventory}/consolidation-preview` — projeta todos os produtos, resultados incluídos, produtos abortados, escolhas pendentes e rodadas abertas. Não materializa resultado nem oficializa consenso.
- `POST /api/v1/inventory/{inventory}/consolidate`

```json
{
  "command_id": "8e0397c5-4088-45bd-83e4-9a9f27b9b261",
  "review_version": "<sha256 da prévia>",
  "allow_partial": false
}
```

Dois resultados completos elegíveis mais recentes com quantidades iguais podem ser oficializados somente por este comando. Escolha pendente não pode ser contornada com `allow_partial`. Sem fonte completa, o produto só é abortado com confirmação parcial; ele não é convertido em zero.

- `GET` do preview após consolidação expõe a fonte congelada e a nova `review_version` para a decisão.
- `POST /api/v1/inventory/{inventory}/approve` recebe `command_id` e `review_version`.
- `POST /api/v1/inventory/{inventory}/reject` recebe os mesmos campos e `reason` obrigatório.

A aprovação/reprovação é terminal e atômica com a liberação dos bloqueios pertencentes ao inventário. Não é necessária uma segunda pessoa gestora. A reprovação não reabre a conferência.

## Concorrência e idempotência

Toda escrita de gestão usa uma transação com o cabeçalho do inventário bloqueado, valida novamente o contexto/autor, compara `review_version` e grava um recibo por `command_id`. Repetir exatamente o mesmo comando devolve o recibo com `replayed: true`, inclusive após a decisão terminal. Reutilizar a chave com payload/ator diferente retorna `409 inventory_review_command_reused`; revisão alterada retorna `409 inventory_review_stale` e requer nova prévia. Falha antes do commit reverte resultados, decisão, eventos e liberação de bloqueios.

Campos de ator, quantidade final, status, depósito e seleção de produtos são proibidos nos comandos web. IDs e quantidades de origem são sempre validados no servidor.
