SeConectai_Vendas/Etapas/seconectai-vendas-arquitetura.md

# SeConectai Vendas — Arquitetura

CRM/controle de vendas multi-tenant, com um painel **master** (você, dono da
plataforma) e painéis de **tenant** (seus clientes, que por sua vez cadastram
os próprios clientes/vendas).

## 1. Modelo de dados (resumo)

```
master_admins              → você e sua equipe (login do painel master)
evolution_api_config        → conexão(ões) com a Evolution API 2.3
master_email_config         → SMTP padrão da plataforma
planos                      → planos de assinatura que você vende
tenants                     → seus clientes (quem compra a plataforma)
tenant_faturas               → mensalidades que o tenant te deve
tenant_users                 → usuários/login de cada tenant
tenant_whatsapp_instances    → instância Evolution API de cada tenant
tenant_email_config           → SMTP próprio do tenant (opcional)
alert_templates               → mensagens (WhatsApp/e-mail) customizáveis
alert_logs                    → auditoria de todo alerta enviado
customers                    → clientes (empresas) de cada tenant
customer_contacts             → contatos dentro dessas empresas
products_services              → catálogo de produto/serviço por tenant
sales / sale_items / sale_payments → vendas, itens e parcelas a receber
audit_logs                    → trilha de auditoria geral
```

Arquivo completo: `seconectai-vendas-schema.sql`.

## 2. Estratégia de multi-tenancy

Banco único, todas as tabelas de dado operacional carregam `tenant_id`, com
**Row Level Security (RLS)** do Postgres isolando cada tenant. A aplicação
define `SET app.current_tenant_id = '<uuid>'` na conexão/transação do
usuário logado; o Postgres bloqueia qualquer leitura/escrita fora do tenant
automaticamente — mesmo que haja um bug na query da aplicação.

Por que essa abordagem em vez de "um schema por tenant" ou "um banco por
tenant": com um único Postgres em Docker, migrations, backup e escala
operacional ficam muito mais simples, e RLS já dá o isolamento de segurança
que schema-per-tenant tentaria resolver com mais complexidade operacional.
O usuário master (você) usa uma role de banco separada com `BYPASS ROW LEVEL
SECURITY`, para poder ver/gerenciar todos os tenants.

## 3. Stack sugerida

- **Backend:** Node.js + TypeScript, com NestJS (organização em módulos por
  domínio: auth, tenants, customers, products, sales, alerts) ou Fastify se
  quiser algo mais enxuto. Node se encaixa bem no seu workflow atual
  (n8n, Evolution API, JS/TS já no dia a dia).
- **ORM:** Prisma — migrations versionadas, tipagem forte, e dá pra injetar
  o `SET app.current_tenant_id` por transação com `$transaction`.
- **Banco:** PostgreSQL 16.
- **Fila/agendamento:** Redis + BullMQ, para dois tipos de job recorrente:
  - varredura diária de vencimentos (`tenant_faturas` e `sale_payments`)
    disparando alertas antes/no dia do vencimento;
  - envio assíncrono de mensagens (não travar a request do usuário
    esperando resposta da Evolution API/SMTP).
- **Autenticação:** JWT de curta duração (access token) + refresh token com
  rotação, guardado com hash (nunca em texto puro) na tabela
  `auth_refresh_tokens`. Senha com `argon2id` (preferível a bcrypt hoje).
- **Deploy:** Docker Compose com serviços `app`, `postgres`, `redis` — a
  Evolution API pode rodar no mesmo compose ou em servidor separado (você
  já mantém instância própria, então só precisa cadastrar a `base_url` +
  `api_key` em `evolution_api_config`).

## 4. Segurança — pontos que valem atenção na implementação

- Hash de senha: `argon2id`, nunca MD5/SHA puro.
- Segredos (API key da Evolution, senha SMTP) criptografados em repouso
  (AES-256-GCM) com chave fora do banco (variável de ambiente/secret
  manager), não só "hash" — porque esses precisam ser recuperados em texto
  puro para uso.
- Rate limiting no login (a tabela `login_attempts` já dá suporte a isso) e
  bloqueio temporário após N tentativas falhas.
- 2FA (TOTP) pelo menos para `master_admins`, opcional para `tenant_admin`.
- RLS como camada de defesa adicional — mesmo com bug de aplicação, tenant A
  não acessa dado de tenant B.
- HTTPS obrigatório, cookies de refresh token com `httpOnly` + `Secure` +
  `SameSite=Strict`.
- Logs de auditoria (`audit_logs`, `alert_logs`) para rastrear quem fez o
  quê — importante já que múltiplos tenants e usuários mexem no sistema.

## 5. Fluxo de alertas (o motor comercial do sistema)

Dois níveis, mesma mecânica:

1. **Master → Tenant:** job diário verifica `tenant_faturas` com vencimento
   próximo/vencido → gera mensagem a partir de `alert_templates`
   (`tipo='mensalidade_tenant'`) → envia via WhatsApp (Evolution API,
   instância própria do master) e/ou e-mail (`master_email_config`) →
   grava em `alert_logs`.
2. **Tenant → Customer:** mesmo job (ou outro, escopado por tenant) verifica
   `sale_payments` pendentes/atrasados de cada tenant → usa a instância
   Evolution do próprio tenant (`tenant_whatsapp_instances`) e o SMTP dele
   (ou o padrão da plataforma, se `usar_config_padrao=true`) → envia e
   registra em `alert_logs`.

Isso te dá, de graça, o mecanismo pra cobrar a própria mensalidade da
plataforma (item que você pediu explicitamente) usando a mesma
infraestrutura que o tenant usa pra cobrar os clientes dele.

## 6. Próximos passos sugeridos

Seguindo seu formato usual de build faseado (prompts sequenciais com
critério de aceite por etapa), a ordem natural seria:

1. Setup do projeto (Docker Compose, Postgres, Prisma, estrutura NestJS)
2. Auth (master + tenant_user, JWT/refresh, RLS aplicado)
3. CRUD de tenants + planos + faturas (painel master)
4. Cadastro Evolution API + instâncias WhatsApp por tenant
5. CRUD de customers, products_services (painel tenant)
6. Vendas (sales/sale_items/sale_payments) + dashboards (views já prontas)
7. Motor de alertas (BullMQ + templates + logs)
8. Personalização visual (logo/cor por tenant)

Posso detalhar qualquer uma dessas fases em um prompt de vibe coding
próprio, se quiser seguir esse fluxo.