# ENG-3113 — Contrato efetivo do inventário manual

## Contexto e autorização

Todas as rotas usam o prefixo `/api/v1/inventory`, autenticação Sanctum e o setor/nível ativos do token: Expedição, Master ou Administrador. System e outros setores/níveis são negados. A proteção específica precede a Policy para não herdar o bypass global de Master.

Configurar `REX_INVENTORY_EXPEDITION_DEPOT_CODE` na instância. Para a Rex, o valor aprovado é a string `004`; ela mapeia todos os endereços da Expedição. A ausência da configuração retorna 503, sem fallback ou consulta ao ERP. A configuração não deve entrar no cache de desenvolvimento nem ser copiada da instância oficial para testes.

## Rotas

| Método | Sufixo | Uso |
| --- | --- | --- |
| GET | vazio | Rascunhos compartilhados, paginados, mais recentes primeiro |
| POST | vazio | Criar rascunho |
| GET | /{id} | Reabrir seleção e dados, com endereços atuais |
| PUT | /{id} | Editar um rascunho usando sua versão |
| GET | /catalog | Catálogo cadastral elegível |
| GET | /address-groups | Nós da hierarquia com todos os IDs de produtos de cada grupo |
| POST | /scope-preview | Resolver seleção e paginar sua apresentação |

Não há endpoints de início, bloqueio, exclusão, contagem ou ERP nesta entrega.

### Criação e edição

```json
{
  "description": "Conferência manual",
  "notes": "Descrição opcional",
  "type": "ciclico",
  "due_date": "2027-01-15",
  "product_ids": [123, 456]
}
```

Na edição, acrescentar `version` com o valor recebido na última leitura. O backend mantém criador/contexto/situação, atualiza autoria da última alteração e incrementa a versão sob bloqueio curto e transação. Números/códigos são derivados do identificador do servidor, sem contador no cliente.

Tipos: `geral` e `ciclico`; modalidade sempre `manual`; situação inicial `rascunho`. Nome, data válida e ao menos um produto elegível são obrigatórios. Não é exigido prazo futuro, participante, distribuição ou rodada. Campos operacionais/contextuais do cliente são proibidos.

As respostas usam `data`. Detalhe inclui `id`, `code`, `description`, `notes`, `type`, `selection_mode`, `status`, `sector`, `depot_code`, `due_date`, `version`, `created_by`/`updated_by` (somente ID/nome), timestamps, `products_count`, `product_ids` e `scope`.

### Catálogo e grupos

Catálogo aceita `search`, `origin_id`, `family_id`, `page` e `per_page` (1–100, somente limite de apresentação). Retorna produtos paginados em `data`, metadados/links padrão Laravel, `context` e `filters` com famílias/origens elegíveis.

Produtos são identificados por `products.id`. O Resource permite apenas descrição, código/barcode/derivação/empresa disponíveis, unidade, família/origem e endereços cadastrais. Não retorna quantidade, referência, objeto completo de integração ou credenciais.

Grupos retornam nós planos com `id`, `parent_id`, `name`, `hierarchy` e `product_ids` agregados sobre sua descendência. Isso permite seleção parcial sem depender da página do catálogo. Um grupo com nenhum produto tem lista vazia.

### Prévia

```json
{"selector": "all", "per_page": 20, "page": 1}
```

```json
{"selector": "groups", "address_ids": [10, 20]}
```

```json
{"selector": "products", "product_ids": [123, 456], "page": 2, "per_page": 20}
```

Seletores são mutuamente exclusivos. `products` aceita lista vazia para prévia, mas não para salvar. Filtros cadastrais podem restringir descoberta por `all`/`groups`; não restringem os endereços obrigatórios dos produtos resultantes.

Além da página em `data`, a resposta traz `selection`: todos os IDs solicitados/resolvidos, `invalid_products` (ID e razão `not_eligible`), `products_count`, `eligible_products_count`, `product_address_count` (pares produto/endereço) e `address_count` (endereços únicos). `context` informa setor e depósito.

Ao paginar uma prévia, reenviar o seletor/IDs no POST. Um GET de link de paginação não preserva o corpo. O geral obtém todos os IDs por `all`, não pelo primeiro lote de produtos.

### Erros

- 401: autenticação ausente/expirada; preservar o fluxo de sessão existente.
- 403: nível/setor ativo não autorizado.
- 404: inventário inexistente ou fora do contexto, inclusive para Master.
- 422: campos/produtos inválidos; detalhes em `errors`.
- 409 + `inventory_version_conflict`: edição concorrente; não sobrescrever.
- 409 + `inventory_not_draft`: registro não editável.
- 503: mapeamento de depósito indisponível ou endereços alterados durante a leitura; neste último caso, repetir a consulta sem assumir abrangência parcial.

Escritas não são repetidas automaticamente pelo cliente, que limita a comunicação a 30 segundos. Perder a resposta de uma criação não comprova que ela falhou.

## Persistência e evolução

Tabelas: `inventories` e `inventory_products`, com unicidade de inventário/produto/depósito. Produtos/autoria não são removidos por cascata de cadastros. Criar/editar sincroniza cabeçalho e produtos atomicamente.

Endereços são resolvidos pelo produto e por todo o setor mapeado, sem filtro de saldo, rua, posição, categoria ou permissões de retirada. Produtos sem endereço elegível são sinalizados na leitura e recusados na escrita. Novos produtos não são incluídos automaticamente ao reabrir um geral revisado.

A ENG-3114 deve congelar abrangência e ativar bloqueios em seu próprio comando. Esta entrega não cria fotografia, rodada, tarefa ou bloqueio. A ENG-3115 deve ampliar consulta/detalhe sem criar um catálogo/contexto paralelo. APIs operacionais futuras precisam de autorização/Resources próprios, sem ampliar indiscriminadamente o acesso administrativo desta entrega.

## Ambiente e validação

Usar exclusivamente o banco de testes confirmado pelo preflight de `docs/testing-database.md`. A execução desta issue usa PHP 8.4 e PostgreSQL descartáveis, sem vendor compartilhado por symlink e sem .env da instância oficial. Nenhum push, merge em main ou deploy é implícito neste contrato.

A evidência da execução fica em `docs/testing/eng-3113-inventario-manual.md`.
