campaigns

O submódulo Campaigns é dono do próprio registro `campaign`: seu conteúdo (assunto, corpo em HTML/texto simples, referência opcional a um template), sua lista de destinatários, seu perfil de entrega e sua máquina de estados de ciclo de vida. Uma campanha é criada com status `draft` e avança por `scheduled` → `sending` → `completed` (ou `paused`, `canceled`, `failed`) à medida que o CampaignDispatchService a conduz adiante. Apenas campanhas com status `draft`, `canceled` ou `failed` podem ser excluídas, o que protege os dados históricos de entrega de tudo o que realmente já foi enviado.

Iniciar uma campanha (`POST /campaign/:id/start`, com alias em `/send`) é a operação mais complexa do módulo. O CampaignDispatchService primeiro valida que a campanha possui um perfil de entrega de e-mail (um Integration Profile), uma lista de destinatários e conteúdo não vazio e — quando a configuração `campaign.unsubscribe.required` está habilitada — que o conteúdo inclui o placeholder `{{unsubscribeUrl}}`. Em seguida, ele carrega a lista de destinatários, deduplica por e-mail normalizado e faz o cruzamento com a lista global de supressão antes mesmo de tocar o banco de dados em uma transação de escrita. Dentro de uma única transação, ele faz upsert de uma linha `campaign_message` por destinatário elegível (pulando os suprimidos/descadastrados/com bounce como `skipped` e reaproveitando linhas que já existem para evitar duplicar envios em andamento na retomada), depois atualiza os contadores da campanha e muda o status para `sending`. Somente após o commit da transação é que ele enfileira um job de fila por mensagem pendente via `CampaignEmailWorkerService` — ou, se `campaign.queue.enabled` estiver desligado, envia cada mensagem de forma inline e síncrona dentro da mesma requisição, reportando o progresso por destinatário através de um registro de Notification.

Pausar e retomar afetam apenas o status da campanha; as mensagens subjacentes e seus jobs de fila são deixados intactos, de modo que uma campanha retomada continua de onde a fila em andamento parou, em vez de reenfileirar mensagens já enviadas. Cancelar define `status: canceled`, que o worker lê no momento do envio para pular as mensagens restantes sem excluí-las. Duplicar cria um novo rascunho a partir do conteúdo e da configuração de uma campanha existente, redefinindo explicitamente cada contador de entrega, timestamp e o agendamento, para que a cópia comece limpa.

O dashboard global (`GET /campaign/dashboard`) e o dashboard por campanha (`GET /campaign/:id/dashboard`) são endpoints de agregação somente leitura respaldados pelo CampaignDashboardService: contagens de status em todas as campanhas, mensagens enviadas hoje, backlog pendente/enfileirado, contagens de falhas nas últimas 24h, totais de supressão/descadastramento e um histórico de envios agrupado por dia dos últimos 7/30 dias, além do contexto de rate-limit (cota diária e capacidade restante) fornecido pelo CampaignRateLimitService. O `GET /campaign/:id/status` é uma combinação mais leve do registro bruto da campanha com contagens agregadas de status de mensagens, útil para polling sem carregar o payload completo do dashboard. Cada transição de estado também grava uma linha de auditoria via CampaignEventService, exposta em `GET /campaign/:id/events`.