# 00 - Introdução > Ponto de partida do manual. Explica o que é o Genesis, que problema resolve, para quem foi feito e os conceitos que você precisa dominar antes de ler qualquer outra coisa. > > Próximo passo de leitura: [01 - Arquitetura Geral](01-arquitetura-geral.md). ## 1. O que é o Genesis O **Genesis** é uma plataforma de gestão empresarial (ERP) multi-tenant, com profundidade especial em **logística de distribuição**: pedidos, romaneios, rotas de entrega, separação e carregamento em armazém (WMS), missões de operadores, dashboards operacionais e integrações com sistemas externos (ERP legado, TMS, WMS de terceiros, WhatsApp). Ele é construído sobre o **Galaxia**, um framework PHP proprietário desenvolvido pela própria equipe, que fornece: roteamento, autenticação JWT, multi-tenant automático em todas as queries, sistema de views com componentes dinâmicos ("Luz"), formulários gerados por backend e uma API interna entre módulos (`dadosG`). Historicamente, o Genesis é o **sucessor do "sistema antigo"** (pasta `antigo/`, MySQL), que ainda opera em paralelo. Boa parte das regras de negócio e integrações existe para permitir essa convivência durante a migração gradual. ## 2. O problema que o sistema resolve Uma distribuidora precisa, todos os dias: 1. Receber e consolidar **pedidos** (parte deles vinda do ERP legado). 2. Agrupar pedidos em **romaneios** (cargas) e definir **rotas** de entrega por veículo. 3. Orquestrar o trabalho do armazém: **separação** (picking), **conferência/bipagem** por código de barras, **pesagem** e **carregamento** — cada etapa como uma **missão** atribuída a operadores. 4. Acompanhar a expedição em tempo real (dashboards, central de acompanhamento) e tratar exceções: **ocorrências** de entrega, **retornos** de mercadoria, ajustes de rota solicitados pelo **motorista** com aprovação do gestor. 5. Controlar estoque por endereço de armazém (**WMS**) — internamente ou integrado a um WMS externo. 6. Manter tudo sincronizado com sistemas satélites (ERP legado, TMS, mensageria WhatsApp). O Genesis cobre esse ciclo ponta a ponta, além dos módulos administrativos clássicos de ERP (clientes, produtos, financeiro, fiscal/NF-e, vendedores, metas e comissões). ## 3. Público-alvo deste manual | Perfil | O que ler primeiro | |---|---| | Dev júnior | [00](00-introducao.md) → [01](01-arquitetura-geral.md) → [15 - Glossário](15-glossario.md) → [10 - Guia de Desenvolvimento](10-guia-de-desenvolvimento.md) | | Dev pleno (manutenção) | [11 - Guia de Manutenção](11-guia-de-manutencao.md) → [12 - Armadilhas](12-armadilhas-conhecidas.md) → [04 - Módulos](04-modulos.md) | | Dev sênior (evolução) | [01](01-arquitetura-geral.md) → [13 - Dívidas Técnicas](13-dividas-tecnicas.md) → [14 - Melhorias Futuras](14-melhorias-futuras.md) | | Analista de negócio / PO | [02 - Fluxos](02-fluxos-do-sistema.md) → [03 - Regras de Negócio](03-regras-de-negocio.md) | | Assistente de IA | Este manual inteiro é a fonte primária; comece pelo [README](README.md) e respeite as referências cruzadas. | ## 4. Os 7 conceitos que você precisa saber antes de tudo 1. **A metáfora astronômica.** O framework chama domínio de **Missão** (ou Constelação), módulo de **Sinal** (ou Estrela), sub-rota de **Lua**, ação de negócio de **Laboratório** e model de **Sonda**. A URL `/missao/Logistica/Edicaorota` significa "Sinal Edicaorota da Missão Logistica". Tabela completa no [Glossário](15-glossario.md). 2. **Multi-tenant é automático e invisível.** Toda query de Sonda é filtrada por cliente (`block`), empresa (`block_empresa_id`) e, conforme o caso, usuário/setor — o framework injeta isso sozinho a partir da sessão. Você raramente escreve o filtro; em compensação, precisa criar as colunas certas em toda tabela nova e entender os fallbacks ([01 §7](01-arquitetura-geral.md#7-multi-tenant-o-mecanismo-mais-importante-do-sistema)). 3. **Excluir não exclui.** `delete()` faz soft delete (`block = 0`). Dados "apagados" continuam na tabela. 4. **Existem duas gerações de código.** V1 (Inteligências, lógica no controller) é legado congelado; V2 (Sondas, dispatcher fino, Validators, Registry/Adapters) é o padrão para tudo que é novo. As referências canônicas V2 são `Mensageria/Otp` e `Logistica/Edicaorota` ([01 §9](01-arquitetura-geral.md#9-as-duas-gerações-v1-vs-v2)). 5. **O frontend não fala com o backend por conta própria.** Formulários, botões de ação e modais são **gerados pelo backend** (`visualFormulario`, `acaoElemento`, `abrirModal`); o JS do framework interpreta os atributos `data-*` e faz as requests. A exceção controlada é a API REST `/api/v1` para dashboards e fluxos sem sessão ([06 - APIs](06-apis.md)). 6. **Ambiente é decidido pelo hostname.** Prefixo `dev-` no subdomínio = desenvolvimento (banco `dev_gx_goldie`); sem prefixo = produção. Não há `.env` ([09 - Configurações](09-configuracoes.md)). 7. **i18n é por texto, não por chave.** `show("Salvar rota")` — a chave é o md5 do texto em português. Três idiomas: pt-br, en, es ([07 - Front-end](07-front-end.md)). ## 5. Números do sistema (julho/2026) - ~48 Missões, centenas de Sinais; a Missão **Logistica** concentra ~30 Sinais e é o coração do produto. - PHP 8.3 + PostgreSQL (produção `gx_goldie`/`gnesis`) + MySQL legado (`goldie_atual`). - ~250 arquivos de teste (scripts PHP standalone, sem PHPUnit). - API REST interna com ~70 endpoints (health, edição de rota, OTP, ~45 de dashboard, regras, veículos, webhook inbound). - Desenvolvimento via pipeline de agentes de IA com gates humanos (`PRD//00-prd.md` → `06-review.md`). ## 6. Como este manual foi construído e como mantê-lo Este manual foi escrito a partir da leitura sistemática do código (framework core, API, domínio logístico, banco, frontend, integrações e configuração) somada ao conhecimento acumulado de desenvolvimento — incluindo bugs históricos e decisões de design que não estão escritas em nenhum outro lugar. **Regras de manutenção:** - Cada assunto tem **um** documento dono; os demais linkam. Não duplique explicações. - Ao corrigir um bug causado por comportamento não-óbvio, adicione a armadilha em [12](12-armadilhas-conhecidas.md). - Ao tomar uma decisão arquitetural nova, registre o **porquê** em [01](01-arquitetura-geral.md) ou no documento do módulo. - Referências `arquivo:linha` derivam com o tempo; prefira nomes de classe/método quando a precisão de linha não for essencial.