# 15 - Glossário

> Todos os termos usados no sistema Genesis e neste manual. O framework usa uma metáfora astronômica consistente — memorize esta tabela antes de ler código.

## Termos do framework Galaxia

| Termo | Sinônimo interno | O que é |
|---|---|---|
| **Galaxia** | — | O framework PHP proprietário sobre o qual o Genesis é construído. Vive em `controladores/_Controladores/` e `system/`. |
| **Genesis** | goldie_app | O produto: ERP/plataforma de gestão (com foco forte em logística) construído sobre o Galaxia. |
| **Missão** | Constelação | Domínio funcional de topo. Uma pasta em `componentes/Missoes/<Nome>/`. Ex.: `Logistica`, `Pedidos`, `Mensageria`. Na URL aparece como o primeiro segmento após `/missao/`. |
| **Constelação** | Missão | Dois usos: (1) sinônimo de Missão nas URLs e no `setConstelacao()`; (2) a pasta `componentes/Constelacoes/<Modulo>/`, que guarda **apenas models compartilhados** (Sondas/Inteligências) entre Sinais. Views e HTML **nunca** ficam em Constelacoes. |
| **Sinal** | Estrela | Módulo/feature dentro de uma Missão. Pasta `Missoes/<M>/sinais/<Sinal>/`. Contém controller, Laboratórios, Sondas, views. O controller principal tem o mesmo nome do diretório (`Edicaorota/Edicaorota.php`), nunca `App.php`. |
| **Lua** | Satélite (roteamento) | Sub-rota de um Sinal. Chega ao controller via `$data['sinalGxData']` (3º segmento da URL `/missao/<Constelacao>/<Sinal>/<Lua>`). |
| **Satélite** | — | Dois usos: (1) sub-controller de um Sinal em `<Sinal>/Satelites/`; (2) o alvo do `setSatelite()` na chamada fluente do GalaxiaRoute — geralmente o nome do Laboratório. |
| **Laboratório** | Action / Use case | Classe em `<Sinal>/Laboratorios/` que executa uma ação de negócio. Recebe `$opcao` (`criacao`, `leitura`, `edicao`, `deletar`...) no construtor e roteia num `switch`. Laboratórios se comunicam entre si **apenas** via `dadosG()`, nunca `new Lab()`. |
| **Sonda** | Model V2 | Model de banco da geração atual, estende `ModelInteligencia`. Vive em `<Sinal>/Sondas/` (local) ou `Constelacoes/<Modulo>/` (compartilhada). Todo código novo usa Sondas. |
| **Inteligência** | Model V1 | Model da geração antiga (**deprecated**). Só leitura/manutenção; nunca criar código novo estendendo o padrão V1. |
| **Validator** | — | Classe em `<Sinal>/Validators/` que valida o input de um Laboratório antes da execução. Padrão V2: sem validação inline no Laboratório. |
| **Luz** | Componente dinâmico | Sistema de atualização parcial de UI. O controller expõe métodos `Luz_<Nome>()` que renderizam um fragmento; o backend manda re-renderizar via `reencaminheLuz()`. Em loops, cada instância precisa de `luzId` único. |
| **Observatório** | Interceptor | Método `Observatorio()` (e `GalaxiaAutoLoad()`) do controller que intercepta requisições de API antes (`before = 1`) e depois (`after`) da execução do Laboratório. Usado para validar e para atualizar a UI (fechar modal, recarregar Luz). |
| **GalaxiaRoute** | `$galaxia` / `$this->galaxiaRoute` | O objeto central do framework: dispatcher de rotas e API fluente (`setConstelacao()->setEstrela()->setSatelite()->setOpcao()`) para renderizar views (`visual`), formulários (`visualFormulario`), botões de ação (`acaoElemento`), modais (`abrirModal`) e chamadas internas (`dadosG`). |
| **dadosG** | Chamada interna | Forma canônica de um Laboratório consumir outro (mesmo de outro Sinal): monta a rota fluente e chama `dadosG($filtros)`. É a "API interna" entre módulos. |
| **GalaxiaResposta** | — | Builder de respostas padronizadas para o frontend: `fecharModal()`, `substituirConteudo()`, `chamarFuncao()`, `atualizarPagina()`, `feito()`. |
| **Adapter** | `Adapters/<Dominio>/` | Pasta dentro de um Sinal que isola toda a integração com um domínio externo (callback + use case + migration + testes daquele domínio). O core do Sinal não conhece o domínio externo. Exemplo canônico: `Logistica/sinais/Edicaorota/Adapters/Romaneio/`. |
| **Registry** | — | Padrão de extensibilidade V2: quem quer estender um Sinal chama `registrar(nome, classe)` num registry (`OtpCanalRegistry`, `EdicaoRotaCallbackRegistry`) e é resolvido por string em runtime — extensão sem PR no Sinal. |
| **V1 / V2** | — | Gerações de arquitetura. V1 = Inteligências, lógica no controller, padrões legados (Designacoes, Pessoas/Gerenciar). V2 = Sondas, controller-dispatcher fino, Validators, Enums, Migrations versionadas, Testes espelhados. Referências canônicas V2: `Mensageria/sinais/Otp` e `Logistica/sinais/Edicaorota`. |
| **show()** | i18n | Função de tradução. Recebe o **texto em português literal** (`show("Salvar rota")`); a chave real é o **md5 desse texto**. Nunca usar chave legível. Strings são colhidas automaticamente (auto-harvest) para `linguagens/{pt-br,en,es}.json`. |
| **GBlocos** | — | Missão que funciona como biblioteca de componentes de UI reutilizáveis (Tabela, Modal, Formulário, Nav, Botão, Whiteboard...). |
| **Workspaces** | — | Missão que implementa o sistema de boards/páginas dinâmicas (estilo Monday/Notion interno). |

## Termos de negócio (domínio logístico)

| Termo | O que é |
|---|---|
| **Romaneio** | Documento de carga: agrupa pedidos que sairão juntos num veículo/rota. Entidade central da expedição. |
| **Rota** | Sequência ordenada de entregas de um romaneio/veículo. Editada no Sinal `Edicaorota`. |
| **Missão Logística** | Unidade de trabalho de um operador de armazém (separação, carregamento, retorno...). Uma missão tem **itens**; vários operadores podem trabalhar na mesma missão simultaneamente (intencional — a exclusão mútua é por **item**, via `SELECT ... FOR UPDATE SKIP LOCKED`). |
| **Separação** | Etapa em que o operador coleta os produtos do pedido no armazém (picking). |
| **Carregamento** | Etapa em que os produtos separados são conferidos e colocados no veículo. |
| **Bipagem** | Leitura de código de barras para validar item. O **fator** (quantas unidades um bip representa) é definido **por código de barras** na tabela `produtos_codigos_barras`. |
| **Retorno** | Fluxo de volta da mercadoria não entregue. **Não** valida código de barras na bipagem. |
| **Ocorrência** | Registro de problema numa entrega (recusa, ausência, avaria...). |
| **WMS** | Warehouse Management System. Existe o WMS interno (endereçamento em `AlocacaoWms`, `SugestoesCodigoBarras`) e a integração com WMS **externo** (`IntegracaoWms`). Quando integrado, o WMS externo é o dono do saldo por endereço. |
| **Endereço (WMS)** | Posição física no armazém. O fluxo de alocação é "endereço-primeiro": o operador escolhe o endereço e então informa os itens. |
| **TMS** | Transportation Management System (sistema externo de transporte) — Genesis sincroniza produtos/pedidos com ele. |
| **ERP legado** | Sistema anterior ainda em operação. Cruzamento de dados: `importacao_id` no Genesis = `codigomd5` no ERP. Timestamps do ERP são gravados em **UTC**. |
| **OTP** | One-Time Password — código de verificação enviado por canal de mensageria (WhatsApp etc.) pelo Sinal `Mensageria/Otp`. |
| **Lote** | Agrupamento de pedidos para processamento logístico em massa (Sinais `Lotes`/`GestorLotes`). |
| **Designação** | Atribuição de trabalho a um operador (Sinal legado `Logistica/Designacoes` — não imitar). |
| **Comodato** | Bem emprestado ao cliente (ex.: vasilhame). No ERP legado a coluna `pedidos.comodato` é NULL em quase todos os registros — filtros devem usar `COALESCE`. |
| **Meta / Bônus V2** | Sistema de metas de vendedores. O bônus V2 fica em `bonificacao_config.por_alvo` (JSON), não no campo flat `bonificacao_valor`. |

## Termos de infraestrutura

| Termo | O que é |
|---|---|
| **`dev_gx_goldie`** | Banco de desenvolvimento. Testes de integração **só** rodam nele. |
| **`customerControl` / `companyControl`** | Mecanismo multi-tenant do framework: filtra automaticamente as queries da Sonda por cliente/empresa da sessão. |
| **Colunas `block_*`** | Colunas obrigatórias em toda tabela nova (controle de bloqueio por tenant). A migration **não** define `DEFAULT 1`; o framework injeta os valores via customerControl/companyControl. |
| **`Config::DEV_USER_IDS`** | Allowlist de IDs de desenvolvedores que libera rotas de dev (`/docs`, `/openapi.json` da API). |
| **`dev_team`** | Branch de trabalho permanente. **Não existe merge para `main`** neste fluxo. |
| **PRD/** | Pasta com especificações por feature seguindo o pipeline de agentes: `00-prd.md` → `01-spec.md` (PO) → `02-techplan.md` (Tech Lead) → `03-backend.md` → `04-frontend.md` → `05-testes.md`. |
| **Tema genezes** | Tema/layout atual do dashboard (root `#genezes_app_root`); substitui o tema goldie em telas novas. |