# Refatoração Dashboard Logística → API V2 — PRD bruto

## Problema / dor

O sinal `componentes/Missoes/Logistica/sinais/Dashboard/` (rota `/missao/logistica/dashboard`) está fora do padrão arquitetural V2 desacoplado adotado nas referências canônicas (`Mensageria/Otp` e `Logistica/Edicaorota`):

1. **Não consome `/api/v1`** (Plataforma/sinais/Api). O frontend (`html/dashboard.js`) usa o canal legado `data-acao-elemento="sendToGalaxia"` + `data-acao-dados=...` para todas as interações (filtrar, ações em missão, abrir detalhes).
2. **Controller "fat"** — `Dashboard.php::renderDashboard` orquestra 9 chamadas ao Laboratório montando a view; `Dashboard.php::filtrarDashboard` **concatena HTML em strings PHP** (linhas ~215-237 para veículos e ~252-269 para rotas) e devolve em `html_kanban`/`html_veiculos`/`html_rotas` para o JS dar `.html(...)`. Isso fere (a) "controller é dispatcher fino", (b) "HTML mora em `html/` ou Luz components".
3. **Sinal `DashboardApi` paralelo e desconectado** — `Logistica/sinais/DashboardApi/` expõe API "JSON pura" via `/labs/apis/Logistica/DashboardApi/...`, que é **outro caminho ainda**, não o `/api/v1` oficial. O Dashboard não consome esse DashboardApi. Duas implementações paralelas.
4. **Sem rotas registradas** em `Plataforma/sinais/Api/Routes.php` para o Dashboard.
5. **HTML inline no PHP do controller** dificulta i18n nas 3 línguas (pt-br/en/es).

## Quem usa

- **Gestor logístico** (usuário final) — vê o dashboard, filtra, executa ações em missões, abre detalhes.
- **Time de devs Genesis** — precisa que o sinal siga o padrão V2 para manutenibilidade, testabilidade e consistência com Otp/Edicaorota.
- **Futuras integrações externas** — eventualmente consumirão `/api/v1/dashboard/...` (mesmo que hoje seja API interna do frontend Genesis).

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

- O frontend `dashboard.js` consome **`/api/v1/dashboard/*`** (com JWT) em vez de `sendToGalaxia`. JSON puro vindo do servidor; render client-side.
- Existem handlers em `Plataforma/sinais/Api/Handlers/Dashboard/` cobrindo, no mínimo, as 9 operações que hoje estão no `renderDashboard` (resumo operacional, listar missões, desempenho, alertas, tipos de missão, extrato, visão geral do dia, status de veículos, rotas do dia) + filtrar + ação em missão + detalhes.
- Rotas registradas em `Plataforma/sinais/Api/Routes.php` no mesmo padrão de Otp/EdicaoRota.
- `Dashboard.php` vira **dispatcher fino**: só renderiza o shell HTML inicial e expõe Luz components; toda lógica de dados sai pelos handlers.
- Validators dedicados em `Validators/<Acao>Validator.php` para input dos handlers.
- Sem HTML concatenado em string dentro de PHP — usar Luz components ou render client-side em JS.
- A experiência visual do usuário no dashboard **não pode regredir** — mesmo layout, mesmos filtros, mesmas ações funcionando.

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

- **Não** mexer no `DashboardLaboratorio` além do mínimo necessário para os handlers chamarem-no (a lógica de dados continua válida).
- **Não** redesenhar o dashboard nem trocar visualizações/UX.
- **Não** mexer nos outros sinais de Logística (Edicaorota, Board, Central, Armazem, Mapas, etc.) — escopo é só `Dashboard` + criação dos handlers no `Plataforma/sinais/Api`.
- **Não** abrir a API publicamente — segue gateada (interna), respeitando `Config::DEV_USER_IDS` para `/docs`.
- **Não** apagar o sinal `Logistica/sinais/DashboardApi/` nesta feature — apenas decidir o destino (recomendar deprecação) e documentar; remoção fica para feature seguinte.
- **Não** remover `Logistica/sinais/Armazem copy/` (lixo evidente) — fora de escopo.
- **Não** migrar i18n inline existente — só não introduzir pior; correção completa de strings fica para feature de i18n dedicada.

## Restrições conhecidas

- API `/api/v1` é **interna** (frontend Genesis). Manter JWT e gating de `/docs`/`/openapi.json` por `Config::DEV_USER_IDS`.
- Código novo é **V2 (Sondas)** — proibido estender Inteligencias.
- Migrations versionadas em `Migrations/NNN_*.sql` se houver alteração de schema (provavelmente não há nesta feature — só refactor).
- Multi-tenant: respeitar `customerControl`/`companyControl` e colunas `block_*` (sem `DEFAULT 1`).
- Nada de raw SQL via `Connect::getInstance` para writes — usar `->update()`/`->create()` da Sonda.
- Testes integration rodam só em `dev_gx_goldie`.

## Inspirações / referências

- **`componentes/Missoes/Logistica/sinais/Edicaorota/`** — referência canônica V2 de "fluxo de domínio": dispatcher fino, Validators, Adapters, Callbacks/Registry, Migrations versionadas, Testes/. Ver também `Edicaorota/COMPARACAO_FRAMEWORK.md`.
- **`componentes/Missoes/Mensageria/sinais/Otp/`** — referência canônica V2 de "capability".
- **`componentes/Missoes/Plataforma/sinais/Api/Routes.php`** — linhas 23-26 (EdicaoRota) e ~36 (Otp) mostram o estilo de registro de rota.
- **`componentes/Missoes/Plataforma/sinais/Api/Handlers/EdicaoRota/AprovarHandler.php`** — modelo de handler.
- **`componentes/Missoes/Plataforma/sinais/Api/Handlers/Otp/CriarHandler.php`** — modelo alternativo.

## Métricas de sucesso

- 100% das interações de `dashboard.js` passam por `fetch('/api/v1/dashboard/...')` (zero `sendToGalaxia` no JS do dashboard).
- 0 strings HTML concatenadas em `Dashboard.php` (busca por `'<tr` `'<div` no controller deve voltar vazio).
- `Plataforma/sinais/Api/Routes.php` tem ≥10 rotas `/dashboard/*` registradas.
- Testes TDD em `Logistica/sinais/Dashboard/Testes/` cobrindo handlers e fluxos críticos passando.
- Visualização do `/missao/logistica/dashboard` permanece idêntica para o gestor (regressão visual zero).

## Notas

- O `Dashboard.php` atual mistura duas responsabilidades (render inicial + dispatcher de ações). Após refactor, a renderização inicial pode permanecer no controller (para SSR do shell) mas o `filtrarDashboard`/`detalhesMissao` desaparecem, virando handlers de API consumidos pelo JS.
- Considerar se `renderDashboard` deve fazer SSR de todos os 9 blocos ou se o JS busca tudo via API depois do load (tradeoff: TTI vs simplicidade). PO decide.
- Débito técnico relacionado (fora de escopo, mas registrar): (a) sinal `DashboardApi` paralelo, (b) `Armazem copy/` lixo, (c) HTML inline em `dashboard.php` precisa de auditoria de i18n.
- Branch base: `dev_team` (a partir de hoje 2026-05-04).