feat: implement predictive dialing engine

- apps/dialer-worker: motor do discador preditivo completo
  - predictive-engine.ts: EWMA de answerProbability/avgTalkTimeSeconds/
    abandonRate, previsao de liberacao de agentes, calculo de quantas
    chamadas originar. Logica pura, 14 testes unitarios
  - cps-limiter.ts: token bucket via script Lua atomico no Redis (dois
    buckets independentes campanha+tronco, min() dos dois, seguro com
    multiplos workers)
  - lead-repository.ts: reserva atomica via FOR UPDATE SKIP LOCKED,
    recuperacao de reservas orfas apos queda de worker
  - campaign-lock.ts: lock distribuido por campanha (Redis SET NX PX +
    token de posse, renovacao/liberacao seguras via Lua)
  - schedule.ts: janela de horario da campanha (timezone real via
    Intl.DateTimeFormat, dias da semana), 6 testes unitarios
  - retry-rules.ts: motor de retentativa por causa de encerramento,
    configuravel por campanha, nunca infinito
  - simulation.ts + campaign-worker.ts (modo DIALER_SIMULATION): permite
    testar o motor inteiro sem tronco de operadora real
  - simulation-harness.ts: reproduz em tempo discreto e deterministico o
    cenario exato de aceite da secao 66 (20 agentes/10 CPS/30% atendimento/
    TMA 180s) — 6 testes validando CPS nunca excedido, concorrencia nunca
    excedida, pacing nao diverge
  - campaign-worker.ts: orquestra tudo contra Postgres/Redis/Asterisk reais

- docs/PREDICTIVE_DIALER.md: algoritmo documentado, incluindo dois bugs
  reais encontrados e corrigidos durante o teste do cenario de aceite
  (concorrencia nao contava chamadas em atendimento; pacing subia sem
  limite durante periodos ociosos, causando rajada maxima assim que um
  agente ficava livre) e limitacoes conhecidas (AMD e wrap-up automatico
  via eventos reais ainda pendentes, documentados sem esconder)

Testado ponta a ponta contra containers reais (Postgres/Redis/Asterisk):
campanha completa criada -> agente disponivel via API -> leads importados
-> campanha iniciada -> reserva atomica -> CPS respeitado -> simulacao de
NO_ANSWER (retry agendado) e ANSWERED (AGENT_CONNECTED, EWMA atualizada ao
vivo) -> parada sem derrubar chamadas em andamento.
This commit is contained in:
2026-08-27 15:24:31 -03:00
parent 167776ff63
commit 66cc2058fd
24 changed files with 1776 additions and 11 deletions

47
TODO.md
View File

@@ -182,17 +182,42 @@ mestre original (`agente.md`, seções 90-93).
- [x] Lista de supressão (DNC): CRUD + import CSV + remoção sempre exige
motivo e é auditada — checagem obrigatória pré-originação
(isSuppressed) implementada e usada pelo dialer-worker (ver abaixo)
- [ ] CPS limiter (token bucket, coordenado via Redis, multi-worker)
- [ ] Reserva concorrente de leads (FOR UPDATE SKIP LOCKED + timeout)
- [ ] Idempotência de originação (attempt_id/call_id/uniqueid/linkedid, state machine)
- [ ] PredictiveDialerEngine (EWMA, pacing, previsão de liberação de agentes)
- [ ] Controle de abandono (pacing cai / suspende originação)
- [ ] AMD opcional por campanha
- [ ] Wrap-up time
- [ ] Retry engine (regras por causa, limite de tentativas)
- [ ] Horário de campanha (timezone, dias/horários, WAITING_SCHEDULE)
- [ ] Lock distribuído por campanha (Redis)
- [ ] docs/PREDICTIVE_DIALER.md
- [x] CPS limiter (token bucket via Lua atômico no Redis, dois buckets
independentes campanha+tronco, min() dos dois — multi-worker seguro)
- [x] Reserva concorrente de leads (SQL único com FOR UPDATE SKIP LOCKED —
atômico; timeout de 90s libera reservas órfãs após queda de worker)
- [x] Idempotência de originação (DialAttempt.id é o attempt_id de negócio,
nunca reoriginado; UNIQUEID nunca usado como PK — seção 97)
- [x] PredictiveDialerEngine (EWMA de answerProbability/avgTalkTimeSeconds/
abandonRate, previsão de liberação de agentes via TMA histórico +
tempo decorrido, ajuste de pacing) — apps/dialer-worker/src/
predictive-engine.ts, 100% lógica pura testável, 14 testes unitários
- [x] Controle de abandono (pacing cai imediatamente acima da meta; nunca
sobe "porque nada de ruim aconteceu" durante período ocioso — bug
real encontrado e corrigido durante o teste do cenário da seção 66)
- [ ] AMD opcional por campanha — campo existe no schema/DTO, detecção real
(app AMD do Asterisk) ainda não integrada à originação (ver
docs/PREDICTIVE_DIALER.md seção 7)
- [ ] Wrap-up time — campo existe, mas transição automática do agente para
WRAP_UP via eventos reais (AgentComplete) não implementada; hoje só
funciona no modo simulação e nas transições manuais da Fase 5 (ver
docs/PREDICTIVE_DIALER.md seção 7)
- [x] Retry engine (regras por causa configuráveis por campanha via JSON,
default seção 79, nunca rediscagem infinita via maxAttempts) —
testado ponta a ponta (NO_ANSWER agendou retry corretamente)
- [x] Horário de campanha (timezone via Intl.DateTimeFormat, dias da
semana, HH:MM, WAITING_SCHEDULE computado) — 6 testes unitários
cobrindo timezone, dias, startDate/endDate
- [x] Lock distribuído por campanha (Redis SET NX PX + token de posse +
renovação/liberação seguras via Lua — nunca libera lock de outro dono)
- [x] docs/PREDICTIVE_DIALER.md — algoritmo, decisões, bugs encontrados e
corrigidos durante o teste, limitações conhecidas documentadas
**Testado ponta a ponta contra containers reais** (Postgres/Redis/Asterisk):
campanha completa criada → agente logado/disponível via API real → leads
importados → campanha iniciada → reserva atômica → CPS respeitado →
simulação de NO_ANSWER (retry agendado) e ANSWERED (AGENT_CONNECTED, EWMA
atualizada ao vivo no Redis) → parada sem derrubar chamadas em andamento.
## Fase 7 — CDR, métricas e relatórios
- [ ] Modelo consolidado de chamadas (CDR+CEL+AMI+queue_log)