Initial project import
This commit is contained in:
Tiago
@@ -0,0 +1,87 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user