B2BCall-dialer/docs/PREDICTIVE_DIALER.md

# CPS Limiter / Predictive Dialer Engine

Agente.md secao 72-86 (motor preditivo) e 77-79 (CPS distribuído, reserva
de leads, lock de campanha). Fecha o discador de verdade — depois desta
fase, uma campanha `RUNNING` origina chamadas sozinha, respeitando
capacidade de agentes, CPS hierárquico e taxa de abandono, sem intervenção
manual.

Deliberadamente **não** implementado nesta fase (agente.md secao 72: "não é
só `for lead -> originate`"): mod_avmd (secao 87, opcional), callbacks
agendados (secao 88), disposições de agente (secao 89) — ficam pra fase
CDR, que é onde o conceito de "resultado de uma chamada" ganha uma tabela
própria de verdade.

## Novo serviço: `apps/predictive-dialer`

Mesmo padrão arquitetural de `apps/freeswitch-events`/`apps/freeswitch-
config`: processo Node standalone em Docker, conexão ESL própria, `tsx`
direto (sem `dist/`), tenant-scoped via `withTenantContext` em toda query.
Um tick a cada 2s: para cada tenant ativo, para cada campanha `RUNNING`/
`WAITING_SCHEDULE`, tenta processar.

## Lock de campanha (secao 79)

`dialer:campaign:{id}` no Redis — `SET NX PX` pra adquirir, renovado a
cada metade do TTL (10s) enquanto o tick daquela campanha está em
andamento, liberado com compare-and-delete (só quem detém o `ownerToken`
consegue renovar/liberar — testado isoladamente: outro dono nunca rouba
nem renova o lock de quem já tem). Garante que, mesmo rodando mais de uma
réplica deste serviço, só um worker processa uma dada campanha por vez.

## CPS distribuído (secao 77, 62)

Token bucket por janela fixa de 1s (`INCR` + `PEXPIRE`, script Lua
atômico) — não é sleep(), múltiplos workers batem no mesmo Redis. A
hierarquia (`GLOBAL → TENANT → TRUNK → CAMPAIGN`, node omitido — só existe
um node FreeSWITCH neste deploy) é uma única chamada Lua com todas as
chaves aplicáveis: só incrementa TODAS se TODAS tiverem espaço — testado
isoladamente que um nível esgotado bloqueia mesmo com os outros níveis
tendo espaço de sobra, **sem incrementar parcialmente** os que passariam
(a chave da campanha ficou em 1, não 2, na segunda tentativa bloqueada
pelo tenant).

## Reserva atômica de leads (secao 78)

`SELECT ... FOR UPDATE SKIP LOCKED` (raw SQL dentro da mesma transação
`withTenantContext`, RLS + lock de linha coexistindo). `SKIP LOCKED` evita
dois workers reservando o mesmo lead — quem chegar depois pula pro
próximo, nunca espera. `READY`/`NEW` → `RESERVED` no mesmo `UPDATE` dentro
da transação.

## Dados em tempo real e pacing (secao 73-76)

`pacing.ts::computeCapacity` conta agentes por estado (via `Tier` →
`Agent.state`, mesma fonte de verdade da fase Agents/Realtime Monitoring)
e estima quantos ficam disponíveis nos próximos 15s — a partir de
`stateUpdatedAt` + `averageTalkTime`/`wrapUpTime`. **Simplificação
deliberada**: a especificação pede 4 buckets de previsão (5/10/15/20s);
aqui é um único horizonte de 15s. Refinar pros 4 buckets fica pra quando
houver dado real suficiente pra validar se faz diferença prática.

`pacing.ts::decidePacing` aplica o cálculo conceitual da secao 76
(`expected_agent_capacity = available + predicted`, `calls_to_originate =
round(expected_agent_capacity * pacing_factor / answer_probability) -
calls_in_flight`) e o controle de abandono da secao 84: `abandon_rate`
acima do alvo reduz o pacing; acima de 2x força o mínimo; acima de 3x
suspende originações nesse tick (nunca desliga a campanha sozinha, só pula
o tick). Nunca origina sem capacidade prevista (secao 85: `if
(expectedAgentCapacity <= 0) return 0`).

## EWMA (secao 75)

`ewma.ts`, alpha=0.25 — `answer_probability`/`average_answer_delay`/
`average_talk_time`/`abandon_rate` persistidos em `CampaignStats`,
atualizados a cada tentativa concluída (`call-attempt.ts::completeAttempt`).
Sem Machine Learning (secao 74: "preferir algoritmo estatístico
determinístico e explicável") — é só a fórmula de suavização exponencial,
nada de modelo treinado.

## Modo simulação (secao 185-186) — como funciona de verdade

`DIALER_SIMULATION=true` por padrão (já estava no `.env` desde o início da
sessão). Nesse modo, **nenhuma chamada PSTN real acontece**: o desfecho
("o cliente atendeu?") é sorteado inteiramente em software
(`simulation.ts`, 40% ANSWERED / 15% BUSY / 35% NO_ANSWER / 10% FAILED,
com delay e talk time aleatórios) — o FreeSWITCH nem é acionado pra
BUSY/NO_ANSWER/FAILED.

Quando o sorteio dá **ANSWERED**, aí sim uma chamada real entra no
FreeSWITCH — mas sintética (`null/dummy`, sem PSTN nenhum envolvido),
direto pra `&callcenter(fila@domínio)`. Escolha deliberada: a partir desse
ponto, quem decide o resto (oferecer pro agente, bridgear, abandono por
timeout) é o **mod_callcenter real**, o mesmo já testado e verificado nas
fases Queues/Agents/Realtime Monitoring — maximiza código real exercitado
em vez de simular tudo em memória. Os identificadores da secao 81
(`b2bcall_tenant_id`/`b2bcall_call_id`/`b2bcall_attempt_id`/
`b2bcall_campaign_id`/`b2bcall_lead_id`) vão como channel variables nessa
perna sintética — os eventos dela chegam com `tenantId` já resolvido no
WebSocket (fase Realtime Monitoring), sem precisar do fan-out usado por
outros eventos de callcenter.

**Achado real durante o teste desta fase**: uma perna `null/dummy` não tem
mídia do outro lado — nada faz ela desligar sozinha depois de bridgear com
um agente (diferente de uma ligação de verdade, onde o cliente desliga).
Sem tratar isso, o canal ficava ativo pra sempre. Corrigido: depois de
originar a perna sintética, um `setTimeout` chama `uuid_kill` no
`talk_time` simulado (matando um canal que já terminou sozinho — ex.:
abandonado na fila — não dá erro, sem efeito).

`event-listener.ts` assina o mesmo canal Redis `b2bcall:events` que a fase
Realtime Monitoring já usa, correlaciona pelo `origination_uuid`
(registry em memória, `queued-attempts-registry.ts`) e fecha o
`CallAttempt` quando `CALL_BRIDGED`/`QUEUE_MEMBER_LEFT`/`CALL_ENDED`
chegam — `AGENT_OFFERED_CALL` só anota qual agente pegou, sem fechar nada
ainda.

## Real Outbound Safety (secao 186)

`originateRealPstnLeg` (`originate.ts`) existe, arquiteturalmente completo
(Sofia Gateway real, `sofia/gateway/<trunk>/<numero>`), mas só é chamado
quando **as duas** condições da secao 186 são verdadeiras
(`DIALER_SIMULATION=false` E `ALLOW_REAL_OUTBOUND_CALLS=true`) — nunca
ativado automaticamente, checado uma vez no boot do worker
(`main.ts::readOutboundSafetyFlags`, log de warning claro em cada estado).
**Nunca exercitado nesta sessão** — não existe trunk/operadora real
disponível neste laboratório. O caminho de `answer_delay` real (via evento
`CALL_ANSWERED`, distinto do delay pré-sorteado do modo simulação) também
está implementado mas não testado pelo mesmo motivo.

## Achado real: corrida entre `queue:sync` e `tier:sync`

Descoberto testando esta fase: criar uma fila e atribuir um tier logo em
seguida (fluxo normal de setup de uma campanha) pode fazer `tier add`
rodar **antes** do `queue reload` da fila terminar no FreeSWITCH — erro
real (`-ERR Queue not found!`), diferente do já conhecido "already exist"
(esse sim inofensivo). Como `queues:sync` e `tiers:sync` são dois canais
Redis independentes sem ordem garantida entre si, o login do agente (que
já resincroniza tiers, ver docs/AGENTS.md) não bastava — os dois disparos
corriam antes do reload terminar. Corrigido com retry curto (até 3
tentativas, backoff de 500ms/1s/1.5s) especificamente pra esse erro, em
`apps/freeswitch-config/src/agent-sync.ts::addTierWithRetry`.

## `GET /campaigns/:id/stats` (secao 227.7 "visualizar pacing")

Expõe `CampaignStats` (atualizado a cada tick) + contagem de agentes por
estado + chamadas em andamento, calculado na hora. Suficiente pro
acceptance criteria "visualizar pacing" sem esperar a fase Frontend.

## Verificado ponta a ponta

```
Campanha RUNNING, 1 agente disponível, 3 leads:
  tick -> originando 3 tentativas (pacing_factor=1.05, answer_probability=0.4)
  Lead 1: FAILED (simulado) -> retry em 30min
  Lead 2: NO_ANSWER (simulado) -> retry em 60min
  Lead 3: ANSWERED (simulado) -> entra na fila real -> AGENT_OFFERED_CALL
    -> CALL_BRIDGED (agente conectado, evento real) -> hangup agendado
    -> CALL_ENDED -> CallAttempt COMPLETED, EWMA atualizada

Corrida queue/tier: "tier add" falhando com "Queue not found" -> retry
  automático -> "tier sincronizado" -> tier list confirma o agente na fila

CPS limiter isolado: maxPerSecond=2, 4 tentativas -> true,true,false,false
CPS hierarquia: nível tenant esgotado bloqueia mesmo com campanha livre,
  SEM incremento parcial (contador da campanha ficou em 1, não 2)
Lock de campanha isolado: dono B nunca rouba nem renova lock do dono A;
  dono C adquire normalmente depois do release do dono A

stop numa campanha com chamada ativa -> não derruba a chamada em curso
  (secao 66), só para novas originações — confirmado observando o canal
  continuar ativo até seu próprio hangup agendado

queue list mostra calls_answered=3 ao final dos testes, confirmando 3
conexões reais de agente via o pipeline completo
```

typecheck do workspace inteiro limpo.

## O que falta

- Previsão de 4 buckets (5/10/15/20s, secao 74) — simplificado pra um
  único horizonte de 15s.
- `mod_avmd` (secao 87), callbacks agendados (secao 88), disposições de
  agente (secao 89) — fora do escopo desta fase.
- Caminho PSTN real (secao 80-83, 186) — implementado, nunca exercitado
  (sem trunk real disponível).
- CPS a nível de trunk (`Trunk.maxCps`) — campo existe no modelo desde a
  fase Trunks, mas só é aplicado quando o caminho PSTN real rodar (a perna
  simulada não passa por um trunk de verdade, não faz sentido contar CPS
  de trunk pra ela).
- Memória do worker ficou em ~266MB depois de alguns ciclos de teste
  (contra ~30-55MB de fs-events/fs-config) — dentro do orçamento da VM,
  mas vale reavaliar se crescer mais rodando por mais tempo/mais
  campanhas simultâneas.
- Relatório de campanha (secao 160), TME/TMA/Service Level/Abandon Rate
  agregados de verdade — dependem de CDR (próxima fase da ordem do
  agente.md secao 232).