Visão geral
O TermoIntranetAPI é o sistema de atendimento com IA da Termotubos. Robôs configurados pelos colaboradores respondem as conversas que chegam pelo WhatsApp (via Z-API) e pelo Chatwoot, seguindo etapas, instruções e ferramentas definidas no painel.
O sistema tem duas metades, no padrão de projeto da Termotubos:
| Parte | Endereço em dev | O que faz |
|---|---|---|
| Frontend (SvelteKit) | http://localhost:51090 | O painel dos colaboradores (/painel) e a landing page |
| Backend (Rust + Axum) | http://localhost:51091 | A API, os webhooks do Z-API e do Chatwoot e a chamada aos modelos de IA |
| PostgreSQL (Docker) | localhost:51099 | Banco do app, no schema termointranetapi |
O que existe no painel
| Área | Rota | O que faz |
|---|---|---|
| Robôs | /painel/robos | Cadastro dos robôs: modelo de IA, prompt base e o fluxo da conversa em canvas (etapas de instrução do modelo, com condição de saída e ferramentas, e etapas de botões que ramificam o atendimento) |
| Conversas | /painel/conversas | Histórico das conversas com os clientes: canal, assunto e resumo |
| Clientes | /painel/clientes | Cadastro dos clientes (razão social, CNPJ, contato) |
| Colaboradores | /painel/colaboradores | Cadastro dos colaboradores e das permissões de ler, criar, editar e deletar |
| Configurações | /painel/configuracoes | Provedores de IA, instâncias do Z-API e contas do Chatwoot |
Como uma mensagem é respondida
- A mensagem chega por webhook:
receberEventoZApi(WhatsApp) oureceberEventoChatwoot, embackend/controller/webhooks/. - O backend passa a conversa para o robô configurado (
responderComoRobo, embackend/integrations/llm/). - A resposta é gerada no provedor de IA configurado: ChatGPT, Gemini ou DeepSeek.
- A resposta volta pelo mesmo canal, pelas integrações
z_apiouchatwoot.
Integrações
| Integração | Pasta | Para que serve |
|---|---|---|
| IA | backend/integrations/llm/ | Gera as respostas dos robôs e valida as chaves e os modelos de cada provedor |
| Z-API | backend/integrations/z_api/ | Recebe e envia mensagens do WhatsApp |
| Chatwoot | backend/integrations/chatwoot/ | Recebe e envia mensagens das caixas de entrada do Chatwoot |
| Intranet | backend/integrations/intranet/ | Consulta dados da intranet da Termotubos |
Acesso
O login é do TermoAuth (app termo-intranet-api): o frontend manda a pessoa para o /handoff do TermoAuth, recebe o JWT em /painel#token= e o envia em Authorization: Bearer a toda chamada. O backend valida o token offline pelo JWKS do TermoAuth e libera só quem tem cadastro ativo na tabela auth (e-mail, perfil colaborador ou cliente, ativo e termoauth_id). Não existe senha no TermoIntranetAPI.
Rodando localmente
| Serviço | Porta | Como subir |
|---|---|---|
| Frontend | 51090 | Configuração frontend do .claude/launch.json |
| Backend | 51091 | Configuração backend do .claude/launch.json |
| Documentação | 51092 | Configuração docs-projeto do .claude/launch.json |
| Diagrama do banco (ERD) | 51093 | Configuração database-erd do .claude/launch.json |
| Drizzle Studio | 51094 | Configuração database-studio do .claude/launch.json |
| PostgreSQL | 51099 | docker compose up -d na raiz |
Esta é a primeira página da documentação do TermoIntranetAPI. As próximas páginas entram em docs/projeto/src/routes/docs/<pagina>/+page.md, e o menu lateral é definido em docs/projeto/src/navegacao.json.