# 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