# Onda 1 — UX Foundation + Dúvidas em Aberto — PRD bruto

> Parte do refinamento [`PRD/dashboard-operacional-refinamento/`](../../00-prd.md). Restrições globais herdadas — ver guarda-chuva.

## Problema / dor

A primeira leva do `dashboard-operacional` (mergeada em `dev_team`) entrou com **8 dúvidas explicitamente em aberto** registradas no `PRD/dashboard-operacional/01-spec.md` (seção "Dúvidas em aberto") e com **débito visual** vs o protótipo React documentado em `componentes/Missoes/Logistica/sinais/Dashboard/frontend-documentacao.md`. Isso impede que as ondas seguintes (drilldown, exportação, alertas) construam em cima de fundação estável: cada onda repete decisão sobre datepicker, persistência de estado, cache, definição de "erro do conferente", etc.

A onda 1 **fecha essa fundação**: decide tudo o que ficou em aberto, alcança paridade visual, e padroniza skeleton/loading. Sem isso, as ondas 3-5 colocam abstrações em cima de variáveis indefinidas.

## Quem usa

- **Gestor logístico / supervisor** — sente o débito visual (cores semafóricas inconsistentes, sparklines tortas, sem skeleton durante re-fetch).
- **Coordenador de separação / expedição** — depende da definição final de "carga com erro" para confiar nos números de assertividade.
- **Time de devs Genesis** — herda decisões fechadas (chart lib, datepicker, persistência URL, cache) pra não reabrir nas ondas seguintes.

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

### Fechar as 8 dúvidas em aberto do PRD anterior

1. **Persistência período + aba** — escolher querystring (compartilhável por link) vs `sessionStorage`; PO já recomendava querystring. Implementar.
2. **Chart lib** — TL audita o que já existe no Genesis (procurar `apexcharts`, `chart.js`, `echarts` em `componentes/`). Se nada existir, recomendar **ApexCharts** (maior cobertura) ou **Chart.js** (mais leve). Decidir e adotar **uma única lib** pro dashboard inteiro.
3. **DateRange picker** — TL audita (`litepicker`, `flatpickr`, `bootstrap-datepicker`). Adotar a já-presente; se nenhuma, escolher **Litepicker** (pequeno, Bootstrap-friendly).
4. **Cache curto de séries diárias** — implementar cache server-side de 5–15 min em handlers de série diária por chave `(customer, range, tipo)`. Avaliar `apcu`/`memcached`/`redis` conforme o que o Genesis já usa em outros sinais.
5. **Auditoria/poda dos 12 handlers `/api/v1/dashboard/*`** da feature anterior — listar quais sobrevivem, quais migram, quais são removidos. (Pode rolar aqui ou na onda 2; TL decide no techplan.)
6. **Mapeamento Sondas ↔ tabelas reais** — validar em `dev_gx_goldie` que `RotaSeparacao`, `ParticipacaoSeparacao`, `Carregamento`, `ErrosMotorista`, `Pessoa` batem com colunas/relacionamentos reais. Documentar no `02-techplan.md`.
7. **Destino do `frontend-documentacao.md`** — hoje untracked. Decidir: (a) commitar como está dentro do sinal (referência viva), (b) mover para `PRD/dashboard-operacional-refinamento/` como anexo, (c) remover (já cumpriu seu papel). PO/TL decidem.
8. **Definição de "carga com erro"** para assertividade do conferente — validar com coordenador de expedição: qualquer `errosMotorista[]` não-vazio conta? Ou só tipos específicos (avaria_transporte não conta porque não é culpa do conferente)?

### Paridade visual com o protótipo React

- Cores semafóricas aplicadas consistentemente em todos os pontos definidos no `01-spec.md` da feature anterior (≥95/≥88 verde/amarelo/vermelho para assertividade; ≥70/≥45 para score; ≥95/≥85 para eficiência de fluxo; 0/1-3/≥4 para overnight).
- Sparklines dos 6 KPIs renderizados com a chart lib escolhida no item 2.
- Badges de score/assertividade nos rankings.
- Skeleton/loading consistente em **todos os blocos** (KPIs, séries, rankings) durante re-fetch ao trocar período/aba.

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

- **Não** trazer drilldown, filtros adicionais, exportação, comparativo, metas, alertas ou histórico — são as ondas 3-5.
- **Não** quebrar `dashboard.js` em módulos — é a onda 2. Aqui aceita-se acréscimo no arquivo monolítico atual; o refactor vem depois.
- **Não** alterar schema do banco — herda restrição original (dados existem).
- **Não** abrir `/api/v1` publicamente.
- **Não** trazer React/Vite/Tailwind/shadcn/Recharts pro repo Genesis.
- **Não** mudar a rota `/missao/logistica/dashboard` ou criar sinal novo — reusa o existente.
- **Não** mudar autenticação/autorização.

## Restrições conhecidas

Ver [restrições globais](../../00-prd.md#restrições-globais-herdadas-em-todas-as-ondas) do guarda-chuva.

Específicas desta onda:

- Chart lib e datepicker escolhidos **vinculam as ondas seguintes** — decisão custosa de reverter, então TL precisa fundamentar.
- Cache de handlers não pode quebrar testes de integração em `dev_gx_goldie` — Tester valida que cache invalidation funciona em re-fetch.
- Paridade visual **não** significa pixel-perfect com React; significa **mesma hierarquia de informação, mesmas cores semafóricas, mesmas regras de agregação**.

## Inspirações / referências

- `PRD/dashboard-operacional/00-prd.md` e `01-spec.md` — base; ler primeiro pra herdar regras de negócio.
- `componentes/Missoes/Logistica/sinais/Dashboard/frontend-documentacao.md` — fonte canônica do design React, fórmulas e estruturas de dados.
- `componentes/Missoes/Logistica/sinais/Dashboard/html/dashboard.{php,js}` — estado atual, alvo do polimento.
- `componentes/Missoes/Plataforma/sinais/Api/Handlers/Dashboard/` — handlers atuais, alvo da auditoria/poda.
- `componentes/Missoes/Logistica/sinais/Edicaorota/` e `componentes/Missoes/Mensageria/sinais/Otp/` — referências canônicas V2.

## Métricas de sucesso

- 8/8 dúvidas em aberto do PRD anterior **fechadas** (registradas no `02-techplan.md` com decisão e justificativa).
- Auditoria documental dos 12 handlers `/api/v1/dashboard/*` (mantidos / removidos / migrados).
- Cores semafóricas consistentes em screenshots lado-a-lado vs protótipo React (validação visual no review).
- Skeleton/loading em <100ms após troca de período/aba (mantém AC8.3 do PRD anterior).
- p95 dos handlers de série diária **com cache** < 200ms para período de 30 dias em `dev_gx_goldie` (melhora vs <500ms anterior).
- Zero regressão funcional vs estado atual em `dev_team` (Tester valida com integration suite existente).

## Notas

- **Branch**: `feature/dashboard-operacional-ux-foundation`.
- Esta onda é **pré-requisito** para todas as outras (ver `roadmap.md`).
- Se a auditoria de handlers (item 5) for grande, TL pode mover pro escopo da **onda 2** (refactor) e aqui só registrar a decisão.
- **`frontend-documentacao.md`** (item 7): se a decisão for "remover", remover **ao final da onda 5** (último consumidor) — aqui apenas registrar a intenção. Se for "commitar/mover", fazer já nesta onda.
- A definição de "carga com erro" (item 8) **muda os números** de assertividade do conferente — comunicar coordenador antes do release.