Operação do Seguros
Visão geral da plataforma Simplafy Seguros: vertical de cotação, propostas, KPIs e agentes IA (Lia, Nina) integrados a NestJS e Next.js.
Operação do Seguros
Simplafy Seguros é a vertical da Simplafy dedicada à operação de seguros e assinaturas. A plataforma centraliza cotação, propostas, KPIs comerciais e agentes de IA (Lia e Nina) sobre uma base NestJS + Next.js, com autenticação via cookies httpOnly e integração com o Simplafy Hub para dados de CRM.
A API pública responde em https://api-seguros.simplafy.com.br e o código vive em Simplafy-tec/simplafy-seguros.
A fonte única de verdade para roadmap, epics, stories e backlog do Seguros é o PM Board MCP (mcp__simplafy-admin-pm__*). Arquivos locais de roadmap não são autoritativos.
O que é
A plataforma cobre o ciclo operacional de seguros e assinaturas em três camadas:
- Backend NestJS — 24 módulos, 21 entidades, contratos de API documentados em
docs/api-contracts-backend.md. Roda em Node 20, TypeScript, PostgreSQL 16 com TypeORM, autenticação JWT via@nestjs/jwte validação comclass-validator. - Frontend Next.js 15 — 117 componentes, 14 páginas, 28 hooks. Usa React 19, Zustand para estado, React Query para data fetching, Tailwind 4 e shadcn/ui (
style: new-york, ícones Lucide). Inclui SDKs@ai-sdk/reacte@ai-sdk/mcppara as experiências de chat. - Integrações — Evolution API v2 para WhatsApp (módulo
EvolutionApiModuleemsrc/api/evolution/) e Simplafy Hub CRM para KPIs de assinaturas (chamado direto pelo frontend, não pelo backend NestJS).
Stats atuais do código:
| Camada | Volume |
|---|---|
| Backend | 24 módulos, 21 entidades, 100+ arquivos |
| Frontend | 117 componentes, 14 páginas, 28 hooks |
| Docs | 12 arquivos, 5000+ linhas |
Para quem é
Esta documentação é destinada a quem opera, integra ou estende a vertical de Seguros:
- Times de produto e operação — acompanhar KPIs de cotação, propostas e performance dos agentes Lia e Nina em vitrines dedicadas (
/dashboarde/subscription-metrics). - Desenvolvedores backend — trabalhar com os módulos NestJS, contratos de API, entidades TypeORM e o módulo de integração com Evolution API.
- Desenvolvedores frontend — consumir a API NestJS via axios com
withCredentials: true, ou o Hub CRM direto via hooks comouseSubscriptionKPIs. - Times de DevOps — operar deploy do registry GHCR (
ghcr.io/simplafy-tec/simplafy-seguros) no clusterprd-2, namespacesimplafy-prd-hub.
O Seguros divide o namespace simplafy-prd-hub no cluster prd-2 com o Simplafy Hub e o Simplafy Admin. Comandos de kubectl precisam apontar o namespace explicitamente.
Módulos principais
A plataforma é organizada em domínios funcionais. Os destaques são:
Autenticação e sessão
JWT em cookies httpOnly (não Bearer), refresh com proteção contra race condition, dual auth via JwtOrApiKeyGuard (JWT primeiro, API key como fallback).
Agente Lia (Seguros)
Agente WhatsApp 24/7 rodando em n8n, com histórico em digibroker_prd.n8n_chat_histories e vitrine operacional em /dashboard.
Agente Nina (Assinaturas)
Agente fora do horário comercial integrado ao Simplafy Hub CRM (CrmLead, CrmLeadHistory), com vitrine em /subscription-metrics.
Evolution API
Wrapper HTTP sobre Evolution API v2 em src/api/evolution/. Instâncias configuradas via variável EVOLUTION_INSTANCES no formato name:label,name:label.
Hub CRM Integration
Frontend consome GET {HUB_BASE_URL}/api/organizations/{orgId}/crm-pipelines/{pipelineId}/kpi direto, com env vars injetadas em build-time via --build-arg.
Dashboards e KPIs
Vitrines padronizadas em 5 faixas: hero comparativo, evolução 24h/7d/30d, diferenciais IA, heatmap horário e funil operacional.
Convenções transversais:
- Banco — PKs UUID, decorators TypeORM, CASCADE em entidades owned, SET NULL em referências, timestamps obrigatórios.
- API — fluxo padrão React Query → axios (
withCredentials: true) → NestJS com validação JWT → audit log automático. - Tokens — access token de 1h, refresh token de 7d.
- UI — sem cores hardcoded. Usar variáveis semânticas (
primary,destructive,warning,success,info,muted, etc.) deapp/globals.css.
Primeiros passos
O ambiente de desenvolvimento expõe três serviços em portas fixas:
| Serviço | Porta | Comando |
|---|---|---|
| Backend NestJS | 3200 | npm run start:dev |
| Frontend Next.js | 3100 | npm run dev |
| PostgreSQL | 5432 | docker compose up -d |
| MCP Postgres | 8000 | via compose |
Clonar o repositório
git clone https://github.com/Simplafy-tec/simplafy-seguros.git
cd simplafy-segurosConfigurar variáveis e MCPs
Copiar .mcp.json.example para .mcp.json e customizar para o seu ambiente. Secrets sensíveis ficam no Infisical, projeto simplafy-seguros (ID b327c845-7c2f-4e13-8924-e3938d76f351).
Subir o banco e instalar dependências
docker compose up -d
npm install
cd frontend && npm install && cd ..Rodar backend e frontend
Em dois terminais separados:
npm run start:devcd frontend && npm run devO backend fica em http://localhost:3200 e o frontend em http://localhost:3100.
Validar a mudança antes de commitar
npx tsc --noEmit
npm testPara o frontend, rodar cd frontend && npx tsc --noEmit. Existem erros pré-existentes em AIChatClient, testes de vendas e SignupForm que não bloqueiam.
Para deploy em staging, rodar npm run deploy:staging -- latest (build e push das imagens backend e frontend para GHCR). O rollout no cluster é via kubectl rollout restart deployment/simplafy-seguros-backend deployment/simplafy-seguros-frontend -n simplafy-prd-hub no host prd-2.
Próximas leituras recomendadas:
docs/index.md— índice oficial e fonte primária de pesquisa.docs/api-contracts-backend.md— contratos de API.docs/data-models-backend.md— entidades e relacionamentos.docs/ui-components-state-frontend.md— componentes e estado do frontend.