# ENG-3115 — Contratos consolidados até a implementação parcial

## Bases incorporadas

- Backend: `c4056323` (`feature/inventario`, com ENG-3113/ENG-3114).
- Frontend: `64b2accd` (`feature/inventario`, com ENG-3113/ENG-3114).
- As worktrees das demais entregas não foram alteradas nem incorporadas.

## Rotas e leitura disponíveis

Todas as rotas ficam sob `/api/v1/inventory`, com `auth:sanctum` e `EnsureInventoryManagementAccess`; a Policy também verifica o setor/depósito ativo antes de ler inventários e sub-recursos.

| Método/caminho | Conteúdo e estado |
| --- | --- |
| `GET /inventory` | Lista paginada com resumo; implementada nesta entrega parcial. |
| `GET /inventory/filter-options` | Opções dependentes de inventários consultáveis, por `field`; implementada. |
| `GET /inventory/{id}` | Cabeçalho e abrangência completa conforme ENG-3113/3114. |
| `GET /inventory/{id}/events` | Histórico persistido paginado; nesta etapa registra criação, edição de rascunho e início. |
| Lançamentos/resultados | Ainda sem endpoint nesta branch; dependem das fontes de contagem/decisão correspondentes. |

Rotas literais precedem a rota numérica do inventário. A paginação usa `page >= 1`, `per_page` padrão 30 e máximo 100. A lista ordena por ID decrescente, sem joins que multipliquem inventários. Eventos ordenam por `occurred_at`, depois `id`, do mais antigo ao mais recente.

## Busca e filtros da lista

Parâmetros aceitos em `GET /inventory`:

`search`, `status`, `type`, `responsible_id`, `created_from`, `created_until`, `origin_id`, `family_id`, `product_id`, `page`, `per_page`.

- `search` é opcional e aceita `null`/string vazia como ausência de busca; o frontend omite parâmetros vazios na requisição.
- Tipo é validado contra o enum atual. Situação é validada contra `InventoryStatusEnum`, com os sete estados do protótipo. `iniciado` é o valor persistido correspondente a “Em contagem”; `conferencia`, `aguardando` e `concluido` são filtros aceitos e retornam zero enquanto não houver registros nesses estados.
- `responsible_id` corresponde a `created_by`, não a `updated_by` ou ao contador.
- A busca usa `unaccent`/`ILIKE` na descrição e reconhece ID ou código `INV-...`; `%`, `_` e `\\` são escapados como texto literal.
- Datas usam `app.timezone`: início inclusivo no início do dia e fim inclusivo convertido em limite exclusivo no início do dia seguinte. Intervalo invertido retorna `422`.
- Origem, família e produto são combinados no mesmo vínculo de produto. Rascunhos consultam o cadastro atual; inventários iniciados consultam IDs e rótulos da fotografia.
- Parâmetros desconhecidos são rejeitados. Portanto `comparison`, saldo e nomes de filtros ERP não ativam predicados alternativos; comparação permanece indisponível até integração com resultados persistidos reais.

## Opções de filtros

`GET /inventory/filter-options?field=...` aceita `status`, `type`, `responsible`, `origin`, `family` ou `product`, mais `search`, `search_by`, `origin_id`, `family_id`, `page` e `per_page` conforme o campo. `search_by` é `all|id|name` para responsável/origem/família e `all|id|code|description` para produto.

- Situações vêm do enum estático do backend, independentemente de já existirem inventários em cada estado; tipos vêm do enum de tipos.
- Responsáveis são autores (`created_by`) de inventários consultáveis.
- Origem/família/produto derivam dos vínculos de inventário consultáveis, sem depender da página atual nem do catálogo elegível de novos cadastros.
- Valores iniciados usam a fotografia; rascunhos usam o cadastro atual.
- Opções dinâmicas suportam busca pelo critério escolhido, paginação e resolução de um ID aplicado pela URL fora da primeira página. `search_by=all` mantém a correspondência combinada anterior.
- Os campos pesquisáveis do painel usam o `SearchFilter` compartilhado e um seletor semântico (ID/nome ou ID/código/descrição); cada filtro tem uma única label visível. A busca geral da lista continua combinada.
- A resposta está sob o envelope `data`; opções paginadas também incluem `meta`/`links` do Laravel.

## Eventos persistidos desta etapa

`inventory_events` preserva ID/autor textual, tipo, mensagem, contexto estruturado e horário do servidor. O vínculo com inventário e ator restringe exclusão física; a emissão ocorre na mesma transação do comando.

- `draft_created`: tipo, descrição e quantidade de produtos.
- `draft_updated`: campos alterados e quantidades anterior/nova; não copia a seleção inteira.
- `started`: produtos e endereços fotografados; não afirma abertura de rodadas de contagem.
- Repetição idempotente do início não cria segundo evento. Falha ao persistir evento reverte o comando e a fotografia/locks da transação.
- Eventos anteriores à instrumentação não são reconstruídos a partir de `updated_at` nem do protótipo.
- Eventos de contagem, correção, distribuição, descarte ou decisão ainda dependem dos produtores das ENG-3116/3117/3118.

## URL e detalhe frontend

A lista guarda somente critérios e página na URL; busca usa debounce, filtros pendentes sobrevivem a consultas da lista e Aplicar/Limpar volta à primeira página. A requisição não envia parâmetros vazios. Em falha da lista, busca/filtros permanecem acessíveis com mensagem inline, sem ações de retry/retorno nem estado vazio enganoso; editar/aplicar critérios dispara nova consulta. Abrir um inventário e retornar pelo breadcrumb conserva a consulta. O detalhe expõe abas Produtos e Histórico; lançamentos e comparações não são simulados nem apresentados como zero/ausência.

## Limites do aceite

Esta branch entrega consulta/paginação/opções e histórico inicial. O filtro de divergência, lançamentos vigentes, correções e histórico operacional completo continuam bloqueados até reconciliação das fontes reais das entregas de contagem/decisão. Nenhuma consulta usa fixtures em runtime, saldo/ERP ou armazenamento local de inventários; nenhuma operação desta feature altera estoque.
