Arquitetura
Como o termo_core é gerado dos contratos OpenAPI e como esta documentação acompanha o código.
TermoCore/
├── openapi/ cópia versionada dos contratos (<serviço>.json e webhook_eventos.json)
├── gerador/ binário Rust que baixa os contratos do SANDBOX e gera os dois pacotes
├── packages/
│ ├── rust/ crate termo_core (crates.io)
│ └── typescript/ pacote termo_core (npm)
└── docs/ esta documentação (Fumadocs)Do contrato à função
Sincronizar
cargo run -p gerador -- sincronizar baixa o openapi.json de cada serviço e o catálogo de eventos (GET /esquemas.json do TermoWebhook), sempre do SANDBOX, para openapi/. O TermoCore nunca acessa o banco de outro serviço.
Gerar
cargo run -p gerador -- gerar lê os contratos uma vez (leitura_do_openapi.rs) e escreve rotas e tipos de cada serviço em Rust e em TypeScript, com os mesmos nomes.
Publicar
O workflow publicar-termo-core.yml publica no crates.io e no npm quando o código de cada pacote muda, subindo só o último número da versão.
Documentar
bun scripts/gerar_paginas_dos_sdks.ts (roda sozinho antes do dev e do build desta documentação) lê o código já gerado em packages/ e os contratos em openapi/ e escreve uma página por entidade em content/docs/servicos/ e o catálogo de eventos. A documentação nunca fica atrás do pacote.
O que é gerado e o que é feito à mão
| Parte | Origem |
|---|---|
<serviço>/rotas e <serviço>/tipos (Rust e TypeScript) | gerado do openapi.json |
webhook/eventos (contratos) | gerado do webhook_eventos.json |
base/ (ambiente, credencial, erro, requisição, token do aplicativo) | feito à mão |
webhook/ publicar, receber, fila, assinatura (só Rust) | feito à mão |
docs/content/docs/servicos/ e eventos/catalogo/ | gerado pelo script da documentação |
| demais páginas desta documentação | feitas à mão |