SeConectai_Vendas/Etapas/04-integracoes-evolution-email.md

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