# 04 - Módulos

> Inventário de todas as Missões e Sinais do sistema: responsabilidade, geração (V1/V2), tabelas e estado. Use este documento para responder "onde vive a funcionalidade X?" e "isso é código vivo ou morto?".
>
> Relacionados: [02 - Fluxos](02-fluxos-do-sistema.md) (como os módulos logísticos se encadeiam), [05 - Banco](05-banco-de-dados.md) (tabelas), [15 - Glossário](15-glossario.md).

## Legenda de geração

- **V2** — controller dispatcher fino, lógica em `Laboratorios/`, models em `Sondas/`, geralmente com `Migrations/` e `Testes/`. Padrão para código novo.
- **V1** — controller com lógica embutida (muitos gerados pelo designer Galaxia), dados via Constelações. Manter, não imitar.
- **Scaffold** — esqueleto CRUD mínimo (controller + 2 views), sem camada de dados própria.
- **Sandbox** — playground pessoal/experimental. **Morto** — cópia/backup a ignorar.

---

## 1. Logistica — o domínio central (~30 sinais)

O coração do produto. Fluxos completos em [02 - Fluxos](02-fluxos-do-sistema.md).

### Sinais principais

| Sinal | Responsabilidade | Geração | Tabelas / notas |
|---|---|---|---|
| **Central** | Painel TMS de despacho em produção: importar/incluir pedidos, montar rotas de carregamento → romaneios → veículos, roteirizar (mapa), aprovar portaria, cubagem, dias efetivos, curadoria de alertas TMS, webhooks de veículos/separadores | V1 (controller ~1.400 linhas) | `rotas_carregamento`, `romaneios*`, `tecnosoft_enderecos_entregas`, `niveis_markup`; front `maps.js`; rooms socket `galaxia_logistica_central/_board`; alimentado por `crompedidos_logistica.php` |
| **Central2** | Reescrita V2 do painel, **dev-only** (gate `ApiConfig::isDev`): Adapters para Romaneio/MissaoLogistica/Processo, sandbox de escrita (`SandboxGuard`, tabelas `c2_*`), labs de escrita desligados por padrão (`LABS_ESCRITA_ATIVOS`), rooms socket próprias | V2 (em desenvolvimento) | Sondas próprias sobre `pedidos`, `romaneios*`, `missao_logistica`; **nunca escreve em tabela V1**; ver `Central2/README.md` |
| **Designacoes** | Painel do gestor para **criar missões** (separação, carregamento, pesagem, ajuste, inventário, alocação WMS, retorno). Template Method (`GestaoMissoesBase` + 7 filhas), Strategy+Factory por tipo, Resolvers/VOs | V1 maduro (baseline; controller 1.599 linhas com débito mapeado em `refatorar.md`) | `missao_logistica*`; débito em `PENDENCIAS.md` |
| **App** | App mobile do operador: dispatcher por handler (Separacao, Pesagem, Carregamento, AjusteDados, Inventario, Retorno, Pedidos, AlocacaoWms), fila SKIP LOCKED, bipagem | V2 (Handlers) | Consome satélites `MissoesExecucao`/`MissoesBipagem`/`MissoesStatus` da Constelação MissaoLogistica |
| **Edicaorota** | Motorista reordena rota (token público + OTP) com aprovação do gestor; callbacks Registry; `Adapters/Romaneio` | **V2 canônico** | `edicoes_rota`; `COMPARACAO_FRAMEWORK.md` |
| **AlocacaoWms** | Missões de operação WMS (endereço-primeiro): alocação, inventários, movimentação — via `OperacaoAdapterFactory` | V2 | `wms_localizacoes`, `wms_movimentos`; `README.md` completo |
| **IntegracaoWms** | Integração com WMS externo: ordens inbound (HMAC), tradutores por tipo, providers de saída plugáveis, ciclo `recebida→traduzida→reportada` | V2 | `wms_ordens`, config `integracao_wms_config`; `README.md` completo |
| **Solicitacoes** | Fila global de aprovações (desvínculo, recomeço, acessos, cancelamento, edição de rota) com Strategy de side-effect por tipo | V2 | `solicitacoes_globais(_historico)` |
| **Lotes** / **GestorLotes** | Staging de entidades antes de virar missão (Facade `GestorLotes`, idempotente, lista imutável) / painel do gestor | V2 | `lotes`, `lotes_entidades`, `lotes_movimentacoes` |
| **Ocorrencias** | Retorno de entregas: triagem, missão de retorno (sempre com aprovação), retorno ao mapa, sync legado | V2 | `ocorrencias(_produtos/_extrato)` |
| **Inventariociclico** | Planos/ciclos de inventário com registries plugáveis (universo, seleção, distribuição, esperado, ajuste) e máquina de divergência | V2 (muito extensível) | `inventario_*`; cron `0-4-inventario_ciclico_diario.php` |
| **SugestoesCodigoBarras** | Operador sinaliza código errado/ausente → missão `AJUSTE_DADOS` via `Adapters/AjusteDados` | V2 | `missao_codigo_sugestao` |
| **Dashboard** | Analytics da operação (KPIs, timelines, rankings, erros, pesagem) — servido por `/api/v1/dashboard/*` | V2 (read-only) | Lê `missao_logistica*` |
| **DashboardApi** | **DEPRECATED (2026-05)** — endpoints migrados para a API; os Laboratórios ainda são consumidos PHP-a-PHP pelo Dashboard novo — **não remover** | V2 deprecated | `DEPRECATED.md` |
| **Missao** | Quase vazio: só Validator transversal de missão (o modelo real está na Constelação) | V2 stub | — |

### Sinais de suporte

| Sinal | Responsabilidade | Estado |
|---|---|---|
| Gps | Rastreio de posições de veículo/motorista (`localizacoes`) | auxiliar |
| Lacres | Controle de lacres de carga (5 sondas: movimentação, auditoria, config) | operacional isolado |
| Mapas | Camada de mapa/markers | suporte ao Central |
| Regioesagrupamentos | Agrupamento geográfico para roteirização (`regioes_administrativas*`) | ativo |
| Armazem | Layout/gôndolas + log de separação (`romaneios_produtos_separacao*`) | ativo |
| **Armazem copy** | cópia | **morto** |
| Board | Quadro Kanban da operação (room `galaxia_logistica_board`) | ativo |
| Admin | Configs dev-gated (allowlist `DEV_USER_IDS`; ex.: scan_cota) | ferramenta interna |
| AppTeste | Sandbox de UI | sandbox |
| Shared | Assets compartilhados (`bipagem_offline.js`, componentes de equipe) | infra |
| Processos / ProcessosPedidos / ProcessosVeiculos | Orquestração legada de sequências de movimentação | legado raso |

### Constelação Logistica/MissaoLogistica (modelo compartilhado)

Inteligências V1 do núcleo: `MissaoLogistica`, `MissaoLogisticaItem`, `MissaoLogisticaUsuario`, `MissaoLogisticaExtrato`, `TipoMissaoLogistica` (+ Notificacao, Solicitacao). Satélites críticos: `MissoesExecucao` (fila SKIP LOCKED), `MissoesBipagem` (fator por código), `MissoesStatus` (máquina de estados + hooks), `MissoesLogisticas` (persistência). Sondas V2: `PedidoErpSonda` (ERP MySQL), `ProdutoCodigoBarraSonda`, `ScanCotaConfigSonda`. Enums: `TipoMissao` (13 tipos, ids fixos não sequenciais), `StatusMissao`, `StatusItem`.

---

## 2. Plataforma

| Sinal | Responsabilidade | Geração |
|---|---|---|
| **Api** | API REST `/api/v1` + webhooks inbound — capítulo próprio: [06 - APIs](06-apis.md) | V2 |
| **Regras** | Motor de regras/limites por cliente (registry de situações) | V2 (`regras`) |

## 3. Mensageria e Integrações

| Missão/Sinal | Responsabilidade | Geração | Tabelas |
|---|---|---|---|
| Mensageria/**Otp** | OTP multicanal (registry de canais) — **referência canônica V2** | V2 | `verificacoes_otp(_eventos)` |
| Mensageria/Central | Barramento genérico de mensageria (conectores, fábrica, webhook) | V2 (sem controller topo) | repositórios canal/empresa |
| Integracoes/Docuseal | Assinatura eletrônica (embed JWT) | V1 | `docuseal_*` |
| Integracoes/Dropbox | Stub (só tela de setup) | V1 stub | — |
| Integracoes/Gmail | OAuth2 Google para envio de e-mail | V1 | `Emails.client_auth` |

## 4. Galaxia — o admin do próprio framework

A Missão `Galaxia` é a IDE interna com que se constroem as demais: **Central** (hub do editor), **Codigo** (editor de PHP), **Design** (editor visual), **Diagramas** (editor de rotas; `DiagramasV1` legado; `Diagramas copy` **morto**), **Rotas** (gestão de `gx_rotas`), **Categorias**, **Planetas**, **Solar**, **Vias**, **Visoes**, **Niveisacesso** (perfis × páginas), **Operadores** (usuários), **Linguagens** (editor de i18n), **Workflows**, **Funcoes**, **Luz** (mecânica de reatividade), **GerenciadorDeArquivos**, **Tutorial**, **Marcos** (playground), **V2** (placeholder vazio). Todos V1-core sobre a Constelação `GalaxiaEstrutural`.

## 5. Cadastros e comercial

| Missão | Sinais | Geração | Notas |
|---|---|---|---|
| Pessoas | Gerenciar (V2), Categorias (V2), Dashboard (V1) | misto | cadastro central PF/PJ (`pessoas*`) |
| Clientes | ClientesListagem, Camposextras, Documentos, Recorrencia | V1 | Constelação `Clientes` rica |
| ModuloDePessoaFisicaOuJuridica | index | V1 rico | componente reutilizável de cadastro PF/PJ |
| Perfil | Cliente | V1 | portal do cliente final |
| Pedidos | PedidosListagem (V1), PedidosFinalizado (**V2**), Info, Processos, Logistica, Gorduras; `estrutura copy.php` **morto** | misto | `pedidos*` |
| Produtos | ProdutosGerenciar, Grupos, SelecaoRapida, Sincronizacoes (com Labs) | V1 | `produtos*` |
| Produtoscategorias / Produtosmarcas / Produtosunidades / Tabelasvenda | Gerenciar | V1 | CRUDs simples |
| Vendedores | VendedoresListagem, Gordurascaixas | V1 | `vendedores*`; metas/comissões via Constelação `Metas` ([03 §R34](03-regras-de-negocio.md)) |
| Vendedor | Dashboard | V1 | painel individual |
| Fornecedores / Motoristas / Setores / Recibos / Notascompra / Formaspagamento / Contasbancos | Gerenciar | Scaffold | esqueletos CRUD |
| Servicos | Orcamentos, Etapas, ServicosEtapas, StatusEtapas, Acompanhamento (**V2**), Processos, ControleNoProcesso, NoStatus, Forms/Formularios (redundância aparente), Notificacoes, Templatesdocs, ConnectionAccounting | misto | `servicos*`, `orcamentos_servicos*` |
| OsProcessos | Listagem | V2 | `os_processos*` |
| ConnectionAccounting | Condicoes, Formularios | V1 | integração contábil externa |

## 6. Financeiro e fiscal

| Missão/Sinal | Responsabilidade | Geração |
|---|---|---|
| Financeiro (Contasapagar, ContasareceberGerenciar, Categorias, Precategorias, Opcoesadicionais) | contas a pagar/receber | V1 |
| Cobrancas/Boletos | motor de boletos (CRUD interno — **sem** integração bancária, [08 §9](08-integracoes.md#9-boletos--bancos)) | V2 sem controller topo |
| Boletos/BoletosPainel | painel de boletos | V1 |
| Fiscal/Nfes | NF-e (stack `sped-*`) | V2 sem controller topo (`nfe`) |

## 7. Estrutura organizacional e dashboards

| Missão/Sinal | Responsabilidade | Geração |
|---|---|---|
| Empresas/Gerenciar, Filiais/Gerenciar | multi-tenant (empresas/filiais) | V1 |
| Filiais/Armazem (+Armazemapp) | blocos de armazém da filial | **V2** (`armazem_blocos*`) |
| Processos (Gerenciar **V2**, GerenciarB — provável duplicata, Listagem, Dashboard) | motor de processos | misto |
| Producao/Metricas | métricas de produção | V1 rico |
| Dashboards (Show, Controle V1; **Expedicao** e **Expedicaoapresentacao** V2) | dashboards; Expedição é cache-first ([02 §10](02-fluxos-do-sistema.md)) | misto |
| Distribuicaov1 (Base, Clientes, Pedidos, Vendedores) | distribuição **legada** | V1 legado |
| Intinerarios (6 sinais; grafia herdada) | itinerários/roteiros | V1 |

## 8. Workspaces e GBlocos (ferramentas de UI)

- **Workspaces** — boards estilo Monday: Manager, Central, Boards(+Status/+Steps), Nos, Paginas, Rotas, Divs, Forms, VisualFormularios, Luz/Autoload (infra). V1-core. Detalhes de funcionamento em [07 §9](07-front-end.md#9-gblocos-e-workspaces-page-builder-e-boards).
- **GBlocos** — biblioteca de blocos do page builder (Drawflow). Maioria V1-core; exceções V2 com Sondas: Whiteboard (`whiteboard_elementos*`), NotasUsuarios (`notas_usuarios`), Filtros, Apis. O editor visual vive em **Construcao/Gerenciar**.

## 9. Sandboxes, experimentos e produtos à parte

| Missão | O que é | Veredito |
|---|---|---|
| **Guilherme** (28 sinais: Animais, Carros, Casas, Familias...) | Playground pessoal de aprendizado (tabelas `gui_*`) | **Sandbox — não é produto** |
| **Felipe**/Documentos | Experimento de estilo de controller (`__call`, `pouso`) | Sandbox |
| **Goldie**/Importar | Importador do legado Goldie (`goldie_*`) | V2, ativo — ferramenta de migração |
| **Tecnosoft**/Importar | Importador do ERP Tecnosoft (~15 tabelas `tecnosoft_*`) | V2, real — migração de dados |
| **RamifyConsultorios** | App white-label de consultórios/agendamento ("Appointly") | Produto/experimento isolado, estilo próprio |
| **Palavra**/Central | Meta-SaaS: gestão de software houses/apps/licenciamento | V2, ativo |
| **Ideias**/Cruzadas, **Mapasmentais**/Novo | Placeholders (só `start`) | Sandbox |

## 10. Constelações (models compartilhados) — mapa de 1 linha

`Boletos` (legado), `CRM`, `Clientes` (núcleo do cliente), `ContasBancarias`, `DadosTotal` (dashboards agregados), `Dashboards` (motor: gráficos, PowerBI), `Distribuicaov1` (legado), `Empresas`, `Etiquetas`, `Financeiro`, `GalaxiaEstrutural` (metaestrutura do framework: usuários, acessos, rotas, i18n, workflows), `Guilherme` (**sandbox**), `Importacoes`, `Integracoes`, `Logistica` (§1), `Metas`, `Orcamentos`, `OrdensServicos`, `Pedidos`, `Pessoas`, `Processos`, `Produtos`, `Regioes`, `Romaneios`, `SegmentosClientes`, `Servicos`, `TabelasVenda`, `Veiculos` (com `VeiculoSonda` V2 emergindo), `Vendedores`, `Workspaces`, `_bases` (**gabaritos de scaffolding**, não runtime), `home` (tenant goldie).

## 11. Código morto e redundâncias conhecidas

**Mortos (ignorar/remover):** `Galaxia/sinais/Diagramas copy`, `Logistica/sinais/Armazem copy`, `Guilherme/sinais/Filtrosbackup`, `Pedidos/sinais/estrutura copy.php`, `Mensageria/.../ResultadoEnvio copy.php`.

**Redundâncias a esclarecer antes de mexer:** `Processos/GerenciarB` vs `Gerenciar`; `Servicos/Forms` vs `Formularios`; `Servicos/Etapas` vs `ServicosEtapas`; `Galaxia/Diagramas` vs `DiagramasV1`; as três implementações de WhatsApp ([08 §2](08-integracoes.md#2-whatsapp-evolution-api)).

**Grafias herdadas (não corrigir — quebraria rotas):** `Intinerarios`, `DistibuicaoPedidos`, `Contasbancos`.

**Sinais V2 sem controller de topo** (só Sondas+Laboratorios, despachados via API/dadosG): `Cobrancas/Boletos`, `Fiscal/Nfes`, `GBlocos/Apis`, `Mensageria/Central` — o "ponto de entrada" deles é o Handler da API ou outro Sinal.