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/main.ts
+++ b/apps/predictive-dialer/src/main.ts
@@ -0,0 +1,134 @@
+import { randomUUID } from "node:crypto";
+import Redis from "ioredis";
+import { getPrismaClient, withTenantContext } from "@b2bcall/database";
+import { FreeSwitchTelephonyProvider } from "@b2bcall/telephony";
+import { createLogger } from "@b2bcall/shared";
+import { acquireCampaignLock, renewCampaignLock, releaseCampaignLock } from "./redis-primitives";
+import { tickCampaign, type TickDeps } from "./tick";
+import { startEventListener } from "./event-listener";
+
+const logger = createLogger("b2bcall-predictive-dialer");
+
+const TICK_INTERVAL_MS = 2000;
+const LOCK_TTL_MS = 10_000;
+
+function requireEnv(name: string): string {
+  const value = process.env[name];
+  if (!value) throw new Error(`${name} nao definido no ambiente`);
+  return value;
+}
+
+/**
+ * Real Outbound Safety (agente.md secao 186): as DUAS condições precisam
+ * estar explicitamente ligadas — nunca ativado automaticamente. Lido uma
+ * vez no boot (não é algo que deveria mudar em runtime sem reiniciar o
+ * worker).
+ */
+function readOutboundSafetyFlags(): { dialerSimulation: boolean; allowRealOutboundCalls: boolean } {
+  const dialerSimulation = (process.env.DIALER_SIMULATION ?? "true") !== "false";
+  const allowRealOutboundCalls = process.env.ALLOW_REAL_OUTBOUND_CALLS === "true";
+  if (dialerSimulation) {
+    logger.info("DIALER_SIMULATION=true — nenhuma chamada PSTN real sera originada");
+  } else if (!allowRealOutboundCalls) {
+    logger.warn(
+      "DIALER_SIMULATION=false mas ALLOW_REAL_OUTBOUND_CALLS != true — chamadas reais continuam bloqueadas (secao 186)",
+    );
+  } else {
+    logger.warn("CHAMADAS PSTN REAIS HABILITADAS (DIALER_SIMULATION=false + ALLOW_REAL_OUTBOUND_CALLS=true)");
+  }
+  return { dialerSimulation, allowRealOutboundCalls };
+}
+
+async function main(): Promise<void> {
+  const { dialerSimulation, allowRealOutboundCalls } = readOutboundSafetyFlags();
+  const redis = new Redis(requireEnv("REDIS_URL"));
+  redis.on("error", (err) => logger.error("erro na conexao Redis", { error: String(err) }));
+
+  const provider = new FreeSwitchTelephonyProvider({
+    host: requireEnv("ESL_HOST"),
+    port: Number(process.env.ESL_PORT ?? 8021),
+    password: requireEnv("ESL_PASSWORD"),
+    logger: {
+      debug: () => {},
+      info: (msg) => logger.debug(msg),
+      error: (msg, data) => logger.error(msg, { detail: data }),
+    },
+  });
+  provider.connect();
+  await provider.waitUntilConnected(10_000);
+
+  const eventSubscriber = startEventListener(requireEnv("REDIS_URL"));
+
+  const workerId = randomUUID();
+  const deps: TickDeps = { redis, provider, dialerSimulation, allowRealOutboundCalls };
+
+  let stopped = false;
+  const tick = async () => {
+    if (stopped) return;
+    try {
+      await runTick(deps, workerId);
+    } catch (err) {
+      logger.error("falha no tick", { error: String(err) });
+    }
+    if (!stopped) setTimeout(tick, TICK_INTERVAL_MS);
+  };
+  setTimeout(tick, TICK_INTERVAL_MS);
+
+  logger.info("b2bcall-predictive-dialer iniciado", { workerId, tickIntervalMs: TICK_INTERVAL_MS });
+
+  const shutdown = async () => {
+    stopped = true;
+    logger.info("encerrando b2bcall-predictive-dialer");
+    await provider.disconnect();
+    redis.disconnect();
+    eventSubscriber.disconnect();
+    process.exit(0);
+  };
+  process.on("SIGTERM", shutdown);
+  process.on("SIGINT", shutdown);
+}
+
+/**
+ * Um tick = uma passada por todos os tenants ativos, campanhas RUNNING (ou
+ * WAITING_SCHEDULE, que pode voltar a RUNNING dentro da janela — ver
+ * tick.ts). Lock por campanha (secao 79) garante que, mesmo rodando mais
+ * de um worker deste serviço, só um processa uma dada campanha por vez —
+ * renovado durante o processamento, liberado com compare-and-delete no
+ * final (nunca libera o lock de outro dono).
+ */
+async function runTick(deps: TickDeps, workerId: string): Promise<void> {
+  const prisma = getPrismaClient();
+  const tenants = await prisma.tenant.findMany({ where: { status: "ACTIVE" } });
+
+  for (const tenant of tenants) {
+    const campaigns = await withTenantContext(prisma, tenant.id, (tx) =>
+      tx.campaign.findMany({
+        where: { tenantId: tenant.id, deletedAt: null, status: { in: ["RUNNING", "WAITING_SCHEDULE"] } },
+      }),
+    );
+
+    for (const campaign of campaigns) {
+      const ownerToken = `${workerId}:${randomUUID()}`;
+      const locked = await acquireCampaignLock(deps.redis, campaign.id, ownerToken, LOCK_TTL_MS);
+      if (!locked) continue;
+
+      const renewTimer = setInterval(() => {
+        renewCampaignLock(deps.redis, campaign.id, ownerToken, LOCK_TTL_MS).catch(() => undefined);
+      }, LOCK_TTL_MS / 2);
+
+      try {
+        await tickCampaign(deps, tenant, campaign);
+      } catch (err) {
+        logger.error("falha no tick da campanha", { error: String(err), campaignId: campaign.id });
+      } finally {
+        clearInterval(renewTimer);
+        await releaseCampaignLock(deps.redis, campaign.id, ownerToken);
+      }
+    }
+  }
+}
+
+main().catch((err) => {
+  logger.error("falha fatal ao iniciar b2bcall-predictive-dialer", { error: String(err) });
+  process.exit(1);
+});