B2BCall-dialer/docs/CAMPAIGNS.md

Campanhas, Leads e Lista de Bloqueio

Agente.md secao 63-71. Modelo de dados, CRUD, máquina de estados da campanha e importação de leads — o motor que de fato origina chamadas (PredictiveDialerEngine, secao 72-86) é uma fase à parte, deliberadamente não implementada aqui (é um sistema grande o suficiente — pacing por EWMA, previsão de liberação de agentes, CPS distribuído, reserva atômica de leads — pra merecer o próprio ciclo de design/teste, ver agente.md secao 72 "Não implementar apenas for lead -> originate. Isso não é discador preditivo.").

Modelo

• campaigns (tenant-scoped, RLS): liga Queue+Trunk, janela de funcionamento (timezone/daysOfWeek/startTime/endTime/startDate/ endDate), limites (maxCps/maxConcurrentCalls, além dos globais do Plan), parâmetros de pacing (pacingInitial/Min/Max, targetAbandonRate — consumidos pela fase Predictive Engine, só armazenados aqui), maxAttempts/ringTimeout, flags de gravação/AVMD/IA. daysOfWeek é Int[] ISO-8601 (1=segunda...7=domingo); startTime/ endTime são "HH:MM" string — sem tipo TIME nativo nesta fase (o scheduler de verdade avalia isso na timezone da campanha, é trabalho da fase Predictive Engine).
• leads (tenant-scoped, RLS): campaignId, phoneOriginal/ phoneNormalized (E.164), status (enum de 16 valores, secao 68), attemptCount/lastAttemptAt/nextAttemptAt/lastResult, customFields JSONB livre. Único por (campaignId, phoneNormalized) — o mesmo telefone pode existir em campanhas diferentes, nunca duas vezes na mesma.
• suppression_entries (tenant-scoped, RLS): lista de bloqueio (secao 71), único por (tenantId, phoneNormalized).

Máquina de estados da campanha (secao 64-66)

start:  DRAFT|READY|WAITING_SCHEDULE|PAUSED -> RUNNING
pause:  RUNNING -> PAUSED
drain:  RUNNING|PAUSED -> DRAINING   (não origina novas, deixa terminar as existentes)
stop:   qualquer não-terminal -> STOPPED

Cada transição valida o estado atual contra uma tabela de transições permitidas (ALLOWED_TRANSITIONS em campaigns.controller.ts) — tentar pause numa campanha DRAFT retorna 400, não silenciosamente ignora. Apagar (soft delete) é bloqueado enquanto RUNNING/DRAINING — precisa parar primeiro.

COMPLETED/ERROR não são alcançáveis via API nesta fase — são estados que só o motor de discagem (fase Predictive Engine) vai setar sozinho (leads esgotados / falha operacional).

packages/shared/src/phone.ts — normalização (secao 70)

Serviço dedicado, normalizePhone(raw, country = "BR"). Assinatura já preparada pra outros países (E.164 completo) — só o normalizador BR está implementado. Aceita com/sem "55" na frente, DDD 2 dígitos + 8 ou 9 dígitos de número; retorna null (nunca lança) pra entrada inválida, já que "número inválido" é um resultado esperado de uma importação de CSV.

Importação CSV (secao 69)

POST /campaigns/:id/leads/import, corpo { csv: string } — a versão desta fase recebe o CSV como texto no corpo JSON, não upload de arquivo multipart; o wizard visual (Upload → Preview → Mapeamento → Validação → Normalização → Duplicados → Importação) descrito na especificação é UI, fase Frontend. Formato mínimo: cabeçalho com colunas nome/telefone (aceita name/phone também).

Processamento em streaming/batches (csv-import.ts): parseia linha a linha (parser CSV mínimo, aceita campos entre aspas), valida telefone, detecta duplicado (dentro do próprio CSV E contra leads já existentes na campanha, num único Set carregado uma vez do banco — não uma query por linha), checa contra a lista de bloqueio do tenant, insere em lotes de 1000 (createMany). Lead que bate na lista de bloqueio é importado como DO_NOT_CALL, não descartado — fica registrado, só não é discado depois (quando o motor existir, ele só vai selecionar status = READY).

Retorna o resumo pedido pela secao 69: { total, valid, invalid, duplicates, imported, suppressed }.

Lista de bloqueio (secao 71)

CRUD simples (/suppression), tenant-scoped. A checagem obrigatória "antes de qualquer chamada" é responsabilidade de quem de fato origina (Predictive Engine) — aqui ela já é aplicada no momento da importação/criação de lead (marca como DO_NOT_CALL na hora, não pré-filtra o import).

Verificado ponta a ponta

POST /campaigns {queueId, trunkId, maxCps:2, daysOfWeek:[1..5], ...}
  -> pacingMin > pacingMax rejeitado (400)
  -> queueId inexistente no tenant rejeitado (400)

POST /suppression {phone: "11988887777"}
POST /campaigns/:id/leads/import (5 linhas: 1 invalida, 1 duplicada, 1 bloqueada)
  -> {"total":5,"valid":3,"invalid":1,"duplicates":1,"imported":3,"suppressed":1}
  -> lead bloqueado importado com status DO_NOT_CALL

pause numa campanha DRAFT -> 400 "Nao e' possivel "pause" ... em status DRAFT"
start -> RUNNING -> pause -> PAUSED -> drain -> DRAINING -> stop -> STOPPED
start numa campanha STOPPED -> 400 (transição não permitida)
delete numa campanha RUNNING -> 400 "Pare a campanha antes de apaga-la"

3a campanha (plano trial, max_campaigns=2) -> 403 Quota excedida

O que falta

• PredictiveDialerEngine inteiro (secao 72-86): dados em tempo real (agentes disponíveis/reservados/etc., secao 73), previsão de liberação via EWMA (secao 74-75), cálculo de pacing (secao 76), CPS distribuído via Redis (secao 77), reserva atômica de lead (FOR UPDATE SKIP LOCKED, secao 78), lock de campanha com TTL/ownership/renewal (secao 79), originate via bgapi (secao 80), state machine da chamada (secao 82), controle de abandono (secao 84), regras de retry (secao 86).
• Wizard visual de importação (upload de arquivo de verdade) — fase Frontend.
• Relatório de campanha (secao 160) — depende de CDR.
• Quota de leads por campanha — não existe campo max_leads no Plan (agente.md secao 56 não lista um); se vier a ser necessário, é uma adição pequena ao Plan + assertQuota.