# Manual Oficial do Sistema Genesis

> **Este é o manual de referência oficial do sistema Genesis (framework Galaxia).**
> Ele foi escrito para transferir o conhecimento completo do sistema — não apenas *o que* o código faz, mas *por que* ele é assim, quais problemas já ocorreram e como evoluí-lo com segurança.
>
> Público-alvo: desenvolvedores (júnior a sênior), analistas de negócio, Product Owners e **assistentes de IA** que usarão este material como fonte primária de conhecimento.

## Como usar este manual

- **Nunca viu o sistema?** Comece por [00 - Introdução](00-introducao.md) e [01 - Arquitetura Geral](01-arquitetura-geral.md).
- **Vai dar manutenção?** Leia [11 - Guia de Manutenção](11-guia-de-manutencao.md) e [12 - Armadilhas Conhecidas](12-armadilhas-conhecidas.md) **antes** de tocar no código.
- **Vai criar algo novo?** Siga o [10 - Guia de Desenvolvimento](10-guia-de-desenvolvimento.md) — ele aponta os padrões e referências canônicas.
- **Precisa entender o negócio?** [02 - Fluxos do Sistema](02-fluxos-do-sistema.md) e [03 - Regras de Negócio](03-regras-de-negocio.md).
- **Termo desconhecido?** [15 - Glossário](15-glossario.md).

## Índice

| # | Documento | Conteúdo |
|---|-----------|----------|
| 00 | [Introdução](00-introducao.md) | Objetivo do sistema, problema que resolve, público, conceitos fundamentais |
| 01 | [Arquitetura Geral](01-arquitetura-geral.md) | Framework Galaxia, camadas, ciclo de request, padrões V1 vs V2 |
| 02 | [Fluxos do Sistema](02-fluxos-do-sistema.md) | Fluxos ponta-a-ponta (logística, pedidos, missões, OTP...) com diagramas |
| 03 | [Regras de Negócio](03-regras-de-negocio.md) | Regras implícitas extraídas do código, com o porquê de cada uma |
| 04 | [Módulos](04-modulos.md) | Inventário de todas as Missões/Sinais: responsabilidade, geração, status |
| 05 | [Banco de Dados](05-banco-de-dados.md) | Conexão, convenções, multi-tenant, tabelas-chave, migrations |
| 06 | [APIs](06-apis.md) | API REST `/api/v1`: arquitetura, auth JWT, inventário de endpoints |
| 07 | [Front-end](07-front-end.md) | Templates, views+JS pareado, Luz, GBlocos, modais, i18n |
| 08 | [Integrações](08-integracoes.md) | ERP legado, WMS, TMS, WhatsApp/OTP, Google, Docuseal, crons |
| 09 | [Configurações](09-configuracoes.md) | Ambientes, credenciais, flags de dev, dependências |
| 10 | [Guia de Desenvolvimento](10-guia-de-desenvolvimento.md) | Como criar Sinal, endpoint, Sonda, migration, tela, integração |
| 11 | [Guia de Manutenção](11-guia-de-manutencao.md) | Onde procurar problemas, como depurar, como testar |
| 12 | [Armadilhas Conhecidas](12-armadilhas-conhecidas.md) | Gotchas reais que já causaram bugs: sintoma, causa, solução |
| 13 | [Dívidas Técnicas](13-dividas-tecnicas.md) | Dívidas classificadas por severidade e impacto |
| 14 | [Melhorias Futuras](14-melhorias-futuras.md) | Roadmap técnico sugerido, priorizado |
| 15 | [Glossário](15-glossario.md) | Todos os termos do projeto (Missão, Sinal, Sonda, Luz...) |

## Convenções deste manual

- **Caminhos** são relativos à raiz do repositório (`/home/goldie/www/genesis`).
- Referências de código no formato `arquivo.php:linha` apontam para a linha na data de escrita (julho/2026); a linha pode derivar, o arquivo raramente.
- Termos do framework (Missão, Sinal, Sonda...) são usados com inicial maiúscula e estão todos no [Glossário](15-glossario.md).
- **Fonte única da verdade**: cada assunto é explicado em profundidade em um único documento; os demais apenas o referenciam.

## Documentação complementar (pré-existente)

- `documentacoes/` — guias operacionais do framework Galaxia escritos durante o desenvolvimento (snippets, padrões de formulário/modal). O manual consolida e supersede o conteúdo conceitual; os snippets continuam válidos.
- `componentes/Missoes/Logistica/sinais/Edicaorota/COMPARACAO_FRAMEWORK.md` — formalização dos padrões V2 vs legado.
- `PRD/` — especificações por feature (processo PO → Tech Lead → Dev → Tester → Reviewer).
- `docs/` — planos de implementação históricos (superpowers/plans) e docs de i18n/websocket.