first commit

Etapas/seconectai-vendas-arquitetura.md

@@ -0,0 +1,118 @@
+# 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.