# ENG-3119 — Dashboard de inventário com dados reais

**Status:** desenho aprovado em 2026-11-06; implementação autorizada por solicitação posterior e em andamento nas worktrees `feature/eng-3119` baseadas em `feature/inventario`.
**Issue:** https://linear.app/soelx/issue/ENG-3119/exibir-dashboard-de-inventario-com-dados-reais
**Dependência operacional:** ENG-3118, sobre os contratos das ENG-3113/3114/3116/3117.

## Objetivo e limites

Substituir os indicadores simulados da aba de inventário do dashboard por cobertura anual, evolução mensal acumulada e tarefas por responsável calculadas no backend a partir dos dados locais persistidos. Permitir alternar entre o ano corrente e os anos anteriores com dados reais, preservando a composição visual do protótipo.

O contexto permanece Administrador/Master com sessão ativa na **Expedição**, com depósito resolvido pela configuração da ENG-3113. Nesta instância, o vínculo aprovado é Expedição ↔ depósito 004; não hardcodar esse código nem aceitar outro contexto arbitrário do navegador.

Não consultar saldo, alterar estoque, depender de integração ERP, reconstruir resultados de contagens no navegador ou implementar as operações das dependências.

## Decisões aprovadas na conversa

1. Os 100% correspondem aos produtos distintos do catálogo elegível **atual** da Expedição, sem filtro por saldo, como na ENG-3113. Não usar apenas os produtos selecionados em inventários nem criar uma fotografia anual.
2. Somente resultados oficiais completos de inventários aprovados localmente contribuem para a cobertura. Zero confirmado conta; produtos abortados e inventários reprovados não contam.
3. Cada produto conta uma vez por ano. A evolução usa sua primeira aprovação válida dentro do ano selecionado, não a criação, o lançamento ou a conclusão de uma rodada.
4. Tarefas têm uma visão operacional independente da cobertura: confirmações persistidas são realizadas; tarefas sem confirmação em etapas ainda abertas são pendentes. Tarefas abertas aparecem em “Sem responsável”.
5. Ano corrente é o padrão. As badges no local do ano atual permitem selecionar anos anteriores; a seleção afeta todos os blocos.
6. O recorte anual das tarefas usa o **ano de início do inventário**, sempre com a situação atual persistida. Não é uma reconstrução da situação em 31 de dezembro.
7. Uma API agregada devolve os blocos do ano selecionado, desde que seja leve. Não carregar registros completos para calculá-los. Medir consultas, resposta e tempo com volume representativo antes do aceite; reavaliar a separação de um gráfico se ele continuar sendo gargalo após otimização.
8. Preservar a aba, os três indicadores e os dois gráficos. Manter ano e aba na URL, distinguir erro de vazio/zero e não oferecer mock como fallback.
9. Trabalho realizado continua contabilizado mesmo em rodada desconsiderada ou inventário reprovado. Tarefas encerradas sem confirmação não permanecem pendentes.
10. Consultas históricas continuam usando o catálogo atual. Mudanças cadastrais podem alterar a cobertura calculada de anos anteriores; congelamento histórico está fora deste recorte.

## Contexto dos repositórios e referência visual

Os checkouts backend inspecionados contêm documentos de planejamento, não a implementação persistida de inventário. Nomes de classes, tabelas e endpoints novos são propostas a reconciliar com as entregas efetivas, sem criar outro domínio ou fontes fictícias.

| Repositório | Referência e integração futura |
| --- | --- |
| `rex-back` | Documentação isolada em `feature/eng-3119`, worktree `rex-back-eng-3119`, criada do commit documental `58a9cf80` da ENG-3118. A implementação dependerá dos contratos efetivamente entregues. |
| `rex-front` | O painel está na `dev`, inspecionada em `f12bbe11`, e em `origin/dev`, então em `7842ccc1`. Foi introduzido pela ENG-3084, commit `d1b2acaa`. Não está no snapshot `eng-2966` (`67305ddb`) anteriormente usado como referência do fluxo de inventário. |
| `Rex-Estoque` | Nenhuma alteração nesta issue. Consumir as tarefas e confirmações persistidas pelas ENG-3116/3117. |

Arquivos visuais encontrados em `rex-front:origin/dev`:

- `src/pages/Dashboard/components/InventoryDashboard/InventoryDashboard.jsx` e `InventoryDashboard.css`;
- `src/pages/Dashboard/components/InventoryDashboard/inventoryDashboard.data.js` e seu teste;
- `src/pages/Dashboard/Dashboard.jsx` e `dashboardTabs.js`;
- `e2e/inventory/dashboard.spec.mjs`.

O painel usa ECharts, três cards e dois gráficos, com tabelas alternativas acessíveis. A badge atual é um `span` estático. O mock importa atores de `Inventory/catalog.mjs` e força a soma de tarefas por responsável a coincidir com os totais de produtos; ambas as dependências devem sair do runtime real.

Reaproveitar o painel sobre o fluxo persistido das dependências. Não incorporar toda a `dev` apenas para obter esses arquivos, não substituir a aplicação pelas simulações e não trocar branches ou alterar os planos de outras sessões. Este documento no backend é a referência comum aos dois repositórios.

## Abordagens consideradas

| Abordagem | Benefícios | Custos ou riscos |
| --- | --- | --- |
| **API de agregados locais por ano — escolhida** | Centraliza regras e acesso; transmite somente totais; permite uma leitura consistente de todos os blocos. | Exige consultas e índices adequados, além de medição com volume realista. |
| Calcular no navegador | Menor agregação inicial no servidor. | Exige buscar muitos registros/páginas, duplica regras e dificulta consistência e autorização. |
| Resumos próprios persistidos | Pode reduzir custo de leitura em volumes maiores. | Introduz sincronização, invalidação e risco de desatualização sem necessidade demonstrada. |

Não criar projeções assíncronas, cache persistido de indicadores, event sourcing ou um framework genérico de dashboards nesta entrega.

## 1. Arquitetura, acesso e desempenho

### Fronteira de consulta

Estender o domínio de inventário e usar o transporte HTTP autenticado existente. Proposta de endpoint: **`GET /api/v1/inventory/dashboard?year=2026`**. O ano é ilustrativo, nunca uma constante de runtime. Reconciliar o prefixo literal com as rotas entregues e registrar `dashboard` antes de identificadores dinâmicos.

A API autoriza explicitamente Administrador/Master com sessão ativa na Expedição, incluindo o acesso cadastral/contexto exigido pelas dependências. Não depender apenas do menu nem de bypass global de Master. Não devolver dados, nomes ou anos de outros setores/depósitos.

A resposta contém somente ano selecionado/atual, anos disponíveis, horário de referência/fuso, totais de cobertura, até 12 posições mensais e uma linha agregada por responsável. Não incluir IDs/listas de inventários, produtos, tarefas, endereços, leituras, revisões, quantidades de estoque ou parâmetros de integração.

### Consultas e consistência

- Reutilizar o predicado do catálogo elegível da ENG-3113 e os resultados finais aprovados da ENG-3118. Não chamar uma listagem paginada para juntar todas as páginas.
- Agregar no PostgreSQL; não hidratar coleções de inventários ou tarefas para somá-las em PHP.
- Manter número fixo de consultas de agregação, sem N+1 por produto, inventário, mês ou pessoa. Unir fontes previamente agregadas para não multiplicar linhas por endereços, rodadas ou revisões.
- Todos os blocos e anos disponíveis devem vir de um snapshot consistente. Usar uma instrução agregada ou, se houver múltiplas consultas, transação curta de leitura com snapshot repetível, sem `FOR UPDATE`, locks operacionais ou alteração global de isolamento.
- Verificar planos de execução, índices existentes e volume representativo. Aplicar novos índices somente quando justificados, com migration/rollback restritos a eles; não criar tabelas de indicadores.
- O tamanho da resposta cresce com meses, anos e responsáveis, não com a quantidade de tarefas/produtos/inventários.

Carregar somente ao ativar a aba e buscar somente o ano escolhido. Não bloquear as demais abas, pré-carregar todos os anos ou disparar requisições por gráfico/pessoa. Atualizar os blocos atomicamente no cliente e ignorar respostas obsoletas.

A API única não é uma garantia de velocidade por si só. O plano de execução deve registrar dataset, ambiente, número de consultas, tamanho da resposta e tempos, incluindo percentis e comparação entre volumes. Se algum gráfico permanecer gargalo, rever sua separação antes do aceite, preservando contexto, ano e regras de consistência; não mascarar custo com dados incompletos ou simulados.

## 2. Cobertura anual e evolução

### Universo e produtos inventariados

Definir `E` como o conjunto de `products.id` distintos elegíveis **agora** no catálogo da Expedição, pela mesma regra da ENG-3113: vínculo a pelo menos um endereço desse contexto, sem condição sobre saldo. Endereços, OPs e linhas de item repetidas não ampliam o universo.

Para o ano selecionado, definir `I` como os produtos de `E` com pelo menos um resultado final incluído na consolidação imutável de inventário **aprovado localmente naquele ano**. Consumir os vínculos oficiais e a decisão terminal da ENG-3118; não inferir aprovação por concordância entre rodadas ou por evento textual.

Regras:

- Resultado final completo com quantidade zero é elegível. Não usar `quantidade > 0` como condição.
- Produto abortado não possui quantidade final e não contribui. Se foi abortado em uma rodada, mas entrou validamente na consolidação por outra, pode contribuir.
- Rascunhos, inventários em andamento/conferência/aguardando aprovação e inventários reprovados não contribuem.
- Rodadas desconsideradas e decisões retiradas não são fontes oficiais válidas. Não recomputar nem substituir as decisões congeladas.
- Produto repetido em inventários aprovados, rodadas, endereços ou revisões conta uma vez por ano.
- Usar a identidade local persistida, não código/descrição, identidade composta da fixture ou quantidade física.

Indicadores: `total = |E|`, `inventariados = |I|`, `pendentes = total - inventariados`, `completude = 100 × inventariados / total`, com uma casa decimal para exibição. Preservar os totais inteiros; não arredondar parcelas nem encobrir incoerências com clamps.

Se `E` estiver vazio, retornar totais zero e um estado explícito de catálogo vazio; mostrar “Sem produtos elegíveis”, não 100% de completude. A apresentação do percentual fica não aplicável, sem divisão por zero ou progresso acessível enganoso.

A interseção com `E` vale também para anos anteriores. Produto que deixe de ser elegível não permanece no numerador desse painel; seu resultado histórico continua íntegro nas consultas de inventário. Novos produtos entram como pendentes até terem aprovação válida naquele ano. Não prometer uma referência cadastral histórica congelada.

### Calendário e curva acumulada

Derivar ano corrente, limites anuais e mês de um mesmo horário do servidor e do fuso configurado da aplicação/instância, nunca do relógio do navegador. Usar intervalo semiaberto `[início do ano, início do ano seguinte)` para o timestamp efetivo da aprovação terminal. O início do inventário não define o ano da cobertura.

Para cada produto elegível de `I`, usar sua **primeira aprovação válida dentro do ano selecionado**. Aprovação em ano anterior não dispensa nova cobertura no ano seguinte. Reaprovar o produto em outro inventário no mesmo ano não incrementa outro mês.

O acumulado de um mês é a quantidade de produtos cujo primeiro timestamp de aprovação no ano ocorreu até o fim daquele mês. Meses passados sem novas aprovações repetem o valor anterior, incluindo zero antes da primeira aprovação.

Devolver as 12 posições ordenadas. Em anos encerrados, todos os meses têm total conhecido. No ano corrente, meses futuros usam total ausente (`null`), não previsão nem repetição que aparente dado realizado. O último ponto conhecido coincide com o card de inventariados. Ajustar tooltips, texto acessível e tabelas para zeros, valores constantes e meses futuros, sem afirmar crescimento até dezembro.

## 3. Tarefas por responsável

Selecionar inventários do contexto cujo timestamp persistido de início pertença ao ano escolhido, com os mesmos limites/fuso do calendário. Considerar todas as suas tarefas reais, inclusive recontagens e produtos históricos que já não pertençam ao catálogo elegível atual. O catálogo atual restringe a cobertura, não apaga trabalho operacional histórico.

A unidade é a **tarefa por rodada + produto + endereço**, não produto distinto, revisão ou etiqueta. A mesma pessoa pode realizar tarefas equivalentes em rodadas distintas; cada uma conta separadamente.

| Estado atual da tarefa/etapa | Indicador |
| --- | --- |
| Possui confirmação persistida vigente, inclusive zero | Realizada, uma única vez. |
| Sem confirmação e rodada/inventário ainda permitem contagem | Pendente, atribuída ao responsável persistido ou ao grupo “Sem responsável”. |
| Sem confirmação e rodada encerrada/desconsiderada, ou inventário fora da etapa de execução | Não entra como realizada nem pendente. Não transformar aborto em realização. |

Uma confirmação de tarefa continua sendo trabalho realizado se o produto ficou incompleto, a rodada foi desconsiderada ou o inventário reprovado. Isso não concede cobertura anual. Correções substituem a revisão vigente e não aumentam o número de tarefas realizadas.

A condição de etapa aberta não depende de presença online ou de o responsável continuar no catálogo atual de participantes. A revogação de acesso não apaga a atribuição nem uma pendência ainda não encerrada. Não reatribuir, liberar ou alterar tarefa durante uma consulta.

Agrupar por identidade persistida do responsável, conservando usuários históricos conforme as dependências. Nomes iguais não unem pessoas. Retornar somente linhas com tarefas realizadas/pendentes, em ordem estável, e uma única linha de responsável nulo quando houver pendências abertas. Não inserir participantes demonstrativos ou linhas para forçar totais.

O gráfico acompanha a situação **atual**, não a posição no fim do ano escolhido: uma tarefa de inventário iniciado em dezembro e confirmada em janeiro atualiza a visão do ano de início. A cobertura daquele produto pertence ao ano da aprovação. Explicitar essa diferença na interface.

**Não exigir igualdade entre soma das tarefas e os cards de produtos distintos.** Remover essa premissa do validador/testes do mock, bem como legendas e tooltips que chamam tarefas de produtos.

## 4. Anos, interface e recuperação

Anos disponíveis: ano corrente mais os anos de início de inventários e de aprovação local no contexto consultável, sem duplicação e em ordem decrescente. Um inventário iniciado em um ano e aprovado em outro pode tornar ambos disponíveis. Não criar anos de demonstração; rascunho sem início/aprovação não cria competência operacional.

Ano omitido usa o ano corrente do servidor. Ano malformado, futuro ou não disponível é erro de validação, não troca silenciosa para outro ano. A validação não deve revelar anos de outros contextos.

Preservar `InventoryDashboard`, seus três cards e dois gráficos ECharts, removendo “Dados simulados”, o argumento padrão do mock e imports transitivos de catálogo/store/model locais. Dados sintéticos são permitidos somente nos testes.

No local da badge, apresentar botões/badges de ano com seleção visível e programática, operação por teclado, foco e quebra/rolagem adequada em telas estreitas. Manter ano e aba selecionados na URL para recarga, links e voltar/avançar do navegador, sem storage de inventário. Reconciliar nomes dos parâmetros sem refatorar a navegação das demais abas.

Identificar os conceitos: produtos aprovados no ano, catálogo atual, e “Tarefas de inventários iniciados em [ano] — situação atual”. Responsáveis numerosos precisam continuar consultáveis sem cortar linhas, sobrepor rótulos ou esconder totais arbitrariamente; preservar tabelas acessíveis equivalentes aos gráficos.

Estados e falhas:

- Carregamento não apresenta zero confirmado. Ao mudar ano, não rotular números antigos com o ano novo.
- Sucesso sem aprovações: zero inventariados e todos os produtos elegíveis pendentes; curva conhecida em zero. Isso é diferente de catálogo vazio.
- Sucesso sem tarefas: estado vazio do gráfico operacional, sem fabricar responsáveis.
- Falha: mensagem legível e nova tentativa, sem converter em vazio/zero ou usar fixture/storage como fallback.
- `401/403`: seguir sessão/acesso existentes e limpar conteúdo incompatível. Parâmetros inválidos: `422` com erro legível. Indisponibilidade de configuração/dados necessários: erro explícito, não contexto presumido.
- Troca de ano, sessão, setor, aba ou desmontagem invalida respostas antigas. A resposta precisa corresponder ao contexto/ano solicitado antes de atualizar gráficos, cards e badges.

Não ler, migrar, gravar ou apagar chaves de inventário do protótipo. Não mostrar aprovação/integração simulada nem carregar resultados brutos para completar a API.

## 5. Validação e aceite

### Backend

- Universo com vários endereços/itens/OPs por produto, saldo positivo/zero e ausência de filtro quantitativo; contexto e catálogo iguais aos da ENG-3113.
- Resultado oficial final aprovado, incluindo zero, duplicidade entre inventários, produto abortado em uma rodada e incluído por outra, aborto final, reprovação e todos os estados não aprovados.
- Primeira aprovação no ano, repetições, aprovações em anos diferentes, intervalos anuais/mensais no fuso configurado e início/aprovação em anos diferentes.
- Curva cumulativa, meses conhecidos sem movimento, futuros ausentes e igualdade entre último ponto conhecido e card.
- Catálogo vazio, mudança de elegibilidade e consulta histórica recalculada pelo catálogo atual, sem alterar resultados históricos.
- Duas rodadas/recontagens independentes, correções sem dupla contagem, zero, tarefas confirmadas de etapas desconsideradas/reprovadas, encerramento sem confirmação e grupo sem responsável.
- Cohort de início do inventário, situação atual inclusive após virada do ano, usuários históricos e ausência de N+1/multiplicação de linhas.
- Acesso contextual, anos sem vazamento, validação do ano e leitura sem escrita, movimento de estoque ou chamada ERP.
- Leitura consistente durante confirmação/aprovação/encerramento concorrente: resposta inteira anterior ou posterior ao commit, nunca mistura de blocos.
- Desempenho com volume representativo, planos de execução, número fixo de agregações e resposta resumida. Novos índices, se necessários, exigem teste e rollback seguro.

### Frontend e integração

- Preservar composição e responsividade do painel encontrado na `dev`; badges/teclado/foco, ano e aba na URL, voltar/avançar e recarga em ano anterior.
- Conferir que cards, gráficos, tooltips e tabelas representam exatamente a mesma resposta; tarefas não são rotuladas como produtos.
- Carregamento, catálogo vazio, ano sem aprovações, gráfico sem tarefas, erro/retry, parâmetros inválidos, sessão revogada e respostas atrasadas após troca de contexto.
- Buscar somente a aba ativa e o ano selecionado; não bloquear demais abas nem criar uma consulta por gráfico/responsável.
- Provar isolamento do runtime de mocks/store/storage e ausência de chamadas ERP.
- Smoke com backend/PostgreSQL reais de testes: contagem, consolidação/aprovação e nova consulta, inclusive após recarga e em outra sessão autorizada. Respostas interceptadas testam a UI, mas não comprovam persistência.

Seguir `AGENTS.md` e `docs/testing-database.md`. Runtime de execução compatível com `composer.json` (PHP `^8.4`); banco exclusivamente descartável após preflight, sem resets concorrentes no mesmo schema. O planejamento não executa migrations, testes funcionais, consultas ao banco ou chamadas ERP.

## Dependências e próximo artefato

| Entrega | Contrato consumido |
| --- | --- |
| ENG-3113 | Contexto configurável, autorização, identidade local e catálogo elegível sem saldo. |
| ENG-3114 | Início persistido e fotografia das operações históricas; nenhum bloqueio é alterado pelo dashboard. |
| ENG-3115 | Consultas gerenciais e histórico, quando entregues, sem duplicação ou dependência artificial. |
| ENG-3116 | Responsável persistido, tarefas independentes por rodada/endereço-produto e tarefas abertas. |
| ENG-3117 | Confirmação vigente, zero explícito e revisões de correção. |
| ENG-3118 | Consolidação final, produtos incluídos/abortados, situação terminal e timestamp de aprovação local. |
| ENG-3084 / frontend `dev` | Composição visual e integração existente da aba de inventário. |

Ordem para o plano: reconciliar contratos e orçamento de desempenho → agregações e consistência → API/autorização → adaptar painel e badges → integração, desempenho e regressão. Se uma dependência não entregar os fatos necessários, registrar bloqueador; não construir tabelas artificiais ou responder vazio para simular integração.

Ficam fora: saldo/ajustes ERP, novas operações de inventário, aplicação nativa, fotografias anuais, projeções/cache persistidos, exportação, filtros adicionais, atualização em tempo real, importação de estado local e refatoração global de componentes.

O [plano detalhado de implementação](2026-11-06-eng-3119-dashboard-inventario-dados-reais-implementation-plan.md) organiza dez tarefas por arquivo, dependência e validação. A implementação foi autorizada depois da aprovação deste desenho; o progresso e as validações parciais estão registrados no plano e em `docs/validation/eng-3119/`.

## Referências

- ENG-3119 e decisões aprovadas nesta conversa, incluindo a condição de desempenho da API única.
- [ENG-3113 — Design](2026-11-05-eng-3113-inventario-manual-design.md) e plano correspondente.
- [ENG-3114 — Design](2026-11-05-eng-3114-inicio-inventario-bloqueio-wms-design.md) e plano correspondente.
- [ENG-3116 — Design](2026-11-06-eng-3116-distribuicao-tarefas-contagem-design.md) e plano correspondente.
- [ENG-3117 — Design](2026-11-06-eng-3117-modalidades-registro-contagens-design.md), commit `70cd36d5`.
- [ENG-3118 — Design](2026-11-06-eng-3118-conferencia-encerramento-local-design.md), commit `4ae97f8a`, e [plano](2026-11-06-eng-3118-conferencia-encerramento-local-implementation-plan.md), commit `58a9cf80`.
- ENG-3115: documentos em `rex-back-eng-3115/docs/plans/2026-11-05-eng-3115-consulta-inventarios-*.md`, commit `5bffa2d7`, consultados sem modificações.
- Frontend `dev`/`origin/dev`: painel da ENG-3084, `Dashboard.jsx`, `dashboardTabs.js`, dados simulados e testes identificados acima.
- Comentário de alinhamento de 04/11/2026 na ENG-3078: primeira entrega sem ERP e dashboard com cobertura, evolução e tarefas.
