# ENG-3115 — Plano de implementação da consulta de inventários

**Status:** implementação parcial autorizada; consulta, filtros, opções, histórico inicial e tela de listagem avançados. Divergência e lançamentos permanecem bloqueados pelas fontes das ENG-3116/3117/3118.
**Desenho aprovado:** [Consulta e filtros de inventários](2026-11-05-eng-3115-consulta-inventarios-design.md), commit `13a7f04a`.

## Resultado esperado e limites

Evoluir a listagem e o detalhe persistidos da ENG-3113 para consultar inventários compartilhados, combinar filtros e acompanhar abrangência, resultados, lançamentos e histórico reais do WMS.

Preservar o acesso de Administradores/Masters com sessão ativa na Expedição e o contexto configurável do depósito. Responsável é `created_by`, não o último editor nem o contador. Rascunhos usam a seleção persistida e o cadastro atual; inventários iniciados usam a fotografia da ENG-3114.

Comparar os dois últimos resultados válidos por produto, pela sequência das rodadas. Origem/família/produto e divergência, quando combinados, são satisfeitos pelo mesmo produto. Ausência de comparação não é quantidade zero nem ausência de divergência.

Não implementar contagens, distribuição, decisões, bloqueios, encerramento, dashboard, exclusão, ERP, automação cíclica ou outro cadastro. Não alterar `Rex-Estoque`. A instrumentação dos comandos existentes se limita ao histórico aprovado, sem mudar suas regras operacionais.

## Estado inicial e segurança

- [x] Desenho aprovado por seções, incluindo inspeção do histórico do protótipo.
- [x] Documento de desenho versionado em `13a7f04a`.
- [x] Worktree de documentação `rex-back-eng-3115`, branch `feature/eng-3115`, criada de `bbb18508` sem trocar branches das outras sessões.
- [x] Autorização recebida para avançar usando `feature/inventario`.
- [x] Bases efetivas da ENG-3113/3114 incorporadas: backend `c4056323`, frontend `64b2accd`; worktrees `feature/eng-3115` isoladas.
- [x] Contratos disponíveis registrados em [contracts.md](../validation/eng-3115/contracts.md).
- [ ] Alinhar os modelos de lançamentos/resultados com ENG-3117/3118 antes das tarefas que os consomem; as branches permanecem separadas.

Os nomes e arquivos listados abaixo eram propostas durante o planejamento. As bases entregues da ENG-3113/3114 foram incorporadas e os contratos executados foram reconciliados conforme [contracts.md](../validation/eng-3115/contracts.md); não duplicar modelos/rotas já existentes. As fontes operacionais de contagem/decisão continuam fora desta branch.

Seguir `AGENTS.md` e `docs/testing-database.md`. O projeto exige PHP `^8.4`; o CLI padrão inspecionado é PHP 8.2. Preparar o runtime compatível já previsto pelo projeto antes de executar a aplicação ou Artisan. Não atualizar dependências ou contornar o guard de testes nesta issue.

Antes de testes com banco, no checkout/runtime e ambiente de testes corretos:

```bash
# Somente se a instância descartável precisar ser iniciada:
docker compose --profile test up -d postgres-test
php artisan --env=testing test:database-safety
```

Não executar migrations nem `migrate:fresh` no banco oficial. Não rodar duas suítes que recriem o mesmo schema simultaneamente. URLs, portas, credenciais e mapeamento de depósito continuam configurados por ambiente, sem valores de instância hardcoded.

## Marcos de dependência

| Marco | Pré-requisitos | Evidência possível |
| --- | --- | --- |
| Consulta cadastral e filtros básicos | ENG-3113 entregue | Busca, filtros, paginação e reabertura compartilhada. |
| Consulta de iniciado e evento de início | ENG-3114 entregue | Fotografia histórica e início persistido, sem recalcular o passado. |
| Lançamentos, correções e eventos operacionais | Fontes correspondentes da ENG-3116/3117 | Leituras persistidas e auditoria das operações existentes. |
| Comparação e consulta completa de decisões | Contratos/fontes da ENG-3117/3118 | Dois resultados comparáveis reais, descarte, oficialização e decisões locais. |

A implementação independente pode ser organizada por esses marcos após autorização. Não disponibilizar filtro de divergência sem suporte real no backend, nem declarar o aceite completo com um adaptador que sempre devolve vazio. Uma ausência de resultados apresentada em produção precisa ser comprovada pela leitura bem-sucedida da fonte correspondente.

## Contrato de leitura a consolidar

Prefixo `/api/v1/inventory`, com autorização explícita de contexto em todas as rotas.

| Método/caminho relativo | Conteúdo |
| --- | --- |
| `GET /inventory` | Lista paginada e resumos leves. |
| `GET /inventory/filter-options` | Opções contextuais por `field`, com busca/paginação quando necessário. |
| `GET /inventory/{inventory}` | Cabeçalho e resumos, preservando os contratos de edição/início das dependências. |
| `GET /inventory/{inventory}/products` | Abrangência paginada, endereços e resultados disponíveis. |
| `GET /inventory/{inventory}/entries` | Lançamentos vigentes paginados. |
| `GET /inventory/{inventory}/events` | Eventos cronológicos paginados. |

Listagem: `search`, `status`, `type`, `responsible_id`, `created_from`, `created_until`, `origin_id`, `family_id`, `product_id`, `comparison=divergent`, `page` e `per_page`. O limite de página não limita a abrangência do inventário; adotar máximo de 100 registros por página, sem teto de 100 produtos por inventário.

Opções: `field` em situação/tipo/responsável/origem/família/produto, com os nomes de transporte consolidados na tarefa 1. Usar identidade nativa, não descrições ou IDs compostos do mock. Resolver também o rótulo de um valor aplicado pela URL que não esteja na primeira página de opções.

Resumos de comparação precisam distinguir quantidade de produtos comparáveis, divergentes e sem comparação. Cada comparação informa rodadas, quantidades e diferença; a ausência é explícita, nunca um zero artificial. Os totais da linha representam o inventário completo, mesmo quando apenas um produto motivou sua inclusão no resultado da busca.

Respostas seguem o envelope/paginação existentes. `401/403/404/422` seguem o desenho aprovado. Rejeitar parâmetros inválidos/de ERP e não permitir que setor/depósito da URL substituam o contexto autenticado. Rotas literais vêm antes de `/{inventory}`, com IDs numéricos restritos.

## Roteiro por tarefa

Para cada etapa ainda pendente: teste focal → falha pelo motivo esperado → implementação mínima → teste passando → revisão do diff → commit pequeno com prefixo `ENG-3115`. Rodar Pint antes dos commits backend. Os comandos de cada seção são um roteiro de validação, não substituem os resultados registrados em `docs/validation/eng-3115/README.md`.

### 1. Reconciliar dependências e fechar contratos compartilhados — parcial concluída

**Depende de:** autorização e entrega efetiva da ENG-3113; alinhamento das fontes da ENG-3114/3117/3118.

**Ler/reconciliar:** Models, enums, contexto, middleware/Policy, Requests/Resources, resolvedor de abrangência, comandos de criação/edição/início, serviço frontend e componentes adaptados pelas dependências.

**Novo artefato de execução:** `docs/validation/eng-3115/contracts.md`.

1. Registrar os commits-base de cada repositório e a matriz fonte → campos → consumidor → teste. Preservar a base do protótipo e as mudanças da ENG-3113 no frontend.
2. Fechar os caminhos da API acima, parâmetros, limites, ordenação, rótulos, representação de ausência e códigos de erro. Não renomear o contrato `description`/`notes` do cadastro nem criar um segundo responsável.
3. Confirmar que a fotografia do início conserva identidade, descrição/códigos, origem/família com IDs/rótulos, unidade/precisão e endereços. Se faltar metadado, alinhar a evolução com a ENG-3114; não reconstruir o passado pelo cadastro atual.
4. Consolidar o contrato dos eventos: tipos, ator/nome, horário do servidor, texto/contexto, justificativas, referência à operação e deduplicação de repetições. Confirmar a fronteira transacional de cada produtor.
5. Consolidar com ENG-3117/3118: rodada/ordem/situação, produto e depósito, abrangência esperada, confirmações explícitas, lançamento vigente/correção, aborto, descarte e resultado oficial. Definir a projeção de resultados completos sem criar outro motor de consolidação.
6. Identificar exatamente quais tarefas ficam bloqueadas por fontes ainda não entregues. Não instalar stubs de runtime para contornar essas dependências.
7. Conferir o componente `Filters` e os controles de paginação/acessibilidade efetivamente usados pela ENG-3113. Não refatorar componentes globais por conveniência.

**Saída parcial:** [contracts.md](../validation/eng-3115/contracts.md) registra os contratos atuais e mantém explícitas as fontes bloqueantes de contagem/decisão.

### 2. Busca, validação, filtros e paginação no backend — implementada, faltam revisões finais

**Depende de:** 1 e persistência/acesso da ENG-3113. O predicado de divergência depende também da tarefa 6.

**Novos propostos:**
- `app/Http/Requests/InventorySearchRequest.php`
- `Domain/Inventory/DTOs/InventorySearchDTO.php`
- `Domain/Inventory/Queries/InventorySearchQuery.php`
- `tests/Feature/Inventory/InventorySearchTest.php`
- `tests/Feature/Inventory/InventorySearchDatesTest.php`

**Editar:** `InventoryController.php`, `InventorySummaryResource.php` e rotas existentes, conforme os nomes efetivos.

1. Cobrir número formatado/não formatado e descrição, caixa, acentos, espaços e strings contendo caracteres usados pelo LIKE. Usar a infraestrutura PostgreSQL `unaccent` já existente, sem outra extensão ou SQL interpolado pelo cliente.
2. Testar situação/tipo/responsável e filtros cadastrais isolados e combinados. Responsável consulta `created_by` mesmo após edição por outro usuário.
3. Construir o predicado de origem/família/produto sobre o mesmo produto. Criar o contraexemplo: produto A satisfaz família, produto B satisfaz produto; o inventário não pode entrar na combinação.
4. Usar seleção/metadados vivos somente no rascunho e fotografia após início, respeitando o contrato da tarefa 1. Não restringir a produtos atualmente elegíveis ou a saldo positivo.
5. Normalizar o período no fuso configurado: início inclusivo, fim exclusivo no começo do dia seguinte. Testar fronteiras de meia-noite, final do dia, somente um limite e intervalo invertido, na API e no DTO.
6. Testar paginação e desempate por ID com datas iguais, múltiplos endereços/itens e mais de uma página. Não duplicar inventários nem paginar em memória após carregar tudo.
7. Validar tamanho de página e campos/enums. IDs bem formados sem correspondência retornam vazio; parâmetros de saldo/ERP não ativam predicados legados.

**Validar:** `./vendor/bin/pest tests/Feature/Inventory/InventorySearchTest.php tests/Feature/Inventory/InventorySearchDatesTest.php`, após preflight.

### 3. Opções dinâmicas e abrangência histórica — implementada parcialmente

**Depende de:** 1–2 e fotografia efetiva da ENG-3114 para os casos iniciados.

**Novos propostos:**
- `app/Http/Requests/InventoryFilterOptionsRequest.php`
- `app/Http/Controllers/Inventory/InventoryFilterOptionsController.php`
- `Domain/Inventory/Queries/InventoryFilterOptionsQuery.php`
- `Domain/Inventory/Queries/InventoryScopeReadQuery.php`
- `tests/Feature/Inventory/InventoryFilterOptionsTest.php`
- `tests/Feature/Inventory/InventoryHistoricalScopeTest.php`
- `tests/Feature/Inventory/InventoryReadQueriesTest.php`

**Editar:** Resources de resumo/produto e `routes/api.php`.

1. Testar opções originadas dos inventários consultáveis, não só da página carregada ou do catálogo de novos inventários. Incluir responsável fora da página e produto histórico sem vínculo elegível atual.
2. Testar mudança de família/origem, descrição e endereços após início. A consulta histórica conserva os dados da fotografia; o rascunho continua mostrando o cadastro atual e suas inconsistências.
3. Testar dependências origem → família → produto, busca/paginação das opções e recuperação do valor selecionado pela URL fora da primeira página. Não carregar todos os produtos para popular um select.
4. Retornar tipos/situações dos enums e fluxos reais disponíveis, sem copiar `inventoryKinds`/`statusLabels` do mock.
5. Contar produtos/endereço em lote e deduplicar vínculos. O resumo da lista não envia todos os endereços, e seus totais não são reduzidos pelos filtros de descoberta.
6. Registrar contagem/plano de consultas com dados de cardinalidade maior, identificar N+1 e medir índices necessários antes de criá-los. Não alterar tabelas de estoque sem necessidade demonstrada.
7. Cobrir todos os novos endpoints com as verificações de contexto da ENG-3113, inclusive Master em outro setor e IDs fora do contexto.

**Validar:** testes novos e suíte de acesso Inventory existente.

### 4. Eventos persistidos de cadastro/início — implementada parcialmente

**Depende de:** 1 e comandos efetivos da ENG-3113/3114.

**Novos propostos, somente se não houver equivalente entregue:**
- `database/migrations/<timestamp>_create_inventory_events_table.php`
- `app/Models/Inventory/InventoryEvent.php`
- `Domain/Inventory/DTOs/InventoryEventDTO.php`
- `Domain/Inventory/Services/InventoryEventStoreService.php`
- `tests/Unit/Inventory/InventoryEventSchemaTest.php`
- `tests/Feature/Inventory/InventoryEventsTest.php`

**Editar:** relações/factories de inventário, `InventoryDraftStoreService.php`, `InventoryDraftUpdateService.php`, `InventoryStartService.php` ou equivalentes. Não duplicar comandos das dependências.

1. Testar schema, vínculos que preservem histórico, índices de leitura cronológica e rollback restrito à nova tabela. Conservar somente contexto mínimo estruturado, não snapshots integrais ou payloads de API.
2. Registrar criação/edição/início na mesma transação do comando, com autoria/nome e horário reais do servidor. Textos precisam corresponder à ação real: não alegar troca de responsável, saldo de referência ou abertura de rodadas no início.
3. Provar rollback do comando sem evento órfão e repetição idempotente do início sem evento duplicado. Manter as versões e regras de concorrência das dependências.
4. Preservar produto/endereço/rodada/antes/depois/motivo nos eventos de correção produzidos pela ENG-3117. Não escrever um comando de correção nesta tarefa.
5. Integrar eventos operacionais somente quando seus produtores existirem; os donos de distribuição/contagem/decisões implementam essas emissões. Não confundir a auditoria de tentativa bloqueada da ENG-3114 com lançamento de contagem.
6. Decidir o rollout antes da execução. Não fabricar eventos antigos usando `updated_at` nem importar o storage do protótipo. Registrar eventual limitação de registros anteriores à instrumentação.

**Validar:** schema/eventos e regressão dos comandos instrumentados. Comparar os resultados de criação/edição/início antes e depois para confirmar que somente a auditoria foi acrescentada.

### 5. Recursos paginados de detalhe e histórico — eventos iniciais disponíveis; lançamentos bloqueados

**Depende de:** 3–4. A leitura de lançamentos depende da fonte efetiva da ENG-3117; resultados oficiais/decisões dependem da ENG-3118.

**Novos propostos:**
- `app/Http/Controllers/Inventory/InventoryReadController.php`
- `Domain/Inventory/Queries/InventoryEntriesQuery.php`
- `Domain/Inventory/Queries/InventoryEventsQuery.php`
- `Domain/Inventory/Resources/InventoryEntryResource.php`
- `Domain/Inventory/Resources/InventoryEventResource.php`
- `tests/Feature/Inventory/InventoryDetailReadTest.php`
- `tests/Feature/Inventory/InventoryEntriesReadTest.php`
- `tests/Feature/Inventory/InventoryEventsReadTest.php`

**Editar:** `InventoryResource.php`, Resource de produtos e rotas, reutilizando recursos equivalentes se já existirem.

1. Consultar cabeçalho e aba separadamente, sem carregar eventos/lançamentos completos para montar o resumo. Preservar o contrato de reabertura/versão necessário à edição e ao início.
2. Produtos e endereços vêm da leitura da tarefa 3. Um detalhe aberto a partir de filtros continua mostrando a abrangência completa, inclusive inconsistências cadastrais do rascunho.
3. Lançamentos mostram rodada, produto, endereço, quantidade vigente, operador e data/hora. Correção não soma a versão anterior; distinguir eventos de correção do registro vigente.
4. Eventos são ordenados por horário + ID, do mais antigo ao mais recente, com paginação acessível. Testar horários iguais, nomes preservados, textos/contexto e justificativas.
5. Excluir credenciais, parâmetros completos de integração e campos ERP das projeções. Não gerar resultados oficiais ou eventos de decisão a partir de deduções da consulta.
6. Proteger todos os sub-recursos por contexto, sem vazamento por IDs aninhados. Testar `401/403/404`, validação e envelopes de erro reais.

**Validar:** testes novos e regressão do detalhe da ENG-3113/3114.

### 6. Comparações reais entre rodadas e filtro de divergência — bloqueada

**Depende de:** 1–3 e fontes/modelos entregues pela ENG-3117/3118. Enquanto ausentes, esta tarefa e seu aceite integrado permanecem bloqueados.

**Novos propostos:**
- `Domain/Inventory/Queries/InventoryComparisonQuery.php`
- `Domain/Inventory/Resources/InventoryProductResultResource.php`
- `tests/Feature/Inventory/InventoryComparisonTest.php`
- `tests/Feature/Inventory/InventoryComparisonFilterTest.php`

**Editar:** `InventorySearchQuery.php`, queries/resources de resumo e detalhe. Reutilizar a projeção autoritativa de completude/resultados da ENG-3118, sem novo motor concorrente.

1. Montar dados persistidos de rodadas independentes, endereços esperados, confirmações, correções, descartes e abortos. Fixtures são exclusivas dos testes; não entram no runtime.
2. Testar `10 → 12 → 12`: comparação atual da última dupla igual a zero, com resultados antigos preservados. Cobrir diferença positiva/negativa e somente um resultado elegível.
3. Testar resultado apenas após rodada concluída e todos os endereços confirmados; zero explícito é resultado, ausência não. Rodadas desconsideradas e resultados abortados não participam.
4. Testar recontagem parcial sem o produto e rodadas encerradas fora da sequência temporal. Selecionar a última dupla por produto pela sequência da rodada, não pelos dois últimos eventos globais nem pelo horário de conclusão.
5. Detectar incompatibilidade de produto/depósito/unidade/abrangência. Não inventar conversão ou usar uma dupla antiga para esconder uma inconsistência da fonte.
6. Calcular diferença no backend com precisão decimal do produto, sem regra fixa herdada da fixture ou comparação por float no cliente.
7. Compartilhar a regra de elegibilidade/última dupla entre lista, detalhe e filtro. Resolver em lote; se usar janela/CTE, particionar por inventário/produto/depósito e filtrar resultados elegíveis antes de ordenar.
8. Testar divergência no mesmo produto do predicado cadastral. Diferença em outro produto não satisfaz a combinação; totais da abrangência permanecem íntegros.
9. Cobrir resumo parcialmente comparável: zero divergências entre os comparáveis não significa inventário inteiro comparado. Não oficializar resultados por concordância.

**Validar:** testes novos, busca, detalhe e regressão da projeção de resultados da ENG-3118. Só liberar o filtro e marcar esse aceite após integração real.

### 7. Transporte frontend e estado de consulta pela URL — implementada parcialmente

**Depende de:** 1–3; métodos de resultados/lançamentos são integrados com as fontes reais das tarefas 5–6.

**Novos propostos em `src/pages/Inventory/`:** `query.mjs`, `query.test.mjs`, `read.mjs`, `read.test.mjs` e hooks locais de leitura conforme a composição efetiva.

**Editar:** `src/domain/Inventory/services/InventoryService.jsx`, helpers `wms.mjs` e teste de isolamento da ENG-3113.

1. Testar serialização/normalização de busca, filtros, página, datas e IDs; a URL guarda somente estado da consulta, sem tokens ou identidade arbitrária de contexto.
2. Modelar separadamente filtros aplicados e pendentes do painel. Aplicar/Limpar atualiza a URL; nova consulta retorna à primeira página; voltar/avançar restaura o estado aplicado.
3. Preservar o contexto da lista ao abrir/voltar do detalhe, inclusive pelo breadcrumb. Acesso direto ao detalhe permite retorno seguro à lista; não aceitar redirecionamento externo da URL.
4. Reutilizar o cliente HTTP e tratamento de sessão existentes. Cancelar/ignorar respostas antigas por consulta/ID/sessão; preservar filtros no retry e não mostrar dados de outro contexto.
5. Testar representação de loading/vazio/erro e ausência de comparação versus zero. O cliente apresenta resultados do servidor, sem recalcular divergência ou oficialização.
6. Atualizar o guard do grafo alcançável para impedir fixture, store, motor local e dependências transitivas. Não proibir o storage legítimo de autenticação fora da feature.

**Validar:** testes unitários focais de consulta/leitura e isolamento, sem iniciar servidor ou carregar dados de negócio.

### 8. Listagem gerencial com filtros reais — implementada, evidências em validação

**Depende de:** 2–3 e 7. O controle de divergência só é disponibilizado com a tarefa 6 concluída.

**Editar:** `src/pages/Inventory/InventoryList.jsx`, `Inventory.jsx` e `Inventory.css`; criar componente local de filtros somente se necessário.

1. Preservar busca visível, painel Aplicar/Limpar, contador de filtros, link de inventário e tabela. Buscar número/descrição com debounce curto sem descartar filtros pendentes.
2. Carregar opções reais sob demanda, com estados de loading/erro/vazio e controles pesquisáveis/paginados para coleções grandes. Manter os rótulos selecionados após recarga da URL.
3. Manter origem/família/produto coerentes e seleção simples. Não usar os componentes globais de busca se exigirem catálogo/elegibilidade ou comportamento incompatível.
4. Remover opção/predicado de estoque/ERP e modalidades não entregues. Não copiar arrays do mock para aparentar dinamismo.
5. Mostrar as colunas e resumos aprovados, com contagens do backend. Diferenciar sem comparação de zero divergências e não pré-carregar todos os resultados para renderizar a lista.
6. Paginação acessível, ordenação estável e estados distintos de lista vazia/sem correspondências. Cancelar respostas tardias e preservar query no retry.
7. Validar Tab/Enter, labels, foco no painel, aplicação/limpeza, retorno do detalhe e larguras 390/1280/1440.

**Validar:** testes de helpers e E2E focais da tarefa 10; não certificar consulta real apenas com interceptações.

### 9. Detalhe equivalente ao protótipo, sem motor local — parcial (Produtos e Histórico)

**Depende de:** 5 e 7; apresentação de resultados completos depende também de 6.

**Novos ou adaptar conforme a dependência:** `InventoryDetail.jsx`, `InventoryProducts.jsx`, `InventoryEntries.jsx` e `InventoryHistory.jsx` em `src/pages/Inventory/`.

**Editar:** composição em `Inventory.jsx`, CSS e identidade/endereço de produto somente quando necessário. O `Results.jsx` legado não pode trazer `model.mjs`/fixture para o runtime persistido.

1. Preservar cabeçalho e abas Produtos e resultados/Lançamentos/Histórico, com seleção acessível e recursos carregados por aba. Paginação não exige carregar todo o inventário.
2. Mostrar abrangência completa, metadados reais e inconsistências do rascunho; após início, usar a fotografia. Preservar expansão de endereços e busca/controles de produto compatíveis com os dados efetivamente entregues.
3. Mostrar somente rodadas existentes e distinguir pendente, não incluído, abortado, desconsiderado e zero. Resultado oficial é leitura explícita, sem escolha ou inferência nesta feature.
4. Exibir a dupla comparada, diferença e resumo de comparabilidade do servidor. Remover colunas/filtros de saldo, diferença ERP e regularização.
5. Histórico mantém autor, data/hora e texto contextual. Correção mostra antes/depois/motivo; decisões mostram suas justificativas. Lançamentos mostram o valor vigente, sem duplicar quantidades históricas.
6. Preservar as ações de edição/início entregues pela ENG-3113/3114 e suas permissões, sem reimplementá-las. Não montar app simulado, aprovação local de protótipo, parametrizações ou decisões antecipadas.
7. Tratar erro por aba sem convertê-lo em vazio/zero e sem trocar a abrangência por catálogo atual. Validar links, teclado/foco e rolagem interna no mobile.

**Validar:** testes de leitura/isolamento e E2E focais do detalhe; comparar a apresentação com o protótipo no recorte aprovado.

### 10. Testes de UI, integração real e evidências — UI interceptada avançada; smoke real pendente

**Depende de:** tarefas anteriores, com fontes operacionais entregues para os cenários de comparação.

**Novos propostos em `rex-front/e2e/inventory/persisted/`:** `query.spec.mjs`, `detail.spec.mjs`, `history.spec.mjs`, `comparisons.spec.mjs`; complementar setup/fixtures, `errors.spec.mjs` e README existentes da ENG-3113.

**Novo registro:** `docs/validation/eng-3115/README.md` no repositório apropriado às evidências. URLs/portas/contas são configuradas por ambiente; não versionar credenciais.

1. UI interceptada: testar busca, todas as combinações, contraexemplo de produtos diferentes, datas, opções fora da página, Aplicar/Limpar, URL/recarga/back/forward e detalhe completo. Usar fixtures sintéticas somente nessa camada.
2. UI interceptada: testar comparação ausente versus igualdade, diferença, `10 → 12 → 12`, produto incompleto, aborto, descarte e rodada parcial. A apresentação usa a resposta do servidor; essas interceptações não comprovam sua regra de negócio.
3. Testar erros e respostas fora de ordem em lista/opções/abas, troca de sessão/contexto e retry sem perda da consulta. Falha não pode aparecer como sucesso vazio.
4. Instrumentar rede/storage para confirmar ausência de ERP e chaves locais de inventário. Não usar o setup legado que bloqueia toda API de negócio e injeta cenários em storage para certificar o fluxo persistido.
5. Smoke real em ambiente descartável/autorizado: usuário A cria/edita pelos comandos entregues; B localiza por filtros, abre e reabre após refresh. Validar iniciado com fotografia e evento real de início.
6. Com ENG-3117/3118 entregues, preparar rodadas/lançamentos pelos comandos de domínio/API reais em ambiente de testes e consultar com outra identidade autorizada. Conferir última dupla, histórico de correção, descarte e resultado oficial persistido. Não inserir resultados no navegador nem alegar que dados interceptados provaram integração.
7. Capturar lista filtrada, detalhe, lançamentos, histórico, comparação e estados relevantes em 390/1280/1440. Validar teclado, foco, rolagem interna e ausência de overflow da página.
8. Registrar separadamente testes de UI, integração backend, smoke browser real e cenários bloqueados/não executados. Falta de fonte de contagem ou ambiente real mantém o respectivo aceite pendente.

### 11. Regressão e revisão final — pendente

**Depende de:** todas as anteriores para declarar a entrega completa.

Backend, no runtime PHP compatível e depois do preflight:

```bash
php artisan --env=testing test:database-safety
./vendor/bin/pest tests/Feature/Inventory tests/Unit/Inventory
./vendor/bin/pint --dirty
composer test-safe
```

Frontend, na worktree da entrega:

```bash
node --test src/pages/Inventory/*.test.mjs
npm test
# ESLint focal dos arquivos alterados, depois lint geral se viável:
npm run lint
npm run build
npx playwright test --config=e2e/inventory/playwright.config.mjs
```

1. Confirmar que a configuração Playwright coleta os cenários persistidos, não a suíte antiga de cenários locais. Revisar os testes de permissões/menu/rotas e o grafo do bundle.
2. Revisar regressões de cadastro/início e dos produtores instrumentados. A regra de consulta A não modifica decisões ou condições de oficialização da ENG-3118.
3. Confirmar ausência de chamadas/colunas/filtros ERP, saldos fictícios e persistência de inventários no navegador. Nenhuma consulta altera estoque ou bloqueios.
4. Executar `git diff --check`, revisar arquivos/stats por repositório e manter commits restritos à issue. Não corrigir falhas preexistentes alheias para ocultar resultados.
5. Registrar comandos, resultados efetivos e limitações. Só marcar o aceite de divergência depois de validar resultados persistidos reais; não encerrar a issue apenas com UI/mock.

## Checklist de aceite da execução

- [x] Busca por número formatado/não formatado e descrição com caixa/acentos; testes PostgreSQL incluem escapes de LIKE.
- [x] Filtros básicos de situação, tipo, responsável, período, origem, família e produto combináveis no backend.
- [x] Predicados de origem/família/produto correspondem ao mesmo produto; comparação de divergência ainda não disponível.
- [x] Opções reais e históricas, sem depender da página carregada ou do catálogo elegível atual; pesquisa/paginação dinâmica.
- [x] Paginação/ordenação estáveis, consulta na URL e retorno do detalhe preservado.
- [x] Rascunho usa cadastro atual; iniciado conserva a fotografia da ENG-3114.
- [ ] Dois últimos resultados válidos por produto e filtro de divergência; depende de resultados persistidos reais.
- [ ] Lançamentos vigentes e histórico operacional completo, incluindo correções/justificativas; depende das ENG-3117/3118.
- [x] Eventos de criação/edição/início são atômicos, autoria real, início idempotente e sem reconstrução do passado.
- [x] API/contexto protegidos e dados compartilhados entre usuários autorizados.
- [x] Sem ERP, saldo de referência, fixture/store local de inventário ou alteração no aplicativo nativo.
- [ ] Regressão total, smoke real e evidências de acessibilidade/responsividade ainda pendentes.
- [ ] Dependências funcionais resolvidas; aceites não comprovados permanecem pendentes.

## Nota histórica

O plano foi preparado manualmente após o desenho aprovado e a inspeção dos repositórios/planejamentos da ENG-3113/3114; a skill `writing-plans` não estava instalada. A implementação começou depois da autorização explícita para usar as entregas já integradas em `feature/inventario`. As tarefas dependentes de fontes ainda ausentes continuam pendentes, não foram substituídas por stubs.
