86 lines
4.3 KiB
Markdown
86 lines
4.3 KiB
Markdown
# 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
|