Arquitetura

O TermoPortal segue o mesmo padrão dos outros sistemas da Termotubos: backend em Rust organizado por feature, com as mesmas 7 operações em toda feature, e frontend em SvelteKit. A regra de negócio, a autorização, o escopo por empresa, a sessão (cookie httpOnly) e os arquivos enviados ficam no Rust; o frontend é um site estático, sem servidor, que chama a API direto do navegador.

Stack

Como uma requisição anda

navegador (site estático, portal.termotubos.com.br) ──► API Rust (api-portal.termotubos.com.br) ──► PostgreSQL (schema termoportal)
                                                        cookie httpOnly "sessao" + CORS

• O navegador chama a API direto (endereço em PUBLIC_API_URL). A sessão é o cookie httpOnly sessao, gravado pela API no login (POST /sessao) e mandado em toda chamada; o JavaScript nunca vê o token.
• Site e API no mesmo site (*.termotubos.com.br): o cookie é SameSite=Lax, a API só responde via CORS às origens de FRONTEND_URL e recusa escrita pelo cookie sem Origin do frontend (CSRF).
• A API continua ouvindo em 127.0.0.1; a exposição para o navegador (proxy ou túnel) é da infra.
• Arquivos enviados (imagens de produto, PDFs de boletim, anexos de demanda) ficam no disco da API, na pasta UPLOAD_DIR, e são servidos em /arquivo/... (com sessão). Os boletins técnicos também abrem por /boletins/<slug> no portal, que redireciona para a API.

Organização do repositório

├── backend/
│   ├── main.rs
│   ├── router/
│   │   └── cotacao.rs
│   ├── controller/
│   │   ├── cotacao/
│   │   │   ├── criar.rs
│   │   │   ├── buscarPeloId.rs
│   │   │   ├── buscarPeloFiltro.rs
│   │   │   ├── buscarPaginador.rs
│   │   │   ├── buscarAutoComplete.rs
│   │   │   ├── atualizarPeloId.rs
│   │   │   └── deletarPeloId.rs
│   │   └── sessao/
│   │       └── exigirSessao.rs
│   ├── model/
│   │   ├── cotacao/
│   │   └── sessao/
│   ├── integrations/
│   │   ├── termoauth/
│   │   ├── termotubos/
│   │   └── chatwoot/
│   ├── migrations/
│   └── seeds/
├── frontend/
│   ├── src/hooks.client.ts
│   ├── src/lib/
│   │   ├── api/client.ts
│   │   └── auth/session.ts
│   └── src/routes/
│       ├── (portal)/
│       ├── login/
│       ├── app/
│       └── convite/
├── docs/
│   └── projeto/
└── .github/workflows/

Backend: 7 operações por feature

Cada feature tem um arquivo em router/, uma pasta em controller/ com um handler por operação e uma pasta em model/, que é a única camada que fala com o banco.

Features que não são cadastros expõem só o que faz sentido. Por exemplo, sessao tem POST /sessao (entrar) e GET/DELETE /sessao/atual; produto_termotubos tem só a busca na API e a importação; chatwoot_entrega_webhook tem só o POST que o Chatwoot chama.

Banco de dados

• PostgreSQL com SQLx, sem ORM: a fonte da verdade é o banco, e o histórico dele são as migrations em backend/migrations/. O backend aplica as migrations sozinho ao subir.
• Schema próprio. Tudo do portal, inclusive a tabela _sqlx_migrations, fica no schema termoportal (constante ESQUEMA_BANCO em main.rs). O backend cria o schema se ele não existir e conecta com search_path só nele, porque os apps da Termotubos podem dividir o mesmo banco, como acontece na sandbox.
• Exclusão lógica. Toda tabela tem deletado boolean NOT NULL DEFAULT false, os índices únicos são parciais (WHERE deletado = false) e as leituras filtram os deletados.
• Dinheiro e quantidades fracionárias são numeric. Enumerações viram text com CHECK. Dados aninhados, como os itens de uma cotação, são jsonb.
• Snapshots. Cotação, pedido e fatura guardam uma cópia dos dados do momento (itens com preço, frete aplicado, cupom), para que mudanças posteriores no catálogo não reescrevam o passado.

Autenticação e autorização

O portal não guarda senha. O login é do TermoAuth; o portal só troca o JWT dele por uma sessão local.

1. Validação do JWT offline em integrations/termoauth/: algoritmo EdDSA, chave pública buscada pelo kid no JWKS de TERMOAUTH_API_URL (/.well-known/jwks.json), iss e aud iguais a TERMOAUTH_URL, e exp. As chaves ficam em cache; um kid desconhecido só dispara nova busca depois de 30 segundos da anterior.
2. Sessão local. POST /sessao acha a pessoa pelo sub do token (pessoa.identificador_termoauth) e grava na tabela sessao só o resumo SHA-256 de um token opaco, válido por 5 dias.
3. Middleware único. controller/sessao/exigirSessao.rs roda em toda rota. Ele consulta o mapa requisito() de model/sessao/mod.rs, que decide por feature e método HTTP o que a rota exige, e injeta o Contexto da sessão (pessoa, se é interna, se é administradora, permissões por módulo, permissões administrativas e empresas).

O escopo por empresa e por pessoa fica nos controllers: listagem de cliente exige uma empresa das dele, registro de outra empresa responde 404, e o autor de uma cotação ou demanda criada por cliente é sempre quem está logado. O controle por página no frontend só mostra e esconde telas; nunca é a barreira real. O fluxo completo está em Entrada e acesso .

Integrações

Variáveis de ambiente

No frontend só existem variáveis públicas: todas vão para o navegador, então nunca guardam segredo.

Portas de desenvolvimento

O TermoPortal usa a faixa 51010–51019 do padrão de portas da Termotubos. O TermoAuth, que devolve a pessoa ao portal, roda sempre em http://localhost:51000 e tem o portal-b2b registrado com o frontend em 51010.

Rodando localmente

1. Banco

Em backend/, docker compose up --detach sobe o PostgreSQL em localhost:51019. O DATABASE_URL do backend/.env.local termina em ?options=-c%20search_path%3Dtermoportal para o sqlx CLI enxergar o mesmo schema do backend.

2. Backend

cargo run aplica as migrations e sobe a API. cargo run --bin seeds cria os dados padrão (perfis, configurações, fretes, departamentos, categorias, alertas de estoque e a pessoa master ti.04@termotubos.com.br); com -- --teste, cria também grupos, empresas e pessoas de teste.

3. Primeiro acesso

A pessoa master entra pelo TermoAuth com o Google, que confirma o e-mail e liga a conta sozinho, ou por convite: cargo run --bin seeds -- --convite ti.04@termotubos.com.br imprime o caminho /convite?token=... para abrir em http://localhost:51010.

4. Frontend

Em frontend/, npm run dev sobe o portal em http://localhost:51010, com PUBLIC_API_URL apontando para a API (e o FRONTEND_URL do backend com http://localhost:51010).

Deploy da sandbox

O repositório oficial é github.com/OrgTermotubos/TermoPortal. Um push na branch sandbox dispara os workflows deploy-sandbox-backend.yml e deploy-sandbox-frontend.yml do GitHub Actions, conforme a pasta alterada.

• Backend: compila em release, monta o .env com os segredos SANDBOX_*, envia por SSH para /opt/termoportal/backend e reinicia o serviço termoportal-backend, que escuta em 127.0.0.1:51011.
• Frontend: site estático no Cloudflare Pages (npm run build, pasta build, variáveis PUBLIC_* no ambiente do build). O workflow antigo deploy-sandbox-frontend.yml (SSH + serviço Node) ficou obsoleto com o frontend estático.
• Fila única. Os dois workflows usam o grupo de concorrência deploy-sandbox sem cancelar o anterior: quando um push mexe nos dois lados, os deploys rodam um depois do outro.
• TermoAuth da sandbox: https://sandbox-auth.navsoftware.com.br, com a API em https://api-sandbox-auth.navsoftware.com.br.