# Comparação `EdicaoRota` × `Designacoes` — aderência ao framework Galaxia > Baseline: `componentes/Missoes/Logistica/sinais/Designacoes/` (sinal maduro, ~6 mil linhas, 6 strategies, 9 testes). > Alvo: `componentes/Missoes/Logistica/sinais/EdicaoRota/` (sinal novo, ~1,5 mil linhas, 5 testes, 64 asserções). ## Resumo executivo Aderência geral: **alta**. O sinal segue todas as convenções estruturais críticas (caminho, sufixos, V2 Sonda, separação Constelacoes×Missoes, testes TDD). As diferenças concentram-se em padrões avançados (Template Method, ISP, Factory) que **fazem sentido em Designacoes pela multiplicidade de strategies (6) e ainda não fazem em EdicaoRota** (1 fluxo, 1 callback adapter). | Categoria | EdicaoRota | Designacoes | Veredito | |---|---|---|---| | Localização do sinal | ✅ `Missoes/Logistica/sinais/EdicaoRota/` | `Missoes/Logistica/sinais/Designacoes/` | Igual | | Sufixos de classe | ✅ Laboratorio, Sonda, Validator, Strategy → Callback, Interface, Enum | Mesmos | Igual | | Sondas (V2) vs Inteligencias (V1) | ✅ Apenas Sondas | Mistura legada | EdicaoRota mais correto | | Constelacoes apenas para models/satélites | ✅ Importa só `RomaneioPedido`/`RomaneioVeiculo` | Importa Inteligencias + Satélites + Traits | Igual | | Isolamento de domínio externo | ✅ `Adapters/Romaneio/` | `Resolvers/` (papel diferente) | EdicaoRota mais explícito | | HTML em `html/` | ✅ | ✅ | Igual | | Testes TDD em `Testes//` | ✅ | ✅ | Igual | | Migrations | ✅ `Migrations/*.sql` | `db/*.sql` | Convenção diferente — ver §3 | | Observatorio()/GalaxiaAutoLoad() | ❌ Não tem | ✅ Tem | Ver §4 | | Template Method (Base abstrata) | ❌ Não tem | ✅ `GestaoMissoesBase` | OK — só 1 fluxo | | Strategy Factory | ⚠️ Substituído por `CallbackRegistry` | ✅ `DesignacaoStrategyFactory` | Conceito equivalente | | ISP (interfaces segregadas) | ❌ 1 interface | ✅ 4 interfaces | OK — só 1 capability | | Documentação interna `.md` | ⚠️ Apenas este arquivo | ✅ 5 `.md` | Ver §5 | --- ## 1. Estrutura de pastas — diff ### EdicaoRota (atual) ``` EdicaoRota/ ├── App.php ├── Adapters/ │ └── Romaneio/ │ ├── Callbacks/ │ ├── Laboratorios/ │ ├── Migrations/ │ └── Testes/Callbacks/ ├── Callbacks/ │ ├── EdicaoRotaCallbackInterface.php │ └── EdicaoRotaCallbackRegistry.php ├── Enums/ ├── Laboratorios/ (6 arquivos) ├── Migrations/ ├── Otp/ ├── Satelites/ ├── Sondas/ ├── Testes/ │ ├── Enums/ │ └── Laboratorios/ ├── Validators/ └── html/ ``` ### Designacoes ``` Designacoes/ ├── Designacoes.php (1586 linhas — entry point) ├── *.md (5 arquivos) ├── Config/ (HierarchyConfig) ├── Laboratorios/ (10, inclui GestaoMissoesBase abstrata) ├── Resolvers/ (4 — VOs / normalizers) ├── Strategies/Designacao/ (12 — interfaces + base + 6 concretas + factory) ├── Testes// ├── db/ (tabelas.sql, inserts.sql) ├── forms/ (8 — submissões de formulário) └── html/ (15, inclui components/Hierarchy/) ``` ### Pastas presentes em Designacoes e ausentes em EdicaoRota - **`Config/`** — não temos configs tipadas; nossa única "config" é `OtpSenderFactory`. Razoável dada a simplicidade. - **`Resolvers/`** — não temos value-objects nem normalizers. Caso a feature evolua para receber inputs heterogêneos (ex.: rota vinda de Coleta, de Romaneio, de TMS externo), justificaria criar. - **`forms/`** — Designacoes usa forms tradicionais Galaxia (HTML POST → satélite). EdicaoRota usa o próprio `App::handle()` como dispatcher unificado. Diferente por design — não é débito. - **`Strategies//`** — só faria sentido se houvéssemos múltiplos tipos de edição. ### Pastas presentes em EdicaoRota e ausentes em Designacoes - **`Otp/`** — específico desta feature (sender/factory). Convenção válida (cabe `/`). - **`Adapters//`** — **convenção nova** que não tem precedente direto em Designacoes. Designacoes resolve dependências de domínio importando direto (acoplamento) ou via `Resolvers/` (transformação leve). Ver §6. - **`Satelites/`** — Designacoes coloca seus satélites em `componentes/Constelacoes/Logistica/MissaoLogistica/Satelites/`. Nós colocamos no sinal (`sinais/EdicaoRota/Satelites/`). Conforme correção do usuário ("Constelacoes é só model"), nossa decisão está alinhada com a regra atualizada — Designacoes carrega aqui um padrão legado. --- ## 2. Convenções de nomeação — diff | Conceito | EdicaoRota | Designacoes | Status | |---|---|---|---| | Use case principal | `*Laboratorio` (ex.: `AprovarEdicaoRotaLaboratorio`) | `Gestao{Tipo}` (ex.: `GestaoMissoesSeparacao`) | Sufixo igual; prefixo é livre por sinal | | Persistência | `*Sonda` | (mistura `*Sonda` + `*Inteligencia` legado) | EdicaoRota só V2 | | Strategy/Polimorfismo | `*Callback` (cumpre papel similar para dispatch pós-decisão) | `*Strategy` | Conceitos diferentes, nomes intencionais | | Validator | `*Validator` | `*Validator` (parcial — alguns validate inline) | EdicaoRota mais consistente | | Interface | `{Tipo}Interface` colocada junto com implementadores (`Callbacks/`, `Otp/`) | `{Tipo}Interface` ou `{Capability}Interface` em `Strategies//` | Igual | | Enum | Backed enum com label/cssClass/transições | Backed enum com label/cssClass/transições | Igual | | Teste | `*TddTest.php` em `Testes//` | `*TddTest.php` em `Testes//` | Igual | | Factory | `OtpSenderFactory`, `EdicaoRotaCallbackRegistry` | `DesignacaoStrategyFactory` | Conceito igual | --- ## 3. Migrations: `Migrations/` × `db/` - **Designacoes** usa `db/tabelas.sql` + `db/inserts.sql` (sem versionamento). - **EdicaoRota** usa `Migrations/001_initial_schema.sql` (numerada). - O padrão **`Migrations/`** já existe no codebase em `componentes/Missoes/Logistica/sinais/Solicitacoes/Migrations/001_initial_schema.sql` — adotamos o padrão **moderno** em vez do legado de Designacoes. **Veredito:** EdicaoRota adota o padrão correto. Designacoes carrega um legado. --- ## 4. Pontos de entrada e hooks Galaxia Designacoes implementa dois hooks do framework: ```php public function Observatorio(?array $available = []) { ... } // post-action public function GalaxiaAutoLoad(?array $available = []) { ... } // routing automático ``` EdicaoRota não implementa nenhum dos dois. Em vez disso, `App::handle($acao, $params)` faz dispatch explícito por ação (`pedir_codigo`, `validar_codigo`, …, `aprovar`, `rejeitar`, …). **Implicação prática:** - Para o **gestor** acessar via painel Galaxia (UI logada), o hook `Observatorio()` poderia ajudar a refrescar listas após `aprovar`/`rejeitar` — hoje isso depende do front emitir um refresh manual. - Para o **motorista** (acesso público sem sessão Galaxia), os hooks não servem — o `App::handle` está correto. **Recomendação:** quando o painel do gestor for plugado de fato, avaliar se vale acrescentar `Observatorio()` ao `App.php` para uniformidade com Designacoes. --- ## 5. Documentação interna Designacoes tem 5 `.md` na raiz: - `PADRAO_ACOES_DINAMICAS.md` — convenção JS/PHP para ações com parâmetros dinâmicos - `PENDENCIAS.md` — tracking de débito técnico (11 itens) - `refatorar.md` — mapeamento de ~500 linhas a mover do controller para Laboratórios - `agrupamento_backend.md` / `agrupamento_frontend.md` — sínteses por feature EdicaoRota tem só este arquivo. Faz sentido — sinal recém-criado, sem débito técnico ainda. Conforme a feature evoluir, replicar o padrão (especialmente `PENDENCIAS.md` e ADRs de decisões não-óbvias). --- ## 6. Adapters/ vs Resolvers/ — convenção nova Designacoes resolve dependências de domínio externo de duas formas: 1. **Importação direta** — Laboratorios importam Inteligencias/Satélites de outras Constelacoes. Acoplamento explícito. 2. **`Resolvers/`** — para casos onde input é heterogêneo (ex.: `MissionOriginResolver` decide se id é PEDIDO ou ROMANEIO, `MissionInputNormalizer` aceita arrays planos ou hierárquicos). EdicaoRota introduziu **`Adapters//`** — uma nova convenção, ainda sem precedente no codebase. Justificativa: - O **core** do sinal (callback, otp, status, sondas) não conhece Romaneio. - A **cola** com Romaneio (callback que escreve em `romaneios_veiculos`, laboratorio que lê `sequencia_roteirizacao`, migration que altera tabela do domínio) fica isolada num único lugar. - Quando outro domínio quiser consumir EdicaoRota (ex.: Coletas), basta criar `Adapters/Coletas/` sem tocar no core. **Status da convenção:** experimental. Se outras features novas adotarem `Adapters//` em vez de importação direta, vira padrão de fato. Caso contrário, fica como solução pontual. **Trade-off versus Designacoes:** Resolvers/Designacoes são para *normalizar input no boundary*; Adapters/EdicaoRota são para *isolar um domínio externo inteiro (callback + use case + migration)*. Os papéis são diferentes — não competem. --- ## 7. Padrões avançados — onde EdicaoRota não chegou (e talvez não precise) ### a) Template Method (`GestaoMissoesBase` em Designacoes) Designacoes tem 6 strategies + algoritmo comum de "criar missão" → justifica uma classe base abstrata de 714 linhas com hooks (`aplicarRegrasNegocio`, `aplicarDeduplicacao`). EdicaoRota tem **um único algoritmo de aprovação** (`AprovarEdicaoRotaLaboratorio`). Não faz sentido criar Base abstrata para 1 implementação. **Recomendação:** manter como está. Caso surjam fluxos similares (ex.: `EdicaoColeta`), considerar extrair Base. ### b) ISP (interfaces segregadas) Designacoes segrega `DesignacaoStrategyInterface` (umbrella) + `PainelStrategyInterface` + `HierarchyCapableInterface` + `AvulsoCapableInterface`. Strategies que não usam hierarquia não implementam métodos vazios. EdicaoRota tem 1 interface (`EdicaoRotaCallbackInterface` com 2 métodos). Não há o que segregar. **Recomendação:** deixar como está. ### c) Strategy Factory tipada Designacoes: `DesignacaoStrategyFactory::create(TipoMissao::SEPARACAO)` → `SeparacaoStrategy`. Tipado por enum, fallback legado. EdicaoRota: `EdicaoRotaCallbackRegistry::resolver('romaneio_veiculo')` → `RomaneioVeiculoEdicaoRotaCallback`. Resolução por string, registrada em runtime. **Trade-off:** - Factory por enum é mais type-safe. - Registry por string permite que módulos externos se registrem sem alterar o core (extensão sem modificação). Para EdicaoRota a flexibilidade vale mais — Coletas, TMS, etc. podem se registrar sem PR no sinal genérico. **Recomendação:** manter Registry. Se um dia a lista de módulos for fechada (ex.: <5), considerar tipar com enum interno. ### d) Value Objects / `Resolvers/` Designacoes tem `MissionReference` (id + origem). EdicaoRota não tem nada equivalente — `rota_atual` e `rota_proposta` viajam como `array` JSON. **Risco:** se a estrutura de cada parada crescer (titulo, endereço, lat/lng, janela horária), arrays soltos viram bagunça. **Recomendação:** quando a parada tiver >4 campos relevantes, criar `Resolvers/Parada.php` (VO). --- ## 8. Onde EdicaoRota está mais saudável que Designacoes 1. **Tamanho do entry point.** `Designacoes.php` tem 1586 linhas com lógica de domínio embutida (mapeada em `refatorar.md`, ~500 linhas a mover). `App.php` tem ~180 linhas, dispatcher puro. Estamos no estado que Designacoes quer chegar. 2. **Sondas (V2) puras.** Sem nenhuma Inteligencia legada V1. 3. **`Adapters/Romaneio/` isola tudo do domínio Romaneio** num único subdiretório. Designacoes importa Romaneio em vários Laboratorios diretamente. 4. **Migrations versionadas (`001_*.sql`)**. Designacoes usa `db/tabelas.sql` sem versionamento. 5. **Constelacoes não é tocado** (após correção do usuário). Designacoes ainda tem satélite em Constelacoes (`MissoesAprovacao`). --- ## 9. Itens de evolução recomendados (priorizados) | Prioridade | Item | Quando | |---|---|---| | 🟡 Média | Adicionar `Observatorio()` no `App.php` quando o painel do gestor for plugado de fato | Antes do primeiro release com painel | | 🟡 Média | Criar `PENDENCIAS.md` e `ADRs` conforme decisões não-óbvias forem surgindo | Contínuo | | 🟢 Baixa | Considerar VO `Parada` em `Resolvers/` se a estrutura crescer | Quando parada tiver >4 campos relevantes | | 🟢 Baixa | Avaliar Template Method `EdicaoRotaBase` se outro fluxo de edição surgir (ex.: edição de coleta) | Sob demanda | | ⚪ Discussão | Validar se `Adapters//` deve virar convenção do codebase ou ficar pontual | Depois de 2-3 sinais novos | --- ## 10. Veredito final EdicaoRota está **estruturalmente alinhado** com o framework — usa as mesmas pastas, sufixos, namespaces, padrão de testes e separação Constelacoes×Missoes que Designacoes. As diferenças observadas são de **três tipos**: 1. **Diferenças por simplicidade da feature** (sem Template Method, sem ISP, sem Factory tipada). Justificadas — adicionar prematuramente seria over-engineering. 2. **Convenções modernas que Designacoes ainda não adotou** (Sondas V2, Migrations versionadas, Constelacoes só model, dispatcher enxuto). EdicaoRota está **adiante**. 3. **Convenção nova** (`Adapters//`). Em observação — pode virar padrão. Estado: **pronto para servir de modelo para próximos sinais novos**.