# ENG-3119 — Plano de implementação do dashboard de inventário

**Status:** implementação autorizada e em andamento; backend e frontend estão nas worktrees `feature/eng-3119` baseadas em `feature/inventario`. O status de validação é parcial.
**Design aprovado:** [Dashboard com dados reais](2026-11-06-eng-3119-dashboard-inventario-dados-reais-design.md), commit `c5ca98ed`.
**Objetivo:** substituir os indicadores simulados por cobertura anual, evolução mensal e tarefas por responsável, com consulta de anos anteriores, persistência real e carregamento leve.

## 1. Arquitetura, estado inicial e segurança

Laravel/PostgreSQL calcula agregados autoritativos a partir do catálogo elegível, consolidações aprovadas, tarefas e confirmações vigentes. React/Vite consulta um único endpoint por ano e apenas apresenta seus resumos no painel ECharts já existente. Não criar tabelas de indicadores, projeções assíncronas, dependência de saldo ou integração ERP.

- [x] Design aprovado em três seções, incluindo a condição de desempenho da API única.
- [x] Design versionado em `feature/eng-3119`, worktree documental `rex-back-eng-3119`, criada de `58a9cf80` da ENG-3118.
- [x] Painel visual localizado na `dev` do frontend: ENG-3084, commit `d1b2acaa`; referências inspecionadas `dev:f12bbe11` e `origin/dev:7842ccc1`.
- [x] Receber autorização expressa para implementar no pedido subsequente a este plano.
- [x] Reconciliar catálogo, contexto, início, tarefas, confirmações, consolidações e aprovação com as implementações efetivas em `feature/inventario`; ver os arquivos reais listados abaixo.
- [ ] Reconciliar consultas específicas da ENG-3115, se houver contrato relevante entregue, sem duplicá-las ou torná-las bloqueador artificial.
- [x] Preparar worktrees backend e frontend em `feature/eng-3119`, baseadas em `feature/inventario`, preservando os demais checkouts.

O protótipo ENG-3084 não é ancestral da branch frontend `feature/inventario`; seu componente visual foi consultado seletivamente no commit `d1b2acaa`. Nenhuma branch inteira foi incorporada.

A correspondência de contratos foi feita com os modelos, queries, serviços, migrations e workflows persistidos de `feature/inventario`. A ausência de fonte confiável continua sendo bloqueador; não reconstruir fatos por `updated_at`, texto de evento, fixture de runtime, saldo ou estado local.

Seguir `AGENTS.md` e `docs/testing-database.md`. A implementação exige PHP compatível com `composer.json` (`^8.4`); o PHP 8.2 padrão do host não deve executar suas suítes. Não atualizar dependências para adaptar o projeto ao host.

Antes de testes com banco, usar `php artisan --env=testing test:database-safety`. Esse preflight confirmou `rex_test` em `127.0.0.1:5433`; os testes backend foram executados pelo container PHP 8.4. Nenhum banco oficial, saldo ou ERP foi consultado. Não executar resets concorrentes do mesmo schema.

## 2. Contrato e invariantes de referência

### HTTP e período

Proposta: `GET /api/v1/inventory/dashboard?year=2026`. O ano é ilustrativo; ausência usa o ano corrente do servidor. Registrar a rota literal antes de `/{inventory}` e reconciliar prefixo e middlewares com o domínio entregue.

Exigir autenticação, Administrador/Master e sessão/acesso atuais na Expedição, inclusive em chamada direta. Setor e depósito vêm do contexto configurado; não são filtros arbitrários do cliente. Não ampliar acesso para System, Almoxarifado ou operador só porque a aba simulada estava visível.

Anos disponíveis: corrente mais os anos de início e de aprovação local dos inventários consultáveis, distintos e decrescentes. Rascunho sem início/aprovação não cria ano. Ano futuro, malformado ou indisponível retorna `422`, sem fallback silencioso ou vazamento de competências de outro contexto.

Derivar corrente, limites e mês do mesmo horário/fuso configurado. Usar intervalo semiaberto `[início do ano, início do seguinte)` convertido para a representação de armazenamento; não presumir fuso do navegador ou armazenamento UTC sem verificar o contrato real.

### Resposta mínima proposta

Usar o envelope `data` e as convenções de Resource existentes. Não devolver registros brutos.

| Campo | Contrato |
| --- | --- |
| `year`, `current_year` | Inteiros: ano consultado e corrente do servidor. |
| `available_years` | Inteiros únicos, decrescentes, incluindo corrente e ano consultado. |
| `generated_at`, `timezone` | Referência temporal do snapshot e fuso configurado, sem valor de instância hardcoded. |
| `coverage.total` | Quantidade de produtos distintos elegíveis agora. |
| `coverage.inventoried` | Produtos desse universo aprovados localmente no ano; distintos. |
| `coverage.pending` | `total - inventoried`. |
| `coverage.completeness` | Percentual com uma casa decimal; `null` quando não há produtos elegíveis. |
| `evolution` | Exatamente 12 posições `{month, total}`, com mês numérico 1–12. Total inteiro conhecido ou `null` somente para mês futuro do ano corrente. |
| `responsibles` | Linhas `{id, name, completed, pending}` agregadas por responsável; `id: null` representa “Sem responsável”, não usuário fictício. |

Zero conhecido e valor ausente não são intercambiáveis. Inteiros/percentuais são validados, não normalizados com `Number(value) || 0`. Total zero exige estado explícito “Sem produtos elegíveis”, não 100% ou progresso inválido.

### Fontes e semânticas

| Bloco | Fonte/competência |
| --- | --- |
| Universo | Predicado do catálogo atual da ENG-3113, por `products.id`, sem saldo. |
| Inventariados | Produtos atuais incluídos na consolidação final da ENG-3118, com aprovação terminal no ano consultado. Zero é válido; aborto final, reprovação e não aprovação não contam. |
| Evolução | Primeira aprovação válida de cada produto dentro do ano; meses conhecidos acumulam, futuros não projetam valores. |
| Tarefas | Inventário iniciado no ano consultado; situação operacional atual de todas as tarefas, inclusive recontagens e produtos fora do catálogo atual. |
| Realizadas | Uma tarefa com confirmação persistida vigente, mesmo zero, produto incompleto, rodada desconsiderada ou inventário reprovado. |
| Pendentes | Tarefa sem confirmação em rodada/inventário ainda abertos à execução, inclusive preparação que ainda possa ser iniciada. Sem responsável é grupo próprio. |
| Encerradas sem confirmação | Não contam em nenhum dos dois totais de tarefas. Não transformar aborto em zero/realização. |

Correções não criam outra tarefa realizada. Nomes iguais não unem pessoas. Revogação de acesso não apaga atribuição ou pendência aberta. Não exigir que soma de tarefas coincida com produtos distintos; o mock atual contém essa premissa incorreta para o fluxo real.

Consulta histórica usa catálogo **atual** e situação **atual** das tarefas da coorte de início. Não é snapshot em 31/12. Uma tarefa de inventário iniciado em dezembro e confirmada/aprovada em janeiro aparece realizada no ano de início; a cobertura pertence ao ano da aprovação.

## 3. Mapa de arquivos

### Backend — `rex-back/`

| Arquivo/grupo proposto | Responsabilidade |
| --- | --- |
| `Domain/Inventory/Queries/InventoryDashboardQuery.php` | Implementado: uma instrução agregada, reutilizando `InventoryCatalogQuery`, com cobertura, evolução, tarefas e anos. |
| `Domain/Inventory/Services/InventoryDashboardService.php` | Implementado: ano/fuso, validação de ano disponível e transformação do agregado em contrato. |
| DTO/Resource separados | Não criados; o serviço devolve arrays simples no envelope `data`, sem models/coleções. |
| `app/Http/Requests/InventoryDashboardRequest.php` | Implementado: validação de ano, sem contexto vindo do cliente. |
| `app/Http/Controllers/Inventory/GetInventoryDashboardController.php` | Implementado: fronteira HTTP enxuta. |
| `routes/api.php` e `EnsureInventoryManagementAccess` existente | Implementado usando middleware contextual já entregue. |
| `database/migrations/<timestamp>_add_inventory_dashboard_read_indexes.php` | Somente se a medição justificar índices ainda ausentes; rollback apenas dos novos índices. |
| `tests/Feature/Inventory/InventoryDashboardTest.php` | Implementado: endpoint, acesso, catálogo sem saldo, vazio, ano, primeiro ano de aprovação, duplicidade, tarefas e grupo sem responsável. |
| Testes separados de snapshot/concorrência | Pendentes; a consistência entre blocos é garantida por uma instrução SQL, ainda sem teste concorrente específico. |
| Perfil de volume | Executado em transação reversível no banco de teste; evidência preliminar em `docs/validation/eng-3119/performance.md`. |
| `docs/validation/eng-3119/{contracts,acceptance}.md` | Pendentes; completar contratos restantes e matriz final de aceite. |

Reutilizar `Inventory`, `InventoryConsolidation`, `InventoryConsolidationProduct`, tarefas, confirmações/revisões, identidade e contexto entregues. Não criar factories/models/tabelas de resultados paralelos para contornar a ENG-3118.

### Frontend — `rex-front/`

- Adicionado `dashboard()` a `src/domain/Inventory/services/InventoryService.jsx`, sobre `@http`, com ano e `AbortSignal`; não foi criado outro cliente/serviço.
- A consulta sob demanda e a proteção/cancelamento estão no efeito de `InventoryDashboard.jsx`; não foi criado hook separado. Os helpers/estado puros ficam em `inventoryDashboard.helpers.js` e seu teste `.helpers.test.mjs`.
- Adaptados `InventoryDashboard.jsx`, `.css` e `index.jsx`, conservando ECharts, cards, tabelas e limpeza das instâncias.
- Adaptados `Dashboard.jsx`, `dashboardTabs.js` e `dashboardTabs.helpers.test.mjs` para visibilidade contextual e URL.
- Não havia `inventoryDashboard.data.js` na base `feature/inventario`; nenhum mock foi introduzido. Os dados sintéticos do teste do helper não entram no runtime.
- Adaptar `e2e/inventory/dashboard.spec.mjs`; criar `dashboard.fixtures.mjs`, `dashboard.integration.spec.mjs` e a configuração de integração real necessária somente se não houver runner adequado entregue pelas dependências.

Nenhuma alteração no Rex-Estoque, em storage de inventário, cliente HTTP compartilhado ou componentes globais para forçar reaproveitamento.

## 4. Roteiro por tarefa

Em cada tarefa futura de código: escrever o teste focal → executá-lo e confirmar falha pelo comportamento ausente → implementar o mínimo → confirmar sucesso → revisar diff e formatação → commit pequeno com prefixo `ENG-3119`. Nenhuma dessas tarefas foi executada neste planejamento.

### Tarefa 1 — Reconciliar dependências, rollout e orçamento de desempenho

**Depende de:** autorização e implementações reais das dependências.
**Ler:** designs/planos ENG-3113/3114/3116/3117/3118; contrato ENG-3115 quando disponível; painel da ENG-3084 na `dev`; `AGENTS.md`, `docs/testing-database.md`, transporte e runner E2E existentes.
**Criar:** `docs/validation/eng-3119/contracts.md` e estrutura de registro de desempenho.

- [ ] Registrar nomes reais de tabela/model, identificadores, setor/depósito e fonte do catálogo; mapear o predicado de elegibilidade sem saldo e sem hidratar seu catálogo paginado.
- [ ] Mapear fonte oficial da consolidação, inclusão/aborto, situação aprovada e timestamp terminal. Não usar quantidade positiva, última edição ou concordância inferida como substitutos.
- [ ] Mapear `started_at` ou equivalente, estados que permitem iniciar/contar, propriedade, confirmação vigente e preservação de usuários históricos. Não chamar Policy por tarefa para montar totais.
- [ ] Confirmar armazenamento de timestamps e fuso configurável, estabelecendo conversão de limites/mês e fonte única de horário para a consulta.
- [ ] Escolher e registrar o mecanismo de snapshot: uma instrução SQL agregada ou múltiplas consultas em transação curta de leitura `REPEATABLE READ`, antes da primeira leitura relevante. Não alterar isolamento global nem adquirir locks operacionais.
- [ ] Registrar prefixo/rota, DTO/Resource, convenções de erros, fonte dos anos e parâmetros de URL propostos `dashboard_tab=inventory` e `inventory_year=2026`. Preservar parâmetros não relacionados.
- [ ] Registrar bases de execução e reaproveitamento seletivo dos arquivos visuais da `dev`, sem trazer seu motor simulado ou mudanças alheias.
- [ ] Definir dataset e ambiente de medição, orçamento de latência percentil/payload e critérios objetivos de aceite com a equipe antes de implementar. Usar volume realista e um volume maior para comparação; não declarar velocidade sem medir.
- [ ] Definir tratamento de registros locais anteriores sem fatos históricos confiáveis: corrigir a dependência/rollout explicitamente antes de habilitar o painel, sem GET que fabrique dados ou ignore inconsistências silenciosamente.
- [ ] Documentar lacunas bloqueadoras e testes de regressão realmente disponíveis; preparar banco seguro e runtime compatível apenas após autorização.
- [ ] Commit: `ENG-3119 Alinha contratos e metas do dashboard`.

**Saída:** mapa concreto de fatos, arquivos, calendário, snapshot e orçamento de desempenho. Nenhum requisito essencial presumido ou implementado nesta tarefa.

### Tarefa 2 — Cobertura anual e evolução por primeira aprovação

**Depende de:** 1 e dados reais do catálogo/consolidação/decisão terminal.
**Criar/editar:** cenário de testes, `InventoryDashboardQuery.php`, `InventoryDashboardCoverageTest.php` e relações de leitura mínimas já previstas nas dependências.

- [ ] Montar cenário com três produtos elegíveis: P1 em múltiplos endereços/itens, P2 com resultado final zero e P3 sem aprovação válida. Adicionar produto de outro contexto e resultados não aprovados para provar exclusão.
- [ ] Testar P1 aprovado em janeiro e novamente em março; P2 aprovado em fevereiro; P3 abortado/reprovado. Esperar total 3, inventariados 2, pendentes 1, percentual 66,7%, janeiro 1 e fevereiro/março 2. A fonte são produtos finais incluídos, não soma de quantidades.
- [ ] Cobrir resultado incompleto em uma rodada e oficial completo em outra, decisões retiradas/desconsideradas, ausência de consolidação e aguardando aprovação. Não confundir zero confirmado com ausência.
- [ ] Cobrir nova aprovação em outro ano, primeira aprovação de cada ano, aprovação exatamente nos limites anuais/mensais e fuso diferente do armazenamento. Testar que início em dezembro e aprovação em janeiro contribui somente no segundo ano.
- [ ] Testar catálogo vazio (`completeness: null`), catálogo com mais de uma página e mudança de elegibilidade atual alterando inclusive o ano anterior, sem alteração de fatos históricos.
- [ ] Congelar o relógio nos testes: meses anteriores sem aprovação acumulam zero; meses sem novidades mantêm total; futuros são `null`; dezembro de ano encerrado é conhecido. O último ponto conhecido deve igualar o card.
- [ ] Executar `./vendor/bin/pest tests/Feature/Inventory/InventoryDashboardCoverageTest.php`; confirmar falha pelos agregados ainda ausentes, não por preflight/runtime.
- [ ] Implementar relação distinta de elegíveis e primeira aprovação por produto dentro do ano. Aplicar faixa de timestamp no filtro para favorecer índices; agrupar mês com o fuso correto. Não usar `whereYear` indiscriminadamente no caminho crítico.
- [ ] Agregar no banco e preencher somente as 12 posições mensais no serviço/DTO. Não fazer consulta por mês, somar revisões ou hidratar inventários/produtos/contagens completos.
- [ ] Reexecutar testes, revisar o SQL/joins para evitar multiplicação de linhas e formatar somente PHP alterado.
- [ ] Commit: `ENG-3119 Calcula cobertura e evolução anual reais`.

**Saída:** agregados corretos para produtos distintos e ano da aprovação, independentes de saldo/ERP e do número de endereços/revisões.

### Tarefa 3 — Tarefas operacionais e anos disponíveis

**Depende de:** 1/2 e contratos de tarefas, confirmações e estados das ENG-3116/3117/3118.
**Editar:** query/cenário; criar `InventoryDashboardTasksTest.php`.

- [ ] Criar duas rodadas e uma recontagem do mesmo produto/endereço; confirmar algumas tarefas, incluindo zero, e deixar outras atribuídas/abertas. Esperar uma realização por tarefa, não por produto/etiqueta/revisão.
- [ ] Corrigir uma confirmação e comprovar que o total realizado não aumenta. Contagem em rascunho ou revisão substituída não produz outra realização.
- [ ] Desconsiderar rodada, encerrar parcialmente e reprovar inventário: confirmações permanecem realizadas; tarefas não confirmadas desses estados saem das pendências, sem virar realizações.
- [ ] Testar rodada preparada/aberta antes do primeiro ingresso, participante sem presença online e usuário com acesso revogado; a atribuição e a pendência não desaparecem só por esses fatos.
- [ ] Testar responsáveis homônimos, preservação de identidade histórica e grupo único `id: null`. Não esconder responsáveis por não constarem no catálogo atual de participantes.
- [ ] Usar inventários iniciados em anos diferentes, confirmados depois da virada; filtrar por início e usar estado atual. Produtos que saíram do catálogo atual continuam em tarefas históricas.
- [ ] Testar anos disponíveis vindos de início e aprovação, corrente sem dados, ordem decrescente, duplicidades, exclusão de rascunho sem início e ausência de vazamento de outro contexto.
- [ ] Executar o teste focal e confirmar falha; implementar agregação por responsável com confirmação vigente/`EXISTS`, sem unir todas as revisões ou consultar cada usuário individualmente.
- [ ] Definir ordem estável para responsáveis e o grupo sem responsável, sem top-N oculto, paginação parcial ou truncamento dos totais. Retornar somente linhas com realizações/pendências.
- [ ] Reexecutar os testes de tarefas e cobertura. Asserir explicitamente um caso em que total de tarefas é diferente de produtos inventariados.
- [ ] Commit: `ENG-3119 Agrega tarefas e competências do dashboard`.

**Saída:** visão operacional por ano de início e catálogo contextual de anos, sem relação artificial com o total de produtos.

### Tarefa 4 — Snapshot consistente, API e autorização

**Depende de:** 2/3 e mecanismo de leitura definido na tarefa 1.
**Criar/editar:** serviço, DTO readonly, Resource, Request, controller, rota e Policy/middleware; testes HTTP/consistência e worker de testes quando necessário.

- [ ] Escrever testes do endpoint para ano omitido, anterior disponível, futuro, indisponível, texto, decimal e campos que tentem alterar o contexto. Validar `422` sem normalização silenciosa.
- [ ] Testar Admin/Master na Expedição e outra sessão administrativa autorizada; negar acesso anônimo, demais níveis e setor indevido, inclusive Master fora do contexto e chamada direta com IDs/parâmetros adulterados.
- [ ] Asserir o contrato da seção 2, exatamente 12 meses, ausência de registros/saldos/revisões/credenciais e tipos numéricos/null corretos. Não retornar nomes/anos de outro contexto.
- [ ] Verificar que GET não cria anos, resultados, eventos ou contagens nem altera estoque/bloqueios. Interceptar gateways HTTP/SOAP/ERP relevantes e exigir ausência de chamadas externas, não apenas uma classe HTTP específica.
- [ ] Executar `./vendor/bin/pest tests/Feature/Inventory/InventoryDashboardTest.php`; observar as falhas esperadas antes de implementar a fronteira HTTP.
- [ ] Implementar coordenação de snapshot antes da primeira leitura relevante. Nas consultas múltiplas, não confiar no `READ COMMITTED` padrão para representar a mesma versão em todos os blocos; não adquirir `FOR UPDATE`.
- [ ] Resolver ano/horário/fuso uma única vez, validar os anos disponíveis no mesmo contexto/snapshot e devolver somente resumos. Configuração/fato essencial ausente deve falhar explicitamente, sem catálogo fictício ou retorno vazio permanente.
- [ ] Registrar rota literal antes da dinâmica, aplicar acesso compartilhado das dependências e impedir cache compartilhado/persistido de respostas sensíveis ou desatualizadas.
- [ ] Com conexões/processos PostgreSQL independentes, ler durante commit controlado de confirmação/encerramento/aprovação. Asserir resposta integral anterior ou posterior, nunca mistura entre cobertura, tarefas e competências. Não reimplementar os comandos/locks da ENG-3118 para esse teste.
- [ ] Testar exceção no meio da leitura e garantir encerramento da transação e ausência de locks operacionais persistentes. Usar instância de testes isolada, sem reset por worker.
- [ ] Executar testes HTTP, consistência e agregados; revisar consultas e formatar PHP alterado.
- [ ] Commit: `ENG-3119 Expõe dashboard agregado e consistente`.

**Saída:** endpoint real e autorizado, com resumos coerentes e nenhuma operação de inventário/estoque como efeito de leitura.

### Tarefa 5 — Gate de desempenho e índices justificados

**Depende de:** 4. Deve ocorrer antes de considerar estável o contrato para a interface.
**Criar/editar:** teste/perfil de desempenho, `docs/validation/eng-3119/performance.md` e migration de índices somente se necessária.

- [ ] Gerar dados sintéticos exclusivamente no banco descartável, usando o cenário válido. Registrar volumes de produtos, inventários, anos, rodadas, tarefas, revisões e responsáveis; não usar backup oficial nem fixtures em runtime.
- [ ] Medir o volume representativo definido na tarefa 1 e outro maior mantendo quantidade de responsáveis/anos equivalente. Incluir muitas revisões por tarefa e endereços repetidos para detectar joins multiplicativos.
- [ ] Instrumentar número de consultas do domínio, sem confundir autenticação com agregação. Asserir que não cresce por produto, inventário, mês ou pessoa. Verificar que a aplicação não hidrata coleções brutas para somar.
- [ ] Medir tamanho do JSON e comprovar que acrescentar tarefas/produtos, sem novos responsáveis/anos, não amplia proporcionalmente a resposta. Não incluir totais ou linhas extras para depuração na API pública.
- [ ] Registrar ambiente, versões, dataset, execução fria/aquecida, amostra de requisições e latências p50/p95, incluindo tempo total HTTP. Comparar com o orçamento acordado, não apenas uma execução isolada ou tempo de SQL.
- [ ] Usar `EXPLAIN (ANALYZE, BUFFERS)` somente na instância de testes. Examinar predicados de contexto/estado/data, FKs das consolidações, tarefas e referência da confirmação vigente; evitar índices redundantes.
- [ ] Se necessário, adicionar índices medidos e testar aplicação/rollback restritos a eles. Não criar tabela materializada/cache para contornar o problema sem novo desenho.
- [ ] Repetir medições e testes de correção após a otimização; registrar antes/depois. Não usar asserts de milissegundos instáveis como única prova em CI.
- [ ] Se um gráfico continuar excedendo o orçamento, registrar o gargalo e revalidar sua separação antes do aceite. Não esconder pessoas, limitar dados arbitrariamente ou proclamar que API única é necessariamente rápida.
- [ ] Executar o perfil configurado, por exemplo `./vendor/bin/pest --group=inventory-dashboard-performance`, somente após reconciliar esse grupo e seu guard com a suite real; demais testes mantêm dataset pequeno e determinístico.
- [ ] Commit: `ENG-3119 Valida desempenho das consultas do dashboard`.

**Saída:** orçamento atendido com evidência reproduzível ou bloqueador explícito de desempenho; nenhum número de teste apresentado como medição de produção.

### Tarefa 6 — Serviço web e carregamento sob demanda

**Depende de:** 4/5 e transporte frontend persistido das dependências.
**Criar:** `InventoryDashboardService.jsx`, `useInventoryDashboard.js`, helpers e testes de apresentação/estado pertinentes.

- [ ] Escrever testes para URL/permissões/representações de vazio/null sem importar o catálogo mockado. Não recalcular cobertura, consolidação ou tarefas no cliente.
- [ ] Criar o serviço sobre `@http`, passando somente ano válido solicitado e cancelamento suportado; não criar outro cliente, token, sessão ou integração.
- [ ] Implementar estados de carregamento/sucesso/erro e retry do mesmo ano. Requisição inicial sem ano explícito usa o default do servidor, não `new Date().getFullYear()` como autoridade.
- [ ] Carregar ao montar/ativar a aba e ao trocar o ano; não pré-carregar todas as competências ou disparar uma chamada por gráfico/responsável. Compatibilizar com montagem/desmontagem de `react-tabs` e eventual comportamento de desenvolvimento do React.
- [x] Capturar ano/contexto/geração da requisição e ignorar tanto sucesso quanto erro atrasados de uma geração anterior; cancelar quando disponível, sem depender somente do cancelamento para correção.
- [x] Na troca de ano, não exibir totais anteriores sob rótulo novo. Validar ano retornado e aplicar cards, gráficos e metadados juntos. A troca de sessão remonta o painel e invalida dados incompatíveis; troca de setor remove o painel por permissão.
- [ ] Não ler, escrever, migrar ou apagar storage de inventário; autenticação existente continua inalterada. Não manter cache persistido de indicadores ou usar fixture em falha.
- [ ] Preparar asserts de rede/estado nos testes E2E das tarefas 7/9, cobrindo retry, ano omitido e ausência de chamadas enquanto a aba está inativa.
- [ ] Executar os testes focais de helpers e formatar/revisar o serviço/hook.
- [ ] Commit: `ENG-3119 Consulta resumos anuais no dashboard web`.

**Saída:** transporte e estado de consulta isolados do mock e protegidos contra respostas obsoletas.

### Tarefa 7 — Adaptar painel, gráficos e isolamento do mock

**Depende de:** 6 e arquivos visuais reais da `dev`.
**Editar:** `InventoryDashboard.jsx`, CSS e índice; remover `inventoryDashboard.data.js` do runtime e substituir seu teste pertinente; adaptar `e2e/inventory/dashboard.spec.mjs` e fixtures exclusivamente de teste.

- [ ] Escrever testes de UI com uma resposta sintética válida do contrato, em que tarefas diferem dos produtos distintos. Asserir três cards, dois gráficos e tabelas equivalentes, sem exigir os números fixos 872/376/69,9% do mock.
- [ ] Conectar o painel ao hook, remover `data = inventoryDashboardMock`, import de `Inventory/catalog.mjs` e qualquer dependência transitiva de atores/store/model/seeds locais. Não transportar a fixture inteira da `dev`.
- [ ] Remover “Dados simulados”; explicar cobertura por aprovação/catálogo atual e tarefas por início/situação atual sem prometer snapshot fiscal congelado ou envio ERP.
- [ ] Preservar formatação pt-BR e o percentual retornado, com estado explícito de catálogo vazio. Erro de contrato não vira valor zero por coerção.
- [ ] Adaptar evolução para 12 meses, zeros/trechos constantes e `null` futuro; usar último ponto conhecido no texto acessível. Não manter a frase fixa de crescimento até dezembro nem acessar posição ausente sem validação.
- [ ] Corrigir títulos, legendas, tooltips e tabelas de responsáveis para **tarefas**, e manter o grupo “Sem responsável”. Nomes/linhas vêm da API, não de catálogo local.
- [ ] Preservar `ResizeObserver`, descarte das instâncias ECharts e opções memorizadas. Alternar ano/aba não deve acumular canvas/observadores ou recriar gráficos por mudanças irrelevantes de estado.
- [ ] Tratar carregamento, catálogo vazio, sucesso sem aprovações, ausência de tarefas e erro/retry como estados distintos, sem simular sucesso.
- [ ] Acrescentar um teste de grafo/imports do módulo entregue, seguindo a convenção de isolamento das dependências: o painel não alcança mock/catalog/store/model/seeds de inventário. Dados de teste não entram no bundle navegável.
- [ ] Executar testes de helpers e UI focais; revisar o diff contra a composição visual da `dev`.
- [ ] Commit: `ENG-3119 Conecta indicadores e gráficos aos dados reais`.

**Saída:** painel existente com fonte real, rótulos corretos e nenhum fallback de demonstração.

### Tarefa 8 — Badges de ano, URL e visibilidade da aba

**Depende de:** 7 e navegação efetiva do dashboard.
**Editar:** painel/CSS/helpers, `Dashboard.jsx`, `dashboardTabs.js`, testes de helpers/abas e E2E.

- [ ] Escrever testes de corrente default, ano anterior, ano de início/aprovação diferentes e URL inválida. Não inventar anos anteriores nem assumir lista fixa 2025/2026 no runtime.
- [ ] Substituir o `span` da badge por grupo de botões de ano, com `aria-pressed`/seleção programática, nome acessível, foco visível e layout que acomode várias badges em tela estreita.
- [ ] Usar `available_years` do backend; selecionar uma badge altera `inventory_year` e consulta somente aquele ano. A mudança preserva parâmetros alheios e não consulta todos os anos de uma vez.
- [ ] Persistir a aba pelo identificador estável (`dashboard_tab=inventory` proposto), não por índice numérico variável entre setores/perfis. Abrir link/recarregar deve ativar a aba correta e restaurar o ano, inclusive voltar/avançar.
- [ ] Evitar uma segunda consulta redundante apenas por normalizar a URL após receber o ano default. Ano inválido na URL apresenta validação; não trocar silenciosamente para corrente.
- [ ] Restringir visibilidade/carregamento a Admin/Master na Expedição; remover a exposição simulada em Almoxarifado/System sem alterar o acesso às outras abas. A API continua sendo a autoridade de segurança.
- [ ] Preservar nomenclatura efetiva da aba existente, hoje “Inventário” no código inspecionado, salvo mudança já entregue; não renomear outras abas ou refatorar todo o gerenciamento de navegação.
- [ ] Atualizar subtítulo operacional com ano de início e situação atual; ao trocar ano, todos os blocos correspondem à mesma seleção.
- [ ] Executar testes de URL/abas/permissões e E2E focal de navegação.
- [ ] Commit: `ENG-3119 Permite consultar anos anteriores por badges`.

**Saída:** mesma localização visual, seleção histórica acessível e restaurável sem storage ou regressão das demais abas.

### Tarefa 9 — Estados, acessibilidade e regressão visual/funcional

**Depende de:** 7/8.
**Editar:** testes de UI/helpers/isolamento; ajustar somente componentes envolvidos quando os testes revelarem falha.

- [ ] Interceptar apenas o endpoint sob teste com respostas sintéticas do contrato, distinguindo esses testes da integração real. A autenticação/runner seguem a convenção existente, sem criar rota mock de produção.
- [ ] Cobrir loading, 200 sem aprovações, catálogo vazio, sem tarefas, erro/retry, `401/403/422`, configuração indisponível e dados malformados sem fallback para zero.
- [x] Controlar respostas de anos A/B fora de ordem e trocar sessão durante o carregamento. Apenas a última geração válida pode atualizar dados/rótulos; E2E sintético cobre troca de ano e token de sessão com resposta antiga atrasada.
- [ ] Cobrir erro atrasado e troca de setor/aba durante o carregamento; somente o contexto atual deve atualizar o painel.
- [ ] Asserir nenhuma consulta do inventário com a aba inativa, uma fonte agregada para todos os gráficos, somente o ano solicitado e ausência de chamadas ERP ou leitura/escrita de chaves locais de inventário.
- [ ] Verificar gráfico/tabela/tooltip com zero, meses futuros, ano encerrado, responsáveis homônimos, sem responsável e nomes longos. O texto acessível não pode afirmar crescimento inexistente ou misturar tarefas com produtos.
- [ ] Validar teclado, foco e badges em 1440 px e 390 px, sem overflow horizontal do documento, perda de dados ou rótulos sobrepostos.
- [ ] Testar muitos responsáveis: manter todos consultáveis com rolagem/viewport apropriados, sem top-N silencioso. Não aumentar a altura do documento indefinidamente nem esconder totais.
- [ ] Alternar anos/abas repetidamente e conferir descarte de canvas/observadores e responsividade dos gráficos. Confirmar que o carregamento do inventário não bloqueia as outras abas.
- [ ] Executar `node --test` nos testes focais de helpers/abas/isolamento e Playwright no config real reconciliado da tarefa 1. Não usar o antigo resultado mockado como prova de aceite.
- [ ] Commit: `ENG-3119 Cobre estados e navegação do dashboard real`.

**Saída:** UI consistente, acessível e leve para dados reais, com evidência de comportamento em rede lenta e múltiplos responsáveis.

### Tarefa 10 — Integração real, desempenho ponta a ponta e aceite

**Depende de:** 1–9 e dependências operacionais entregues.
**Criar/editar:** `e2e/inventory/dashboard.integration.spec.mjs`, runner/config já existente ou mínimo necessário e `docs/validation/eng-3119/acceptance.md`.

- [ ] Preparar backend/PostgreSQL descartáveis após preflight e frontend conectado a eles. Credenciais/URLs vêm da configuração de testes, nunca de valores de instância versionados. Não usar a base oficial.
- [ ] Preparar fixtures persistidas exclusivamente de testes, com dados anteriores válidos e contextos isolados. Usar comandos reais para a cadeia atual: iniciar, atribuir/assumir, confirmar, consolidar e aprovar; não acrescentar endpoints de seed em runtime.
- [ ] Verificar que confirmar tarefa atualiza realizadas, mas não cobertura antes da aprovação. Após aprovação local, consultar de novo e conferir produto distinto/curva; confirmar zero também deve funcionar.
- [ ] Cobrir reprovação e encerramento parcial: realizadas preservadas, pendências encerradas removidas e somente produtos finais incluídos/aprovados entrando na cobertura.
- [ ] Repetir produto em outro inventário aprovado no mesmo ano sem aumentar a cobertura; consultar ano anterior e caso de início/aprovação em anos diferentes com fontes temporais confiáveis de testes.
- [ ] Selecionar badge histórica, recarregar a página e conferir aba, ano, cards, gráficos e tabelas. Repetir em outra sessão autorizada e comprovar que resultados não dependem do navegador.
- [ ] Alterar elegibilidade atual em cenário controlado e confirmar repercussão também na consulta do ano anterior, sem alterar o histórico dos inventários.
- [ ] Conferir GET sem escrita e ausência de HTTP/SOAP/ajustes ERP usando instrumentação de testes. Não basta ocultar os campos na UI.
- [ ] Repetir perfil de volume com API e navegador integrados; anexar evidência de latência/payload/queries e da interação dos gráficos. Se o orçamento não for atingido, não encerrar o aceite com apenas o dataset pequeno.
- [ ] Executar testes backend focais, regressão das dependências pertinentes, testes web, build e lint nos escopos suportados; registrar falhas preexistentes separadamente, sem correções globais fora do escopo.
- [ ] Rodar Pint no PHP alterado, revisar diffs dos dois repositórios e conferir inexistência de mudanças no Rex-Estoque, credenciais, dados oficiais ou artefatos locais indevidos.
- [ ] Registrar comandos/ambiente, resultados, limitações e links de evidência na matriz abaixo; diferenciar testes interceptados, integração e perfil de desempenho.
- [ ] Commit final de evidências: `ENG-3119 Registra validação integrada do dashboard`.

**Saída:** todos os critérios comprovados em integração real e orçamento de desempenho atendido. Não marcar funcionalidade concluída só pela existência do plano, testes mockados ou aprovação do design.

## 5. Matriz de aceite

| Critério | Evidência futura mínima | Tarefas |
| --- | --- | --- |
| Completude anual, produtos inventariados e pendentes | Catálogo atual distinto; consolidações aprovadas; zero/aborto/reprovação; comparação numérica API/UI e cenário de catálogo vazio. | 2, 4, 7, 10 |
| Evolução mensal acumulada | Primeira aprovação por produto/ano, repetição, limites/fuso, meses conhecidos/futuros e último ponto igual ao card. | 2, 7, 9, 10 |
| Tarefas realizadas e pendentes por responsável | Tarefas por rodada/endereço, confirmação vigente, correção sem duplicar, grupo aberto, fechamento sem confirmação e coorte anual. | 3, 7, 9, 10 |
| Resultados locais sem saldo ou ERP | Fonte final da ENG-3118, catálogo sem filtro de saldo, GET sem escrita e gateways HTTP/SOAP sem chamadas. | 1–4, 9, 10 |
| Coerência após recarga | URL restaura aba/ano; API/banco reais; outra sessão autorizada; ausência de store/fixture; snapshot e respostas antigas protegidos. | 4, 6, 8–10 |
| Consulta de anos anteriores por badges | Anos reais por início/aprovação, corrente default, seleção/teclado, voltar/avançar e sem congelamento histórico implícito. | 3, 8–10 |
| Condição aprovada de carregamento leve | Consulta sob demanda, resumos sem registros brutos, número fixo de queries, payload por responsáveis/meses/anos e perfil p50/p95 documentado. | 1, 4–6, 9, 10 |

## 6. Handoff e fora do escopo

### Estado de execução

| Frente | Estado atual | Entregue | Falta para aceite |
| --- | --- | --- | --- |
| Contratos/base das dependências | Reconciliada com `feature/inventario`. | Catálogo/contexto, timestamps, consolidação, tarefas, confirmações, rotas e modelo foram inspecionados. | Registrar matriz completa da ENG-3115/contratos restantes e orçamento formal. |
| Backend agregado | Implementado, com testes focais passando. | API contextual; uma query agregada; cobertura, primeira aprovação mensal, tarefas e anos; leitura sem mutação. | Concorrência/snapshot, reprovações, abortos, correções e testes mais amplos. |
| Desempenho | Perfil sintético preliminar registrado em `docs/validation/eng-3119/performance.md`. | 10.001 produtos, 5.000 aprovados, 20.002 tarefas; 1 query, 40,32 ms de consulta e JSON agregado de 450 bytes. | Perfil maior, p50/p95 e orçamento acordado; sem inferência sobre produção. |
| Frontend | Implementado; testes unitários, build e E2E focal passando. | Aba/ano na URL, badges, lazy fetch, cancelamento, estados, ECharts e tabelas acessíveis; 4 E2E sintéticos cobrem ano, URL inválida, sessão e resposta antiga; sem mock no runtime. | Smoke E2E com API/banco reais e cenários restantes de erro, setor/aba e responsividade. |
| Aceite integrado | Pendente. | Banco descartável e workflows reais exercitados em testes focais. | Smoke E2E API/UI, matriz completa e perfil ponta a ponta. |

Validação executada: testes backend focais — 23 casos e 383 assertions, 21 passaram e 2 terminaram como warnings do PHPDotenv ao procurar o `.env` ausente; suíte frontend — 482 passaram; build passou com o aviso existente de chunk grande; E2E focal sintético — 4/4 passaram, incluindo troca de ano, sessão e resposta atrasada. ESLint direcionado aos componentes web e à spec E2E passou. O lint global continua bloqueado por erros preexistentes em arquivos não alterados (4 erros e 99 warnings).

A suíte backend completa foi tentada com `memory_limit=512M`, mas ultrapassou o limite de 15 minutos sem relatório final. Antes do timeout, três falhas foram localizadas em `Tests\Unit\PickingOrder\MarkConcludedPickingOrdersWithSeparatedItemsAsDeliveredPartialMigrationTest`; uma execução isolada confirma que as três param na criação do `PickingOrder`, pois a factory/teste omite `responsible_id`, obrigatório no schema. É um bloqueador herdado fora do escopo da ENG-3119; não foi alterado. Uma tentativa anterior com o limite padrão de 128M também encerrou por falta de memória. Nenhum desses resultados equivale à aprovação da suíte completa.

A ordem restante é finalizar os casos backend/concorrência, registrar e tratar os bloqueios de regressão pertinentes, rodar perfil maior e E2E real e, então, completar a matriz de aceite. Testes interceptados não substituem o smoke real.

Não implementar saldo/ajuste/integração ERP, cadastro/contagem/conferência/encerramento duplicados, fotografia anual congelada, consulta fiscal por endereço, novos filtros, exportação, cache/projeção persistidos, polling/tempo real, alterações no aplicativo ou refatoração global. Se desempenho exigir mudança arquitetural além da consulta agregada aprovada, registrar evidência e revalidar antes de ampliar o escopo.

Este plano foi detalhado manualmente porque a skill `writing-plans` não estava instalada no ambiente. A execução atual foi iniciada somente após autorização expressa posterior; este registro acompanha o progresso e não substitui o aceite final.
