feat(dialer): CPS Limiter + Predictive Dialer Engine

Fecha agente.md secao 72-86 (motor preditivo) e 77-79 (CPS distribuido, reserva de leads, lock de campanha). Uma campanha RUNNING agora origina chamadas sozinha, respeitando capacidade de agentes, CPS hierarquico e taxa de abandono — sem intervencao manual. Deliberadamente fora do escopo (agente.md secao 72: "nao e' so' `for lead -> originate`"): mod_avmd (opcional), callbacks agendados, disposicoes de agente — ficam pra fase CDR. ## Novo servico apps/predictive-dialer Mesmo padrao arquitetural de fs-events/fs-config: Node standalone em Docker, ESL propria, tick a cada 2s sobre tenants ativos x campanhas RUNNING/WAITING_SCHEDULE. - Lock de campanha (dialer:campaign:{id}, secao 79): TTL/ownership/ renewal/safe-release via Lua compare-and-delete. - CPS distribuido (secao 77, 62): token bucket janela 1s, hierarquia GLOBAL/TENANT/TRUNK/CAMPAIGN numa unica chamada Lua atomica — nivel esgotado bloqueia todos SEM incremento parcial dos que passariam. - Reserva atomica de leads (secao 78): FOR UPDATE SKIP LOCKED dentro da mesma transacao withTenantContext. - CallAttempt/CampaignStats (schema novo): state machine da chamada (secao 82) + EWMA (secao 75) de answer_probability/average_answer_delay/ average_talk_time/abandon_rate por campanha. - Capacidade em tempo real + pacing (secao 73-76, 84-85): conta agentes por estado via Tier->Agent.state, previsao de liberacao (horizonte unico de 15s, simplificacao documentada dos 4 buckets da especificacao), controle de abandono reduz pacing progressivamente, nunca origina sem capacidade prevista. ## Modo simulacao (secao 185-186) DIALER_SIMULATION=true (default, ja estava no .env desde o inicio da sessao) sorteia ANSWER/BUSY/NO_ANSWER/FAILED em software, sem PSTN real. So' quando ANSWERED e' que uma chamada sintetica (null/dummy, sem PSTN) entra na fila real via mod_callcenter de verdade — escolha deliberada pra maximizar codigo real exercitado em vez de simular tudo em memoria. Os identificadores da secao 81 (b2bcall_tenant_id/call_id/attempt_id/ campaign_id/lead_id) vao como channel variables nessa perna, entregando tenantId real no WebSocket sem fan-out. Real Outbound Safety (secao 186): as duas flags checadas no boot, nunca ativadas automaticamente — caminho PSTN real implementado mas nunca exercitado (sem trunk/operadora real neste laboratorio). ## Dois bugs reais achados e corrigidos testando esta fase - Perna sintetica (null/dummy) nao tem midia do outro lado — nunca desligava sozinha depois de bridgear com um agente. Corrigido com hangup agendado via uuid_kill no talk_time simulado. - Corrida entre queue:sync e tier:sync (dois canais Redis independentes, sem ordem garantida): atribuir tier logo depois de criar a fila podia rodar tier add antes do queue reload terminar ("-ERR Queue not found!", erro real, diferente do ja conhecido "already exist"). Corrigido com retry curto (ate 3 tentativas) em agent-sync.ts::addTierWithRetry. ## GET /campaigns/:id/stats Secao 227.7 "visualizar pacing" — CampaignStats + agentes por estado + calls em andamento, sem esperar a fase Frontend. Verificado ponta a ponta: campanha RUNNING originando 3 tentativas por tick, outcomes simulados corretos com retry agendado (BUSY 15min/ NO_ANSWER 60min/FAILED 30min), uma tentativa ANSWERED completando o ciclo real inteiro (fila -> agente -> bridge -> hangup -> EWMA atualizada), stop nao derruba chamada ativa (secao 66), calls_answered=3 confirmado no `queue list` do FreeSWITCH. CPS limiter e lock de campanha testados isoladamente (hierarquia sem incremento parcial, ownership nunca roubado). typecheck do workspace inteiro limpo. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01X1HxY46WGU4G1zmVDNKcWw
2026-08-28 13:31:31 -03:00
parent 7b62ad3d82
commit cb6d343b2e
29 changed files with 1851 additions and 28 deletions
--- a/apps/predictive-dialer/src/call-attempt.ts
+++ b/apps/predictive-dialer/src/call-attempt.ts
@@ -0,0 +1,137 @@
+import { randomUUID } from "node:crypto";
+import type { CallAttempt, CallAttemptStatus, Prisma } from "@b2bcall/database";
+import { computeNextAttemptAt } from "./retry-rules";
+import { ewmaUpdate } from "./ewma";
+
+export interface CreateAttemptParams {
+  tenantId: string;
+  campaignId: string;
+  leadId: string;
+  simulated: boolean;
+}
+
+export async function createCallAttempt(
+  tx: Prisma.TransactionClient,
+  params: CreateAttemptParams,
+): Promise<CallAttempt> {
+  return tx.callAttempt.create({
+    data: {
+      tenantId: params.tenantId,
+      campaignId: params.campaignId,
+      leadId: params.leadId,
+      simulated: params.simulated,
+      status: "RESERVED",
+    },
+  });
+}
+
+export async function setAttemptStatus(
+  tx: Prisma.TransactionClient,
+  attemptId: string,
+  status: CallAttemptStatus,
+  extra: Partial<Pick<CallAttempt, "originationUuid" | "ringingAt" | "answeredAt" | "bridgedAt" | "agentId">> = {},
+): Promise<void> {
+  await tx.callAttempt.update({ where: { id: attemptId }, data: { status, ...extra } });
+}
+
+export function newOriginationUuid(): string {
+  return randomUUID();
+}
+
+export type TerminalOutcome = "COMPLETED" | "BUSY" | "NO_ANSWER" | "FAILED" | "ABANDONED";
+
+export interface CompleteAttemptParams {
+  attemptId: string;
+  tenantId: string;
+  campaignId: string;
+  leadId: string;
+  outcome: TerminalOutcome;
+  reachedQueue: boolean;
+  answerDelaySeconds?: number;
+  talkTimeSeconds?: number;
+  hangupCause?: string;
+  agentId?: string;
+}
+
+const OUTCOME_TO_STATUS: Record<TerminalOutcome, CallAttemptStatus> = {
+  COMPLETED: "COMPLETED",
+  BUSY: "BUSY",
+  NO_ANSWER: "NO_ANSWER",
+  FAILED: "FAILED",
+  ABANDONED: "ABANDONED",
+};
+
+/**
+ * Fecha uma tentativa: grava o CallAttempt terminal, atualiza a EWMA da
+ * campanha (agente.md secao 75) e decide o próximo passo do Lead — nunca
+ * retry infinito (secao 86): `attemptCount >= maxAttempts` vira
+ * MAX_ATTEMPTS, terminal, nunca mais selecionado. Leads que ainda vão
+ * tentar de novo voltam pra READY (não BUSY/NO_ANSWER/etc como status
+ * consultável — a razão especifica fica em `lastResult`; READY é o único
+ * jeito da query de reserva achar o lead de novo depois de
+ * `nextAttemptAt`).
+ */
+export async function completeAttempt(
+  tx: Prisma.TransactionClient,
+  params: CompleteAttemptParams,
+  campaignMaxAttempts: number,
+): Promise<void> {
+  const now = new Date();
+
+  await tx.callAttempt.update({
+    where: { id: params.attemptId },
+    data: {
+      status: OUTCOME_TO_STATUS[params.outcome],
+      talkTimeSeconds: params.talkTimeSeconds,
+      hangupCause: params.hangupCause,
+      agentId: params.agentId,
+      endedAt: now,
+    },
+  });
+
+  const stats = await tx.campaignStats.findUniqueOrThrow({ where: { campaignId: params.campaignId } });
+  const wasAnswered = params.outcome === "COMPLETED" || params.outcome === "ABANDONED";
+  const data: Prisma.CampaignStatsUpdateInput = {
+    answerProbability: ewmaUpdate(stats.answerProbability, wasAnswered ? 1 : 0),
+  };
+  if (wasAnswered && params.answerDelaySeconds != null) {
+    data.averageAnswerDelay = ewmaUpdate(stats.averageAnswerDelay, params.answerDelaySeconds);
+  }
+  if (params.talkTimeSeconds != null) {
+    data.averageTalkTime = ewmaUpdate(stats.averageTalkTime, params.talkTimeSeconds);
+  }
+  if (params.reachedQueue) {
+    data.abandonRate = ewmaUpdate(stats.abandonRate, params.outcome === "ABANDONED" ? 1 : 0);
+  }
+  await tx.campaignStats.update({ where: { campaignId: params.campaignId }, data });
+
+  const lead = await tx.lead.findUniqueOrThrow({ where: { id: params.leadId } });
+  const attemptCount = lead.attemptCount + 1;
+
+  if (params.outcome === "COMPLETED") {
+    await tx.lead.update({
+      where: { id: params.leadId },
+      data: { status: "COMPLETED", attemptCount, lastAttemptAt: now, lastResult: params.outcome },
+    });
+    return;
+  }
+
+  if (attemptCount >= campaignMaxAttempts) {
+    await tx.lead.update({
+      where: { id: params.leadId },
+      data: { status: "MAX_ATTEMPTS", attemptCount, lastAttemptAt: now, lastResult: params.outcome },
+    });
+    return;
+  }
+
+  await tx.lead.update({
+    where: { id: params.leadId },
+    data: {
+      status: "READY",
+      attemptCount,
+      lastAttemptAt: now,
+      lastResult: params.outcome,
+      nextAttemptAt: computeNextAttemptAt(params.outcome, now),
+    },
+  });
+}