termo_core 0.1.1

Todos os clientes da Termotubos num crate só: um módulo por serviço e cada rota da API como uma função de uma linha, com o endereço resolvido pelo ambiente atual.
Documentation
# TermoCore

Todos os clientes da Termotubos num **crate só**, o `termo_core`. 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.

```toml
termo_core = "=0.1.5"                                          # todos os serviços
termo_core = { version = "=0.1.5", features = ["webhook_postgres"] } # + fila de saída de eventos
```

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?;
```

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: só 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 [`termo_core/base/servicos.rs`](termo_core/base/servicos.rs). 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.

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://...")`.

## Serviços

| Módulo     | Serviço          |
| ---------- | ---------------- |
| `termo_core::ai` | TermoAI |
| `termo_core::auth` | TermoAuth |
| `termo_core::bucket` | TermoBucket |
| `termo_core::intranet` | TermoIntranetAPI |
| `termo_core::leads` | TermoLeads |
| `termo_core::mcp` | TermoMCP |
| `termo_core::portal` | TermoPortal |
| `termo_core::quality` | TermoQuality |
| `termo_core::sell` | TermoSell |
| `termo_core::status` | TermoStatus |
| `termo_core::studio` | TermoStudio |
| `termo_core::support` | TermoSupport |
| `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`, `webhook_receber` e `webhook_postgres` (veja abaixo).

## 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;

// Ao subir, uma vez (feature webhook_postgres):
termo_core::webhook::iniciar_envio_automatico_dos_eventos_guardados(&pool, termo_core::webhook::ConfiguracaoDoHub::carregar_do_ambiente_atual()).await?;

// No model, dentro da transação que já grava a mudança:
termo_core::webhook::guardar_evento_para_publicar_na_mesma_transacao(&mut *transacao, id.to_string(), ColaboradorCriadoV1 { /* ... */ }).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`. O app informa só `TERMOWEBHOOK_APLICATIVO_ID` e, se publica, o segredo `TERMOWEBHOOK_SEGREDO_DE_PUBLICACAO`.

## 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 termo_core/<serviço>/rotas.rs e tipos.rs, e termo_core/webhook/eventos/contratos.rs
```

- `openapi/` fica no git: toda mudança de API aparece no diff.
- `rotas.rs`, `tipos.rs` e `eventos/contratos.rs` **nunca são editados à mão**. Código feito à mão fica em outros arquivos do módulo (como `publicar.rs` e `receber.rs` do `webhook`).
- Serviço novo: adicione a constante em `termo_core/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.

## 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 quando o código mudou, subindo o último número da versão. Usa o segredo `CARGO_REGISTRY_TOKEN`.