# ENG-3115 — Consulta e filtros de inventários

**Status:** desenho aprovado por seções em 2026-11-05; somente planejamento, sem autorização para implementar.
**Issue:** https://linear.app/soelx/issue/ENG-3115/consultar-e-filtrar-inventarios

## Objetivo

Permitir à gestão encontrar inventários persistidos e consultar sua abrangência, situação, resultados, lançamentos e histórico compartilhados no WMS. Evoluir a listagem e o detalhe da ENG-3113, sem outro cadastro, base paralela, cenários locais ou dependência de saldos e ajustes do ERP.

## Contexto e isolamento

- A ENG-3113 tem desenho e plano aprovados, mas ainda não possui implementação no checkout inspecionado. Sua listagem básica será a base desta entrega.
- A ENG-3114 define início, fotografia operacional e bloqueio obrigatório de movimentações. Não produz rodadas ou resultados.
- As ENG-3116/3117/3118 produzem distribuição, contagens, resultados e decisões. A ENG-3115 apenas consulta esses dados; não antecipa suas operações.
- O contexto continua sendo Administrador/Master com sessão ativa na Expedição. O depósito 004 é configuração da instância estabelecida pela ENG-3113, nunca constante de consulta nem escolha arbitrária do cliente.
- A worktree de documentação `rex-back-eng-3115`, branch `feature/eng-3115`, foi criada de `bbb18508`, contendo o planejamento da ENG-3113 sobre a base backend `a6b49a5f`. Não houve troca de branch nas worktrees das outras sessões.
- A documentação da ENG-3114 foi consultada na worktree `rex-back-eng-3114`, então em `60600299`. Não foi copiada ou alterada por esta atividade.
- O frontend inspecionado está em `67305ddb`, base do protótipo `eng-2966`, na branch da ENG-3113. A futura implementação frontend deve partir da entrega efetiva dessa dependência, não presumir que o protótipo está na `main`.

Os nomes de arquivos e contratos novos devem ser reconciliados com as implementações efetivas das dependências. Este desenho não autoriza implementá-las nem editar seus planejamentos em andamento.

## Abordagens consideradas

1. **Estender a API de inventários e reutilizar a interface — escolhida.** Consultas, filtros e resumos no backend, com paginação e recursos de detalhe. Preserva permissões e componentes e reduz duplicação.
2. **Criar estrutura de leitura separada.** Facilita otimizações futuras, mas exige sincronização e manutenção de projeções sem necessidade demonstrada nesta etapa.

Não criar projeção assíncrona, event sourcing, outro cliente HTTP ou framework genérico de filtros.

## Decisões aprovadas

1. A entrega é de consulta. Não cria contagens nem toma decisões operacionais.
2. Divergência atual compara os **dois últimos resultados válidos por produto**, pela sequência das rodadas. Em `10 → 12 → 12`, a diferença atual é zero; os valores anteriores permanecem consultáveis.
3. Origem, família e produto são satisfeitos pelo **mesmo produto** da abrangência. Quando aplicado, o filtro de divergência também deve ser satisfeito por esse produto.
4. Responsável corresponde ao criador (`created_by`), preservado nas edições. Não significa operador da rodada nem último editor.
5. Preservar busca visível, painel Aplicar/Limpar e organização do detalhe do protótipo. Não simplificar o conteúdo do histórico.
6. Busca, filtros e página ficam na URL; abrir e voltar do detalhe preserva o contexto da listagem.
7. Filtros localizam inventários, mas não recortam sua abrangência no detalhe.
8. Falha de consulta, ausência de resultados e ausência de divergência são estados distintos.
9. O aceite integrado das divergências depende de resultados reais das entregas de contagem. Mocks não encerram esse aceite.

## 1. Arquitetura, acesso e fontes de dados

Evoluir o contexto de inventário da ENG-3113, seguindo Models, DTOs, Requests, Resources, queries e serviços de domínio existentes. Resolver busca, filtros, paginação e resumos no servidor. A listagem não precisa carregar todos os inventários, produtos ou lançamentos no navegador.

Manter acesso compartilhado entre Administradores e Masters com sessão ativa na Expedição. Autorizar explicitamente cada endpoint, inclusive opções de filtro e sub-recursos. Não depender de um bypass global de Master, do criador ou somente do menu. IDs fora do contexto não revelam dados.

### Abrangência cadastral e fotografia

| Estado | Fonte da abrangência consultada |
| --- | --- |
| Rascunho | Seleção persistida pela ENG-3113, com metadados e endereços atuais do WMS; inconsistências continuam visíveis. |
| Iniciado ou posterior | Fotografia persistida pela ENG-3114, sem recalcular o passado pelo catálogo atual. |

Produtos e endereços históricos não desaparecem por mudanças no cadastro. O contrato da fotografia precisa conservar identidade, códigos/descrição, unidade/precisão e identificação/rótulos de origem e família necessários à consulta. Alinhar esse requisito com a ENG-3114 antes da implementação, sem construir outra fotografia nesta issue.

As opções dos filtros são obtidas dos inventários e abrangências consultáveis no contexto, não apenas do catálogo elegível para novos cadastros. Responsáveis podem aparecer mesmo sem terem criado um registro na página atual. Produtos históricos continuam localizáveis fora do catálogo elegível atual.

Projetar somente campos necessários. Não devolver saldos de referência, ajustes, credenciais ou parâmetros completos de integração.

## 2. Busca e filtros

### Regras

- Buscar por número, com ou sem formatação, ou descrição. Não distinguir caixa e acentos; usar parâmetros de consulta, sem SQL montado pelo cliente.
- Combinar por AND: situação, tipo, responsável, inclusão de/até, origem, família, produto e resultado divergente entre contagens.
- Preservar seleção simples dos filtros do protótipo; não introduzir múltipla seleção nesta entrega.
- Tipos e situações vêm do domínio WMS entregue. No recorte inicial, geral e cíclico manual; não oferecer automação ou situações exclusivas da simulação.
- Origem/família/produto pertencem ao mesmo produto. Não aceitar uma família de um produto e um produto de outra família apenas porque ambos estão no inventário.
- Com filtro de divergência, exigir diferença atual não zero em um produto que também satisfaça os filtros cadastrais preenchidos.
- Remover as opções e predicados de divergência com estoque/ERP. Não criar filtros por saldo, endereço ou depósito.
- O período é inclusivo no fuso configurado da aplicação. Implementar o limite superior como início do dia seguinte convertido para o armazenamento temporal, sem perder registros no fim do dia. Sem período implícito.
- Intervalo inválido é sinalizado antes da consulta e também recusado pela API. Parâmetros malformados são inválidos; valores de identidade bem formados sem correspondência não revelam dados e produzem consulta vazia.

Usar um único predicado de produto na consulta, por exemplo `EXISTS`, compartilhado com os resumos pertinentes. Deduplicar inventários e produtos apesar de múltiplos endereços, itens ou rodadas.

### Interface da listagem

- Preservar busca visível e painel com Aplicar/Limpar. A busca pode usar debounce curto; filtros pendentes não alteram a consulta antes de Aplicar.
- Manter origem/família coerentes e as opções selecionadas identificáveis mesmo fora da página atual de opções.
- Mostrar número, descrição, responsável, inclusão, tipo, situação, prazo, resumo da abrangência e acompanhamento das contagens quando disponível.
- Exibir famílias/resumos sem carregar toda a abrangência na resposta da lista. Os totais da linha representam o inventário inteiro, não apenas o produto usado para encontrá-lo.
- Paginar no servidor, com ordem estável pelos mais recentes (`created_at` e identificador como desempate). Mudar busca/filtros retorna à primeira página.
- Serializar filtros aplicados, busca e página na URL. Suportar recarga, voltar/avançar do navegador e retorno pelo detalhe, sem storage de inventários. Não misturar contexto de outra sessão/setor.
- Preservar link identificável, navegação por teclado e rolagem interna da tabela.
- Distinguir ausência de inventários de ausência de correspondências aos filtros.

## 3. Contrato de leitura e fluxo de dados

Reutilizar o prefixo `/api/v1/inventory` e o transporte frontend da ENG-3113. Os seguintes caminhos são uma proposta a consolidar com seus controllers/resources efetivos:

| Método e caminho relativo | Responsabilidade |
| --- | --- |
| `GET /inventory` | Listagem gerencial paginada, filtros e resumos leves. |
| `GET /inventory/filter-options` | Opções contextuais de situação, tipo, responsável, origem, família ou produto, com busca/paginação quando necessário. |
| `GET /inventory/{inventory}` | Cabeçalho persistido, contexto, autoria, situação e resumos; preservar o contrato necessário à edição/início. |
| `GET /inventory/{inventory}/products` | Abrangência paginada e resultados por produto/rodada quando existentes. |
| `GET /inventory/{inventory}/entries` | Lançamentos vigentes paginados, com autoria e vínculos. |
| `GET /inventory/{inventory}/events` | Histórico cronológico paginado. |

Registrar caminhos literais antes de `/{inventory}` e restringir os identificadores. Não duplicar um sub-recurso equivalente caso a dependência já o tenha implementado.

Parâmetros propostos da listagem: `search`, `status`, `type`, `responsible_id`, `created_from`, `created_until`, `origin_id`, `family_id`, `product_id`, `comparison=divergent`, `page` e `per_page`. Limitar o tamanho de página no servidor. `responsible_id` consulta `created_by`; não cria outro campo de responsável.

O endpoint de opções pode receber `field`, busca e os filtros cadastrais necessários à dependência origem/família/produto. Não reduzir as opções à página de inventários carregada nem exigir carregar todo o catálogo. Tipos/situações usam enums e fluxos reais do backend, não o `statusLabels` do mock.

Fluxo: URL → validação/normalização → API de listagem → página e totais → abertura por ID → cabeçalho → recurso da aba ativa. Cabeçalho, produtos, lançamentos e histórico têm estados de carregamento/erro próprios. Não pré-carregar todos os eventos ou lançamentos para montar uma linha da lista.

Nenhum endpoint novo altera inventários ou estoque. O novo registro de eventos é interno aos comandos de origem, não uma rota de escrita pelo navegador.

## 4. Detalhe e comparação

Manter as abas **Produtos e resultados**, **Lançamentos** e **Histórico**. Abrir o detalhe sempre apresenta o inventário completo; os filtros da lista não excluem produtos dele.

### Produtos e resultados

- Apresentar identidade, unidade e endereços, usando a fonte correta para rascunho/iniciado.
- Sinalizar inconsistências de rascunho sem remover produtos silenciosamente.
- Exibir apenas rodadas reais, sem três colunas artificiais obrigatórias. Rodadas desconsideradas permanecem identificadas para consulta.
- Distinguir pendente/incompleto, não incluído, abortado, desconsiderado e resultado zero explícito.
- Mostrar resultado oficial somente quando registrado pelo fluxo de conferência; não inferi-lo da concordância, da última rodada ou do saldo.
- Preservar expansão dos endereços e identificação de quantidades/operadores quando os dados correspondentes existirem.

### Comparabilidade

Um resultado é elegível quando a rodada está concluída e todos os endereços esperados daquele produto possuem confirmação explícita, inclusive zero. Não usar totais parciais, produtos abortados ou rodadas desconsideradas. Correções substituem o lançamento vigente, sem somar também a quantidade anterior.

Comparar por inventário + produto + depósito, com abrangência e unidade compatíveis. Incompatibilidade ou inconsistência não é uma diferença quantitativa e deve ser sinalizada, não convertida para zero nem ocultada por uma conversão inventada.

Ordenar os resultados válidos pela sequência da rodada, não pela ordem em que rodadas paralelas terminaram. Selecionar os dois últimos de cada produto; uma rodada parcial que não inclui esse produto não elimina seu resultado anterior.

Devolver os identificadores/números das rodadas comparadas e a diferença assinada `mais recente − anterior`, com a precisão real do produto. O backend é a fonte do cálculo, sem ponto flutuante do navegador definindo a divergência.

Estados distintos:

- **Sem resultados comparáveis:** menos de dois resultados elegíveis/compatíveis; diferença ausente, não zero.
- **Sem divergência:** existem resultados comparáveis e a diferença é zero.
- **Com divergência:** diferença atual não zero.

A listagem informa quantos produtos são comparáveis e quantos divergem. Uma parte comparável sem diferenças não permite afirmar que todos os produtos foram comparados. A tabela mantém os demais resultados históricos.

A regra A é uma alteração explícita em relação ao helper atual do protótipo: `comparison()` pode recuperar uma quantidade antiga diferente, mesmo após duas rodadas recentes concordarem. Não reutilizar esse comportamento nem o motor local. A concordância atual não oficializa, aprova ou altera as regras de decisão da ENG-3118.

## 5. Histórico equivalente ao protótipo

A inspeção de `Inventory.jsx`, `model.mjs`, seus testes e `e2e/inventory/read.spec.mjs` confirmou:

- O histórico é uma linha do tempo em ordem cronológica, com autor, data/hora e texto contextual.
- Registra criação/edição/início, participação, distribuição, lançamentos, correções, conclusão/recontagem, descarte, oficialização e decisões.
- Correções preservam produto, endereço, rodada, quantidade anterior, nova quantidade e motivo.
- Descarte e reprovação preservam justificativas. Outras decisões exibem a justificativa quando o fluxo real a fornecer.
- A aba de lançamentos mostra a quantidade vigente; o histórico conserva as alterações.
- Não existe interface geral de diff entre versões, reconstrução ou reexecução de eventos.

Preservar esse conteúdo, não apenas rótulos genéricos. Retirar somente eventos/textos dependentes de regularização ERP ou de automação fora do recorte. Não afirmar no início que rodadas foram criadas pela ENG-3114, pois essa issue não as produz.

### Contrato persistido de eventos

Estabelecer um contrato compartilhado, com armazenamento próprio de eventos do inventário caso ainda não exista equivalente. Conservar: ID, inventário, tipo de ação, autor e identificação de exibição, horário do servidor, resumo e contexto mínimo estruturado de produto/endereço/rodada/justificativa/quantidades quando pertinente. Não copiar o estado completo nem payloads com credenciais.

Registrar eventos na mesma transação da ação de origem. Eventos de operações revertidas não sobrevivem. Uma repetição idempotente do início não gera outro evento. Ordenar por horário e ID como desempate.

A ENG-3115 integra criação/edição da ENG-3113 e início da ENG-3114 ao contrato, sem alterar suas regras operacionais. Distribuição, contagens e decisões registram seus próprios eventos nas respectivas entregas. Não recriar seus comandos nesta issue.

Não reconstruir eventos pelo `updated_at`, importar eventos do navegador ou fabricar acontecimentos anteriores. Se houver registros anteriores à instrumentação, preservar os dados de autoria/datas comprovados no cabeçalho e explicitar a limitação do histórico; decidir o rollout antes da execução.

A auditoria de movimentações recusadas da ENG-3114 permanece separada. Não exibi-la como lançamento de contagem nem construir um painel avançado de tentativas nesta entrega.

## 6. Componentes e isolamento do runtime

Reutilizar `InventoryList`, a composição do detalhe, identidade/endereço de produto, `PageHeader`, `Button`, `Filters`, `Spinner` e paginação somente quando preservarem os contratos aprovados de interação, acessibilidade e carregamento. Reconciliar com os componentes já adaptados pela ENG-3113 antes de editar.

Separar helpers de consulta/apresentação do legado. O grafo navegável não pode importar `MockData`, fixture, `store.mjs`, `seeds.mjs`, `operations.mjs`, `catalog.mjs` ou `model.mjs`. `list.mjs`, `presentation.mjs` e `Results.jsx` atuais também possuem dependências transitivas do mock; não reutilizar seus imports sem adaptação.

Manter autenticação e cliente HTTP existentes. Não ler, gravar, migrar ou apagar chaves de inventário do navegador. Fixtures são permitidas exclusivamente nos testes. Não alterar o aplicativo `Rex-Estoque`, componentes globais ou fluxos operacionais para forçar reaproveitamento.

## 7. Falhas

- Distinguir carregamento, vazio real e erro em lista, opções e cada aba. Uma falha nunca vira ausência de divergência, quantidade zero ou cenário local.
- Permitir nova tentativa preservando a consulta. Conteúdo antigo, se mantido durante uma atualização, não pode parecer uma confirmação atual.
- Cancelar/ignorar respostas antigas ao mudar busca, filtros, página, ID ou sessão. Não publicar dados da sessão/contexto anterior.
- `401`: fluxo existente de sessão; `403`: acesso/contexto indevido; `404`: inventário fora do contexto ou inexistente; `422`: parâmetros inválidos. Indisponibilidade preserva uma mensagem legível, sem revelar informações técnicas sensíveis.
- Falha do recurso de resultados não deve ser apresentada como “Sem resultados comparáveis”. Esse estado exige uma leitura bem-sucedida que ateste a ausência.
- Não modificar parâmetros inválidos silenciosamente nem recorrer ao catálogo local/ERP para completar dados ausentes.

## 8. Validação

### Backend

- Busca por número formatado/não formatado e descrição, caixa/acentos, paginação e ordem estável sem duplicações.
- Cada filtro e suas combinações; contraexemplos em que produtos diferentes satisfariam predicados isolados; divergência em produto diferente do recorte não atende ao filtro combinado.
- Datas inclusivas no fuso da aplicação, extremos do dia, limites abertos e intervalo inválido.
- Opções completas e contextuais, responsáveis fora da página, mudanças cadastrais e produto histórico não elegível para um novo inventário.
- Rascunho com leitura cadastral atual versus fotografia imutável após início.
- Dois últimos resultados por produto, recontagem parcial, término fora da sequência, igualdade, diferença, zero explícito, correção, aborto, incompletude, descarte e incompatibilidade de unidade/abrangência.
- Resumos e filtros usam a mesma regra; ausência de comparação é distinta de zero divergências.
- Eventos atômicos, autoria e justificativas; rollback e repetição sem duplicação. Paginação cronológica e consulta de lançamentos vigentes.
- Acesso com duas identidades autorizadas e recusas em todos os endpoints, inclusive Master fora da Expedição e IDs de outro contexto.
- Consultas em lote sem N+1, sem truncamento funcional de 100 produtos e sem campos/chamadas de saldo ou integração ERP.

### Frontend e integração

- Aplicar/Limpar, busca, dependências de opções, URL, recarga, voltar/avançar, retorno do detalhe e redefinição da página.
- Detalhe completo apesar dos filtros da lista; abas, expansão, resultados reais e histórico equivalente ao protótipo.
- Carregamento, vazio, erro, validação, retry, respostas fora de ordem e troca de sessão/contexto.
- Teclado, foco, semântica dos links/abas e responsividade, preservando rolagem interna sem overflow da página.
- Ausência de fixture/storage do inventário e chamadas ERP no runtime.
- Smoke com backend real e usuários autorizados distintos. Interceptações sintéticas de UI não comprovam persistência nem comparação integrada.

Testes que alteram schema seguem `docs/testing-database.md`, apenas na instância descartável e após o preflight. Não usar banco oficial nem rodar resets concorrentes no mesmo schema. O planejamento não executa migrations, testes funcionais ou chamadas ERP.

## 9. Dependências e ordem de execução

| Entrega | Contrato consumido |
| --- | --- |
| ENG-3113 | Cabeçalho, seleção persistida, catálogo/resolução, acesso e transporte/API básicos. |
| ENG-3114 | Início, fotografia definitiva, acesso ao iniciado e evento de início. |
| ENG-3116 | Distribuição/assunção e seus eventos, quando disponíveis. |
| ENG-3117 | Lançamentos vigentes, confirmações explícitas e correções auditadas. |
| ENG-3118 | Situação das rodadas, resultados completos, descarte, resultado oficial e decisões locais. |

A dependência formal no Linear é a ENG-3113. Há dependência funcional da ENG-3114 para validar fotografia e das entregas de contagem para validar resultados. Alinhar esses contratos no planejamento sem apresentar código futuro como disponível.

Ordem aprovada: consolidar contratos → consultas/filtros/histórico no backend → conectar listagem/detalhe → validar UI e integração real. O trabalho independente pode avançar após autorização, mas o aceite de divergências permanece pendente até integração com resultados persistidos reais. Não criar motor de contagem, tabelas artificiais de resultados ou adaptador que sempre retorna vazio para contornar a dependência.

## Fora do escopo

Cadastro duplicado, início/bloqueios, distribuição e assunção, modalidades/registro de contagem, recontagem operacional, escolha de resultado oficial, aprovação/reprovação, desbloqueio, exclusão, dashboard, exportação, integração/saldo ERP, automação cíclica, atualização em tempo real, event sourcing, alterações no aplicativo nativo e refatoração global de componentes.

## Referências

- ENG-3115 e critérios de aceitação.
- [Desenho ENG-3113](2026-11-05-eng-3113-inventario-manual-design.md) e [plano ENG-3113](2026-11-05-eng-3113-inventario-manual-implementation-plan.md).
- `docs/plans/2026-11-05-eng-3114-inicio-inventario-bloqueio-wms-design.md` e plano correspondente, consultados na worktree da ENG-3114.
- ENG-3116, ENG-3117, ENG-3118 e alinhamento de 04/11/2026 nos comentários da ENG-3078.
- `rex-front/src/pages/Inventory/Inventory.jsx`, `InventoryList.jsx`, `Results.jsx`, `list.mjs`, `model.mjs`, testes de modelo/operações e `e2e/inventory/read.spec.mjs`.
- `AGENTS.md`, `docs/testing-database.md` e infraestrutura existente de busca PostgreSQL com `unaccent`.

O próximo artefato é o plano detalhado de implementação. Sua elaboração continua sendo planejamento e não autoriza executar a funcionalidade.
