first commit

2026-08-14 17:35:24 -03:00
commit 04472fcd2b
118 changed files with 19173 additions and 0 deletions
@@ -0,0 +1,85 @@
+# Etapa 4/8 — Integrações: Evolution API (WhatsApp) e E-mail
+
+## Contexto do projeto
+
+Continuação do **SeConectai Vendas**. Já existem: setup do projeto, auth
+completa com RLS, e o CRUD de tenants/planos/faturas no painel master.
+
+Esta etapa conecta a infraestrutura de mensageria: cadastro da Evolution
+API (nível master), criação de instâncias de WhatsApp por tenant, e
+configuração de SMTP (padrão da plataforma e por tenant). **O disparo
+automático de alertas fica para a Etapa 7** — aqui o objetivo é deixar a
+infraestrutura de envio pronta e testável manualmente.
+
+## Tarefas
+
+1. **Módulo `evolution` — nível master (`src/modules/evolution/`)**
+   - CRUD de `evolution_api_config` (`POST/GET/PUT/DELETE
+     /master/evolution-config`), protegido por `MasterGuard`.
+   - **Nunca** retornar `api_key_cripto` em texto puro nas respostas da
+     API — mascarar (ex: mostrar só os últimos 4 caracteres).
+   - Implementar criptografia AES-256-GCM para `api_key_cripto` (chave
+     vinda de variável de ambiente `ENCRYPTION_KEY`, nunca hardcoded).
+     Criar um `EncryptionService` reutilizável (vai servir também para
+     `smtp_senha_cripto`).
+   - `POST /master/evolution-config/:id/testar-conexao` — faz uma chamada
+     simples à Evolution API (ex: endpoint de status/versão) para
+     validar que a `base_url`/`api_key` cadastradas funcionam.
+
+2. **Módulo `whatsapp` — nível tenant**
+   - `POST /tenant/whatsapp/instancias` (`TenantGuard`, role
+     `tenant_admin`) — cria uma instância na Evolution API (nome único
+     sugerido automaticamente, ex: `tenant-<slug>-<uuid curto>`), grava
+     em `tenant_whatsapp_instances` com status `desconectado`.
+   - `GET /tenant/whatsapp/instancias/:id/qrcode` — solicita o QR code
+     de conexão à Evolution API e retorna para o front exibir; atualiza
+     `qr_code_gerado_em`.
+   - `GET /tenant/whatsapp/instancias/:id/status` — consulta status atual
+     na Evolution API e sincroniza com o campo `status` local
+     (desconectado/conectando/conectado/erro).
+   - `DELETE /tenant/whatsapp/instancias/:id` — desconecta e remove a
+     instância na Evolution API e localmente.
+   - `POST /tenant/whatsapp/instancias/:id/testar-envio` — envia uma
+     mensagem de teste para um número informado, útil para o tenant
+     validar a conexão antes de confiar no sistema.
+   - Respeitar `limite_instancias_whatsapp` do plano do tenant ao criar
+     nova instância (retornar erro claro se o limite foi atingido).
+
+3. **Módulo `email-config`**
+   - `master_email_config`: CRUD simples (`MasterGuard`) — geralmente só
+     um registro ativo, mas manter como tabela para permitir trocar
+     provedor sem downtime.
+   - `tenant_email_config`: `GET/PUT /tenant/email-config`
+     (`TenantGuard`, role `tenant_admin`) — se `usar_config_padrao=true`,
+     ocultar/ignorar os campos de SMTP próprio; se `false`, exigir os
+     campos de SMTP preenchidos.
+   - `POST /tenant/email-config/testar-envio` — envia e-mail de teste
+     para um endereço informado, usando a config resolvida (própria ou
+     padrão).
+   - Implementar `EmailService` central que resolve automaticamente qual
+     SMTP usar (do tenant ou o padrão) e usa `nodemailer`.
+
+4. **Serviço central de envio (preparando a Etapa 7)**
+   - Criar `AlertDispatchService` com dois métodos:
+     `enviarWhatsapp(tenantId, numero, mensagem)` e
+     `enviarEmail(tenantId, destinatario, assunto, corpo)`. Ambos apenas
+     executam o envio (sem lógica de "quando enviar" — isso é da Etapa
+     7) e retornam sucesso/erro. Usar esse service nos endpoints de
+     "testar envio" acima, para já validar que funciona ponta a ponta.
+
+## Critérios de aceite
+
+- [ ] Master consegue cadastrar config da Evolution API e testar conexão
+- [ ] `api_key` e senha SMTP nunca aparecem em texto puro em nenhuma
+      resposta de API (conferir payloads)
+- [ ] Tenant consegue criar instância WhatsApp, obter QR code, escanear e
+      ver status mudar para `conectado`
+- [ ] Criar instância além do limite do plano retorna erro claro
+- [ ] Teste de envio de WhatsApp funciona (mensagem chega no número de
+      teste)
+- [ ] Tenant consegue configurar SMTP próprio ou usar o padrão da
+      plataforma
+- [ ] Teste de envio de e-mail funciona nos dois modos (SMTP próprio e
+      padrão)
+- [ ] `EncryptionService` usado de forma consistente para todos os
+      segredos armazenados