SeConectai_Vendas/Etapas/07-motor-de-alertas.md

Etapa 7/8 — Motor de Alertas (BullMQ)

Contexto do projeto

Continuação do SeConectai Vendas. Já existem: setup, auth com RLS, painel master completo, integrações Evolution API/e-mail com serviço central de envio (AlertDispatchService), CRUD de customers/produtos, e o módulo completo de vendas/parcelas/dashboards.

Esta é a etapa que automatiza o que até agora só existia como endpoint manual: verificação de vencimentos e disparo de alertas, nos dois níveis do sistema (master→tenant e tenant→customer).

Tarefas

1. Infraestrutura de filas

   • Configurar @nestjs/bullmq conectado ao Redis já disponível no docker-compose.
   • Criar duas filas: alertas-mensalidade (master→tenant) e alertas-cobranca (tenant→customer).
   • Criar um processo/worker separado do processo web principal (pode ser o mesmo container em dev, mas documentar como se separaria em produção — ex: main.ts vs worker.ts, ou um segundo serviço no docker-compose chamado worker rodando o mesmo build com um comando diferente).

2. Módulo alert-templates

   • CRUD de alert_templates:
     • Nível master (MasterGuard): templates padrão da plataforma (tenant_id = null), tipo mensalidade_tenant.
     • Nível tenant (TenantGuard, role tenant_admin): templates próprios, tipo cobranca_cliente (e outros tipos que fizerem sentido, ex: venda_confirmada, lembrete_vencimento). Se o tenant não tiver template próprio para um tipo/canal, usar o template padrão do master como fallback.
   • Implementar renderização de placeholders ({{nome}}, {{valor}}, {{vencimento}}, etc — listar todos os placeholders suportados por tipo de template em um arquivo de constantes, documentado).

3. Job diário: mensalidade_tenant

   • Cron (ex: todo dia às 8h, horário configurável via env) que:
     1. Roda a lógica equivalente ao endpoint POST /master/faturas/atualizar-atrasadas (marca faturas vencidas como atrasado, tenant vira inadimplente).
     2. Para toda tenant_faturas com vencimento em N dias (configurável, ex: 3 dias antes) ou já vencida e ainda sem alerta hoje, enfileira um job na fila alertas-mensalidade com os dados necessários.
   • Worker da fila alertas-mensalidade: busca template (mensalidade_tenant, canal whatsapp e/ou email conforme configurado), renderiza, chama AlertDispatchService, grava resultado em alert_logs, atualiza tenant_faturas.alerta_enviado_em.

4. Job diário: cobranca_cliente (por tenant)

   • Mesmo padrão do job acima, mas iterando sale_payments de todos os tenants ativos: marca atrasadas, enfileira alerta para parcelas próximas do vencimento ou já atrasadas (respeitando alerta_enviado_em para não notificar duas vezes no mesmo dia).
   • Usa a instância WhatsApp e config de e-mail do tenant dono da venda, não a do master.

5. Idempotência e resiliência

   • Garantir que um mesmo job não dispare o mesmo alerta duas vezes (checar alerta_enviado_em antes de enfileirar, e novamente antes de enviar, dentro do worker, para lidar com concorrência).
   • Configurar retry com backoff exponencial no BullMQ para falhas transitórias de envio (ex: Evolution API fora do ar), com limite de tentativas (ex: 3) e log do erro final em alert_logs.erro.
   • Endpoint de observabilidade: GET /master/alertas/logs e GET /tenant/alertas/logs para consultar alert_logs com filtros (canal, status, período).

Critérios de aceite

• Worker processa as duas filas de forma independente do processo web (documentado como escalar workers separadamente)
• Template do tenant sobrepõe o padrão do master quando existe; usa fallback quando não existe
• Placeholders são substituídos corretamente na renderização
• Job diário marca faturas/parcelas atrasadas corretamente
• Alerta de mensalidade chega no WhatsApp/e-mail do tenant em teste controlado (vencimento simulado para "hoje")
• Alerta de cobrança chega no WhatsApp/e-mail do customer, usando a instância/config do tenant correto (testar com 2 tenants diferentes)
• Mesmo alerta não é disparado duas vezes no mesmo dia (testar rodando o job duas vezes seguidas)
• Falha de envio é reprocessada com retry e, após esgotar tentativas, fica registrada em alert_logs com erro
• Endpoints de consulta de logs funcionam com os filtros esperados