# TermoCore
Todos os clientes da Termotubos num **pacote só**, o `termo_core`, em Rust (crates.io, em [`packages/rust`](packages/rust)) e em TypeScript (npm, em [`packages/typescript`](packages/typescript), para frontend e backend). Cada serviço é um módulo (`termo_core::bucket`, `termo_core::auth`...) e **cada rota da API do serviço é uma função de uma linha**, gerada a partir do `openapi.json` dele, com o mesmo nome nas duas linguagens. O uso em TypeScript está no [README do pacote npm](packages/typescript/README.md).
```toml
termo_core = "=0.1.5" # todos os serviços
termo_core = { version = "=0.1.5", features = ["segredo_de_app"] } # + busca automática do segredo do app
```
Fixe sempre a versão exata (`=`). O workflow publica cada mudança de contrato do sandbox subindo só o último número, inclusive quando a mudança quebra código. Para atualizar, troque a versão de propósito e confira se compila.
```rust
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_usuario_logado(token_do_usuario);
let usuario = termo_core::auth::buscar_pelo_id_usuario(&credencial_de_acesso, id).await?;
let pagina = termo_core::auth::buscar_paginador_usuario(
&credencial_de_acesso,
&termo_core::auth::ParametrosDeBuscarPaginadorUsuario { pagina: Some(1), ..Default::default() },
)
.await?;
```
### Token do aplicativo (conversa entre back-ends)
```rust
let credencial_de_acesso = termo_core::CredencialDeAcesso::token_do_aplicativo().await?;
let resposta = termo_core::bucket::/* rota de sistema */(&credencial_de_acesso, /* ... */).await?;
```
`token_do_aplicativo()` troca o `SEGREDO_DO_APP_GERADO_NO_TERMO_AUTH` por um JWT curto em `POST {TermoAuth}/token_de_app` (`{ "segredo" }` → `{ token, expira_em, app }`). O token fica em cache no processo e só é pedido de novo quando falta menos de 60 s para `expira_em`; não há tarefa em background. Sem a variável, devolve `ErroAoChamarServico::FalhaAoMontarRequisicao` dizendo para defini-la. Token de aplicativo só vale nas APIs de sistema (gateway do TermoAI, API de arquivos do TermoBucket, publicação no TermoWebhook); as rotas de painel continuam só para pessoas.
O nome da função é a ação seguida do recurso (`operationId` `usuarioBuscarPeloId` com a tag `usuario` vira `buscar_pelo_id_usuario`). Rotas públicas não pedem credencial. Todo erro vem como `ErroAoChamarServico`, com o status e o campo `erro` da resposta.
## Configuração: a variável `AMBIENTE`
| `AMBIENTE` | Para onde cada serviço aponta |
| ------------ | ------------------------------------------------------------------------------ |
| `LOCALHOST` | o servidor local (`http://localhost:51xx1`) ou o sandbox, escolhido por serviço |
| `SANDBOX` | `https://sandbox-api-<serviço>.termotubos.com.br` |
| `PRODUCTION` | `https://api-<serviço>.termotubos.com.br` |
A tabela fica em [`packages/rust/base/servicos.rs`](packages/rust/base/servicos.rs) (o gerador copia para `packages/typescript/base/servicos.ts`). No LOCALHOST, o TermoAI usa o endereço do sandbox (`EnderecoNoLocalhost::MesmoEnderecoDoSandbox`), então não é preciso levantar a IA na máquina. Sem `AMBIENTE` ou com um valor inválido, o processo para com uma mensagem clara: nunca cai em PRODUCTION por engano.
A única outra variável lida é `SEGREDO_DO_APP_GERADO_NO_TERMO_AUTH`, o segredo do app gerado no TermoAuth (`PATCH /app/{id}` com `gerar_segredo: true`), guardado no secret do GitHub Actions e gravado no `.env` pelo deploy. Ela só é exigida por quem fala como aplicativo (veja abaixo).
Para apontar um serviço para outro endereço só num processo (ex.: teste): `termo_core::substituir_endereco_do_servico_neste_processo(&termo_core::servicos::TERMO_AUTH, "http://...")`.
Toda requisição tem tempo limite de 30 s. Para um serviço que demora mais (ex.: gerar imagem no gateway do TermoAI), o processo troca o limite ao subir: `termo_core::definir_tempo_limite_do_servico_neste_processo(&termo_core::servicos::TERMO_AI, Duration::from_secs(300))`. No TypeScript, cada chamada já aceita `tempo_limite_em_milissegundos`.
## Serviços
| Módulo | Serviço |
| ---------- | ---------------- |
| `termo_core::agenda` | TermoAgenda |
| `termo_core::ai` | TermoAI |
| `termo_core::auth` | TermoAuth |
| `termo_core::bucket` | TermoBucket |
| `termo_core::flow` | TermoFlow |
| `termo_core::intranet` | TermoIntranetAPI |
| `termo_core::leads` | TermoLeads |
| `termo_core::mcp` | TermoMCP |
| `termo_core::meet` | TermoMeet |
| `termo_core::miro` | TermoBoard |
| `termo_core::portal` | TermoPortal |
| `termo_core::quality` | TermoQuality |
| `termo_core::status` | TermoStatus |
| `termo_core::studio` | TermoStudio |
| `termo_core::support` | TermoSupport |
| `termo_core::talk` | TermoTalk |
| `termo_core::tracing` | TermoTracing |
| `termo_core::webhook` | TermoWebhook |
| `termo_core::wms` | TermoWMS |
Cada módulo também é uma feature, todas ligadas por padrão (`todos_os_servicos`). Quem quiser compilar menos usa `default-features = false, features = ["auth", "bucket"]`. O webhook tem ainda `webhook_publicar` e `webhook_receber` (veja abaixo), e `segredo_de_app` liga a busca automática do segredo do app no TermoAuth.
## Eventos do TermoWebhook
Os contratos dos eventos são gerados dos esquemas cadastrados no hub, lidos de `GET /esquemas.json` do TermoWebhook (o TermoCore não acessa o banco de nenhum serviço). Cada aplicativo dono vira um módulo:
```rust
use termo_core::webhook::eventos::termo_auth::ColaboradorCriadoV1;
// A partir da fila do próprio app, gravada junto com a mudança (feature webhook_publicar):
let configuracao = termo_core::webhook::ConfiguracaoDoHub::carregar_do_ambiente_atual();
termo_core::webhook::publicar_evento_no_hub_agora(&configuracao, &envelope).await?;
// Na rota que recebe as entregas (feature webhook_receber):
let evento = termo_core::webhook::receber_evento_conferido_do_hub::<ColaboradorCriadoV1>(&cabecalhos, &corpo).await?;
```
O endereço do hub vem do `AMBIENTE`. A publicação manda `Authorization: Bearer <token do aplicativo>` (`token_do_aplicativo()`), então quem publica só informa `SEGREDO_DO_APP_GERADO_NO_TERMO_AUTH`; o hub reconhece o app pelo `sub` do token. Sem a variável, `ConfiguracaoDoHub::carregar_do_ambiente_atual()` devolve `None` e os eventos só são impressos no terminal. Quem recebe entregas não informa nada a mais: o destino assinado pelo hub é o id do app no TermoAuth (`app` do token de aplicativo, `identificador_do_aplicativo()`), o mesmo id do aplicativo no hub. Sem o segredo do app, a entrega responde `503` e o hub reenvia.
## Como o código é gerado
```bash
cargo run -p gerador # sincronizar + gerar
cargo run -p gerador -- sincronizar # baixa o openapi.json de cada serviço e o /esquemas.json do TermoWebhook (do SANDBOX) para openapi/
cargo run -p gerador -- gerar # gera packages/rust e packages/typescript a partir de openapi/
```
```
gerador/
leitura_do_openapi.rs lê rotas, parâmetros, corpo, resposta e o catálogo de eventos (comum às duas linguagens)
rust/ escreve packages/rust/<serviço>/{rotas,tipos}.rs e webhook/eventos/contratos.rs
typescript/ escreve packages/typescript/<serviço>/{rotas,tipos,index}.ts, base/servicos.ts, index.ts e webhook/eventos/
packages/
rust/ crate termo_core (crates.io)
typescript/ pacote termo_core (npm)
```
- `openapi/` fica no git: toda mudança de API aparece no diff.
- O código gerado **nunca é editado à mão**. Código feito à mão fica em outros arquivos (como `publicar.rs` e `receber.rs` do `webhook` no Rust, e a pasta `base/` do TypeScript, menos `servicos.ts`).
- Serviço novo: adicione a constante em `packages/rust/base/servicos.rs` e em `TODOS_OS_SERVICOS`, a feature e o `pub mod` no `termo_core`, e rode o gerador. Ele cria o `mod.rs` do módulo novo e o módulo TypeScript inteiro.
## Publicação
O workflow [`publicar-termo-core.yml`](.github/workflows/publicar-termo-core.yml) roda a cada push na `production`, manualmente ou por `repository_dispatch` (`contratos_atualizados`). Ele sincroniza, gera, testa, faz commit dos contratos que mudaram e publica o `termo_core` no crates.io (segredo `CARGO_REGISTRY_TOKEN`) e no npm (segredo `NPM_TOKEN`), cada um só quando o código dele mudou, subindo o último número da versão de cada pacote.
Ao terminar com sucesso, o [`release-termo-core.yml`](.github/workflows/release-termo-core.yml) cria uma GitHub Release `crate-<versão>-npm-<versão>` com as versões publicadas, que serve de gatilho para outras rotinas. Se nenhuma versão mudou, nenhuma release nova é criada.