88 lines
5.5 KiB
Markdown
88 lines
5.5 KiB
Markdown
# Prompt 08 — Avisos/alertas: Evolution API (WhatsApp), e-mail e destinatários
|
||
|
||
## Contexto
|
||
Prompts 01–07 concluídos: financeiro funcionando, CRUD de condomínios/contatos completo. **Leia `10-tracker-progresso.md` antes de começar.**
|
||
|
||
Este prompt implementa: conexão da instância WhatsApp (Evolution API) pelo escritório + aprovação pelo master, configuração de SMTP único da plataforma, e o fluxo completo de criação/envio de avisos com documentos anexados e destinatários.
|
||
|
||
## Objetivo
|
||
CRUD de `avisos` + `aviso_documentos` + `aviso_destinatarios`, conexão/aprovação de instância Evolution, configuração de SMTP, envio real de mensagens (WhatsApp e e-mail) respeitando o catálogo de `funcionalidades` liberado por empresa, e gravação em `logs_envio_avisos`.
|
||
|
||
## Especificação
|
||
|
||
### 1. Conectar WhatsApp (escritório)
|
||
```
|
||
POST /api/config/evolution-instancia/conectar
|
||
body: {"instance_url", "numero_whatsapp"}
|
||
→ cria a instância na Evolution API (consultar a documentação oficial da Evolution API
|
||
pra confirmar o endpoint exato de criação de instância e pareamento por QR Code —
|
||
não assumir o formato sem checar), grava em evolution_instancias com status='pendente'
|
||
(mesmo depois de parear o QR Code com sucesso do lado da Evolution — a ativação pra
|
||
USO no sistema depende da aprovação do master)
|
||
→ retorna o QR Code (imagem/base64) pro frontend exibir e o funcionário escanear
|
||
GET /api/config/evolution-instancia/status
|
||
→ status atual: pendente, aprovada, rejeitada, inativa
|
||
```
|
||
|
||
### 2. Aprovação (master)
|
||
```
|
||
GET /api/master/empresas/{id}/evolution-instancias
|
||
POST /api/master/empresas/{id}/evolution-instancias/{instId}/aprovar
|
||
POST /api/master/empresas/{id}/evolution-instancias/{instId}/rejeitar
|
||
```
|
||
|
||
### 3. Configuração de e-mail (master, plataforma única)
|
||
```
|
||
GET /api/master/configuracoes
|
||
PUT /api/master/configuracoes
|
||
body: {"smtp_host", "smtp_port", "smtp_user", "smtp_password", "smtp_remetente"}
|
||
→ salva em configuracoes_plataforma (senha deve ser guardada de forma reversível pra
|
||
uso no envio, mas nunca retornada em texto puro no GET — mascarar tipo "••••1234"
|
||
se quiser mostrar algo, ou simplesmente omitir o campo senha no GET)
|
||
```
|
||
|
||
### 4. Avisos — CRUD completo
|
||
```
|
||
POST /api/condominios/{id}/avisos
|
||
body: {"assembleia_id" (opcional), "tipo": "aviso"|"alerta", "titulo", "mensagem",
|
||
"data_evento" (opcional), "data_expiracao" (opcional), "prioridade",
|
||
"documentos": [documentoId, ...], "destinatarios": [{"tipo":"contato","id":X}, ...],
|
||
"enviar_whatsapp": bool, "enviar_email": bool}
|
||
→ valida que enviar_whatsapp só pode ser true se a empresa tiver a funcionalidade
|
||
'whatsapp_envio' ativa E uma evolution_instancia com status='aprovada'; valida que
|
||
enviar_email só pode ser true se a empresa tiver 'email_envio' ativa
|
||
→ grava o aviso + vínculos em aviso_documentos + aviso_destinatarios
|
||
→ se enviar_whatsapp ou enviar_email = true, dispara o envio (ver seção 5) de forma
|
||
síncrona nesta fase (fila assíncrona fica como melhoria futura documentada no código)
|
||
GET /api/condominios/{id}/avisos
|
||
GET /api/condominios/{id}/avisos/{avisoId}
|
||
```
|
||
|
||
### 5. Envio efetivo
|
||
`NotificacaoService.enviarAviso(aviso)`:
|
||
1. Busca os `aviso_destinatarios`; para cada um, resolve nome/telefone/email:
|
||
- se `tipo_destinatario='contato'`: busca em `contatos` (tenant)
|
||
- se `tipo_destinatario='funcionario'`: busca em `db_master.funcionarios`
|
||
2. Para cada destinatário, se `enviar_whatsapp`: chama `EvolutionApiClient.enviarMensagem(instanceUrl, token, numero, mensagem, anexos)` (consultar doc da Evolution API pro formato exato de envio com anexo).
|
||
3. Se `enviar_email`: chama `EmailClient.enviar(smtpConfig, destinatarioEmail, assunto=titulo, corpo=mensagem, anexos=documentos)` — usar `jakarta.mail` (única dependência nova aqui, é a forma padrão de mandar e-mail em Java puro).
|
||
4. Para cada tentativa (sucesso ou falha), grava uma linha em `logs_envio_avisos` (no `db_master`, incluindo `contato_nome` como snapshot).
|
||
5. Atualiza `avisos.status_envio` = 'enviado' se todas as tentativas relevantes deram certo, 'falhou' se pelo menos uma falhou.
|
||
|
||
### 6. Reenvio manual
|
||
```
|
||
POST /api/condominios/{id}/avisos/{avisoId}/reenviar
|
||
→ reprocessa só os destinatários cujo último log foi 'falhou'
|
||
```
|
||
|
||
## Critérios de aceite
|
||
- [ ] Escritório sem a funcionalidade `whatsapp_envio` ativa recebe erro claro ao tentar criar aviso com `enviar_whatsapp=true`.
|
||
- [ ] Conectar uma instância Evolution gera QR Code; aviso criado com `enviar_whatsapp=true` antes da aprovação do master é rejeitado com mensagem clara ("instância pendente de aprovação").
|
||
- [ ] Depois do master aprovar a instância, o mesmo aviso consegue ser enviado.
|
||
- [ ] Envio por e-mail funciona de ponta a ponta usando um SMTP de teste (ex: Mailtrap ou Gmail com senha de app) configurado via `PUT /api/master/configuracoes`.
|
||
- [ ] Um destinatário com telefone/e-mail inválido gera uma linha `falhou` em `logs_envio_avisos` sem quebrar o envio pros demais destinatários.
|
||
- [ ] `POST .../reenviar` só reprocessa quem falhou, não reenvia pra quem já recebeu com sucesso.
|
||
- [ ] Documento anexado ao aviso (via `aviso_documentos`) é de fato enviado como anexo no WhatsApp/e-mail.
|
||
|
||
## Ao concluir
|
||
Atualizar `10-tracker-progresso.md`: Prompt 08 concluído, data, resumo. Confirmar Prompts 01–07 seguem marcados.
|