# Dashboard Operacional — PRD-guarda-chuva de Refinamento

> **Este PRD é uma referência de roadmap, não é acionável diretamente.** Ele NÃO roda pelo pipeline `/genesis-feature`. Cada **onda** dentro de `ondas/NN-<slug>/` tem o seu próprio `00-prd.md` que é o que vira spec → techplan → código.

## Contexto

A feature `dashboard-operacional` foi mergeada em `dev_team` (commits `9c9fff70` → `a1b7edb4`). Ela substituiu o kanban antigo da rota `/missao/logistica/dashboard` por uma UI operacional com 6 KPIs, 3 abas (Visão Geral / Separação / Carregamento), rankings ponderados e séries temporais sobre `/api/v1/dashboard/*` (padrão V2).

Após a primeira leva em produção/staging, ficaram **gaps conhecidos** (UX, dúvidas em aberto do `01-spec.md`, refactor adiado, novas features pedidas pelos coordenadores). Este PRD organiza tudo isso num **roadmap de 5 ondas** independentes-mas-ordenadas, cada uma com seu próprio PRD pronto pra entrar no pipeline.

A intenção é poder pegar uma onda, rodar `/genesis-feature dashboard-operacional-refinamento/ondas/NN-<slug>` e ter escopo coeso pro time.

## Visão de produto

Um dashboard operacional **maduro**, capaz de:

- Responder com paridade visual ao protótipo React (cores semafóricas, sparklines, badges) — **hoje** ainda há débito visual.
- Permitir **drilldown** (clicar numa pessoa abre detalhe) e **filtros operacionais** (filial/CD, turno, tipo de rota).
- Suportar **exportação** (CSV/PDF), **comparativo** entre pessoas e **metas configuráveis**.
- Disparar **alertas** quando alguém despenca de assertividade ou pendências overnight estouram.
- Mostrar **histórico/evolução** por pessoa.
- **Integrar-se com outros sinais** de Logística (Edicaorota, Ocorrencias, Designacoes) via deep-link.

Tudo dentro do padrão V2 desacoplado do Genesis (Sondas, `/api/v1` interno, sem React/Vite, i18n nas 3 línguas).

## Personas

Herdadas do PRD original (`PRD/dashboard-operacional/00-prd.md`):

| Persona | Papel | Contato com a feature |
|---|---|---|
| Gestor logístico / supervisor | Decisor operacional | Abre o dashboard diariamente, observa KPIs, ajusta período |
| Coordenador de separação | Gestor de equipe de separação | Aba Separação, ranking, treinamento |
| Coordenador de expedição | Gestor de equipe de carregamento | Aba Carregamento, retrabalho, erros do motorista |
| Time de devs Genesis | Mantenedor | Implementa/mantém handlers, Sondas e views (V2) |

## Ondas

Resumo de 1 frase cada. Detalhe completo no PRD da onda.

1. **[ux-foundation](ondas/01-ux-foundation/00-prd.md)** — Paridade visual final + resolver as 8 "Dúvidas em aberto" do PRD anterior (datepicker, persistência URL, chart lib, cache, definição de "carga com erro", etc.).
2. **[refactor-tecnico](ondas/02-refactor-tecnico/00-prd.md)** — Quebrar `dashboard.js` (44KB) em módulos, podar handlers obsoletos, consolidar Sondas duplicadas. Refactor puro, sem mudança de UX.
3. **[drilldown-filtros](ondas/03-drilldown-filtros/00-prd.md)** — Clicar em separador/conferente abre detalhe; filtros adicionais (filial/CD, turno, tipo de rota).
4. **[exportacoes-comparativo-metas](ondas/04-exportacoes-comparativo-metas/00-prd.md)** — CSV/PDF de rankings, comparativo lado-a-lado de 2-3 pessoas, metas configuráveis com sinalização visual.
5. **[alertas-historico-integracoes](ondas/05-alertas-historico-integracoes/00-prd.md)** — Alertas (queda de assertividade, overnight estourado), histórico por pessoa, deep-links pra Edicaorota/Ocorrencias/Designacoes.

Ordem e dependências em [`roadmap.md`](roadmap.md).

## Restrições globais (herdadas em todas as ondas)

- **V2 (Sondas)** — proibido estender `Inteligencias` (V1, deprecated).
- **Multi-tenant obrigatório** — `customerControl`/`companyControl` em toda query; colunas `block_*` sem `DEFAULT 1` (framework injeta).
- **`/api/v1` é interno** — JWT/sessão Galaxia; `/docs` e `/openapi.json` gateados em `Config::DEV_USER_IDS`.
- **Sem React/Vite/Tailwind/shadcn/Recharts** no repo Genesis. Stack: PHP view (shell) + vanilla JS + chart lib client-side já adotada.
- **i18n obrigatório nas 3 línguas** (`pt-br`, `en`, `es`) — zero string hardcoded em PHP/JS.
- **Sem raw SQL via `Connect::getInstance` para writes** — usar `update()` do model.
- **Integration tests rodam só em `dev_gx_goldie`** — bootstrap precisa de `$_SESSION` em raiz + dashboard.
- **Referências canônicas V2**: `Mensageria/Otp` (channel registry), `Logistica/Edicaorota` (callback registry + Adapters). **Não imitar Designacoes/Pessoas (legado V1).**
- **`Constelacoes` é só model/banco** — HTML/views vão em `sinais/<Modulo>/html/`.
- **Controller principal** do sinal usa o nome do diretório (`Dashboard/Dashboard.php`), não `App.php`. View "index" em minúsculo (`html/dashboard.php`).

## Pipeline esperado por onda

Cada onda roda o pipeline completo:

```
PO refina 00-prd.md  →  01-spec.md
TL planeja           →  02-techplan.md
Dev backend          →  03-backend.md (Sondas, Migrations, Handlers, Validators)
Dev frontend         →  04-frontend.md (Views, JS, i18n)
QA                   →  05-testes.md (unit + integration TDD)
Reviewer             →  06-review.md
```

Branch convencional: `feature/dashboard-operacional-<slug-da-onda>`.

## Métricas de sucesso (do refinamento como um todo)

- 5 ondas concluídas (cada uma com `06-review.md` aprovado).
- Zero regressão no que já está em `dev_team` (rota `/missao/logistica/dashboard` continua acessível e correta entre ondas).
- p95 dos handlers de KPI/série diária < 500ms para período de 30 dias em `dev_gx_goldie` mantido.
- Zero `sendToGalaxia` no `dashboard.js`; zero HTML inline no controller PHP.
- Adoção: ≥80% dos coordenadores de separação/expedição abrem o dashboard ≥1×/semana após o lançamento da onda 5.

## Notas

- **Branch base** de cada onda: `dev_team` no momento do início da onda (sempre fast-forward das ondas anteriores que dependem).
- **Dependências entre ondas**: ver `roadmap.md`. Ondas 3, 4 e 5 só fazem sentido depois da ux-foundation (1) e do refactor (2). Onda 5 depende de tudo.
- **`frontend-documentacao.md`** (em `componentes/Missoes/Logistica/sinais/Dashboard/`) está untracked — o destino dele (commitar / mover pra cá / remover) é decidido na **onda 1**.
- **Auditoria/poda dos 12 handlers** `/api/v1/dashboard/*` da feature `dashboard-logistica-api-v2`: pode ser feita na onda 1 (parte das dúvidas em aberto) ou na onda 2 (refactor) — TL decide no techplan.
- **Compatibilidade entre ondas**: cada onda DEVE manter a anterior funcionando. Se uma onda mudar contrato de handler/Sonda, atualizar todos os consumidores na mesma PR.