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):

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
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).
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).
Para cada tentativa (sucesso ou falha), grava uma linha em logs_envio_avisos (no db_master, incluindo contato_nome como snapshot).
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.

5.5 KiB Raw Blame History Unescape Escape