# Dashboard Operacional (KPIs / Rankings / Erros) — PRD bruto

## Problema / dor

Existe um protótipo/POC documentado em `componentes/Missoes/Logistica/sinais/Dashboard/frontend-documentacao.md` (React+Vite+TS+Tailwind+Recharts) que define um **dashboard operacional muito mais rico** do que o kanban atual:

- 6 KPIs no topo com sparklines (Separações, Carregamentos, Itens Separados, Cubagem, Eficiência de Fluxo, Pendências Overnight)
- 3 abas (Visão Geral / Separação / Carregamento) com filtro de período global (DateRange)
- Time series (AreaChart/BarChart) e comparativos mensais
- Rankings de separadores e conferentes com scores ponderados, assertividade, retrabalho, erros tipados
- Detalhamento de tipos de erro (trocado/falta/sobra para separação; faltando/trocado/avaria/endereço errado para carregamento)
- Cards semafóricos por faixa de assertividade/score

O dashboard atual em `/missao/logistica/dashboard` (kanban de missões/veículos/rotas — recém-refatorado para padrão V2 em `feature/dashboard-logistica-api-v2`) **não cobre essa visão de performance operacional** e precisa ser **substituído** por essa nova UI.

## Quem usa

- **Gestor logístico / supervisor** — acompanha KPIs operacionais, identifica gargalos, premia/treina pessoas com base em assertividade/score.
- **Coordenador de separação** — vê ranking de separadores, tipos de erro, tempo médio por item.
- **Coordenador de expedição** — vê ranking de conferentes, índice de retrabalho, erros do motorista.
- **Time de devs Genesis** — precisa que essa UI siga o padrão V2 (handlers em `Plataforma/sinais/Api`, dispatcher fino, frontend Genesis-stack).

## O que precisa fazer (alto nível)

- Substituir a rota `/missao/logistica/dashboard` (kanban atual) pela **nova UI operacional** descrita em `frontend-documentacao.md`.
- **Stack Genesis padrão**: PHP view (shell) + vanilla JS + biblioteca de chart compatível (Chart.js ou ApexCharts — TL decide). **Sem React/Vite/Tailwind.** Sem build step novo.
- Consumir **exclusivamente** `/api/v1/dashboard/*` (padrão V2 — Plataforma/sinais/Api). Nada de `sendToGalaxia`, nada de SSR de tabelas/listas grandes.
- Filtro de período global (DateRange) propaga para todas as queries via querystring nos handlers.
- 3 abas client-side: **Visão Geral**, **Separação**, **Carregamento**. Estado das abas + período persiste na sessão/URL (definir na spec).
- 6 KPIs com sparklines no topo — fixos em todas as abas.
- Rankings paginados com scores ponderados (fórmulas no doc: `frontend-documentacao.md` §6, §7, §9).
- Cards/scores com cor semafórica (≥95/≥88 verde/amarelo/vermelho para assertividade; ≥70/≥45 para score).
- i18n nas 3 línguas (pt-br/en/es) para todos os labels novos.
- Sondas/agregações novas em `Logistica/sinais/Dashboard/Sondas/` (ou compartilhadas em `Constelacoes/`) cobrindo o domínio de **separação** (RotaSeparacao, ParticipacaoSeparacao) e **carregamento** (Carregamento, ErrosMotorista).

## O que NÃO precisa fazer (escopo negativo)

- **Não** trazer React/Vite/Tailwind/shadcn/Recharts para o repo Genesis. A documentação React é apenas referência de design e fórmulas.
- **Não** criar um novo sinal — reusar o sinal `Logistica/sinais/Dashboard/` já refatorado em V2 (substitui a UI in-place; mantém o controller fino). Os 12 handlers `/api/v1/dashboard/*` da feature anterior **podem ser removidos/consolidados** se não fizerem sentido nesta nova UI — TL decide na sondagem.
- **Não** mexer em outros sinais de Logística (Edicaorota, Board, Central, Armazem, etc.).
- **Não** abrir `/api/v1` publicamente — segue interna com JWT/sessão Galaxia.
- **Não** migrar PRD anterior (`dashboard-logistica-api-v2`) — está mergeado em `dev_team`. Esta é uma **substituição** do JS/PHP/handlers, não uma evolução incremental.
- **Não** implementar exportações CSV/PDF nesta feature (fica para depois).
- **Não** adicionar autenticação/autorização nova — herda o que `/api/v1` já tem (JWT.customer).
- **Não** alterar o esquema do banco se as tabelas já existem (ver decisão do usuário: dados existem, só precisa Sondas/agregações).

## Restrições conhecidas

- **API `/api/v1` é interna** (frontend Genesis). Manter JWT/sessão e gating de `/docs`.
- Código novo é **V2 (Sondas)** — proibido estender Inteligencias.
- Multi-tenant obrigatório em todas as queries: `customerControl`/`companyControl`, colunas `block_*` (sem `DEFAULT 1`).
- Nada de raw SQL via `Connect::getInstance` para writes (esta feature é leitura-pesada — writes praticamente inexistentes).
- Charts: bibliotecas client-side já existentes no projeto têm preferência. Se nada existir, recomendar **ApexCharts** (peso aceitável, suporte amplo) ou **Chart.js** (mais leve). TL decide.
- Performance: como envolve agregações temporais (séries diárias por até 365 dias), **handlers devem ser cacheáveis** ou pelo menos otimizados (índices, queries enxutas). Definir na spec se cache vale a pena na rodada 1.
- Testes integration rodam só em `dev_gx_goldie` (mesmo padrão da feature anterior).

## Inspirações / referências

- **`componentes/Missoes/Logistica/sinais/Dashboard/frontend-documentacao.md`** — fonte canônica do design, fórmulas e estruturas de dados. **Ler antes de qualquer coisa.**
- **`componentes/Missoes/Logistica/sinais/Dashboard/`** — sinal já em V2 (controller fino, dispatcher), reusado para esta nova UI.
- **`componentes/Missoes/Plataforma/sinais/Api/Handlers/Dashboard/`** — 12 handlers da feature anterior; servem de molde para os novos (mesmo padrão BaseHandler + Validators).
- **`componentes/Missoes/Logistica/sinais/Edicaorota/`** — referência canônica V2 (Adapters, Callbacks, Migrations versionadas, Testes/).
- **`componentes/Missoes/Mensageria/sinais/Otp/`** — referência canônica V2 (capability + Channel registry).
- **`PRD/dashboard-logistica-api-v2/`** (recém-mergeado) — exemplo concreto de pipeline V2 ponta-a-ponta.

## Métricas de sucesso

- 100% das interações do `dashboard.js` novo passam por `fetch('/api/v1/dashboard/...')`.
- 6 KPIs do topo + 3 abas funcionando com paridade visual ao protótipo React (em screenshots lado-a-lado, layout e cor semafórica consistentes).
- Rankings ordenados pelos scores definidos em `frontend-documentacao.md` §9, validados por testes unit das funções de score.
- Filtro de período propaga corretamente: alterar DateRange dispara re-fetch coordenado dos blocos (com loading skeleton).
- Tempo de resposta dos handlers de KPI/série diária < 500ms para período de 30 dias em `dev_gx_goldie` (smoke).
- Testes integração em `dev_gx_goldie` validando que as agregações batem com os dados crus (não-mock).
- Zero `sendToGalaxia` no `dashboard.js`; zero HTML inline no `Dashboard.php`.

## Notas

- **Branch base**: `dev_team` (já contém o merge de `feature/dashboard-logistica-api-v2`). Branch desta feature: `feature/dashboard-operacional`.
- **Os 12 handlers da feature anterior podem ser podados** — provavelmente só `TiposMissaoHandler` (e talvez metadados pontuais) sobrevivem. A nova UI tem fluxo de dados completamente diferente (KPIs/rankings/séries vs kanban de missões). TL valida e propõe lista de remoção/manutenção.
- **Mapeamento Sondas → tabelas Genesis**: o usuário confirmou que os dados existem. TL precisa sondar o schema (`Constelacoes/`, `dev_gx_goldie`) e mapear:
  - `RotaSeparacao` ↔ tabela de rotas/missões de separação
  - `ParticipacaoSeparacao` ↔ tabela de participantes/itens por separador na rota
  - `Carregamento` ↔ tabela de embarque/conferência
  - `ErrosMotorista` ↔ tabela de ocorrências/erros pós-entrega
  - `Pessoa` (separador/conferente) ↔ tabela de operadores/usuários
- **DateRange picker**: definir biblioteca compatível com Genesis (Bootstrap datepicker já em uso? Litepicker? Flatpickr?). PO/TL decidem.
- **Cache**: handlers de séries diárias podem se beneficiar de cache curto (5-15 min) por (customer, range, tipo). Não é blocker pra rodada 1, mas registrar.
- **Mock determinístico** descrito no doc React (PRNG semeada, 365 dias) é só para o protótipo — **fora de escopo**. Aqui se conecta ao banco real.
- A documentação `frontend-documentacao.md` deve ser **atualizada ou substituída** ao final da feature (ela hoje descreve o protótipo React; o estado real será o Genesis-stack). Decisão final no PO/TL.
- Arquivo `frontend-documentacao.md` está untracked no repo — provavelmente nunca foi commitado. Seguir a feature trazendo-o pra dentro do PRD ou removendo após o trabalho.