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
25 KiB
TODO — B2BCall
PHASE 01 — Infrastructure
- Diagnóstico do servidor (Debian 13, 2 vCPU, ~1.9GB RAM, 26GB disco livre)
- Docker + Docker Compose instalados
- Estrutura de monorepo criada (apps/, packages/, infrastructure/, scripts/, docs/)
- PostgreSQL 18 (docker-compose, porta 127.0.0.1:5432)
- Redis 7 (docker-compose, porta 127.0.0.1:6379)
- Secrets gerados em
.env(POSTGRES_PASSWORD, REDIS_PASSWORD, JWT_SECRET, JWT_REFRESH_SECRET, ENCRYPTION_KEY, ESL_PASSWORD) FREESWITCH_PATconfigurado em.env(não commitado)- FreeSWITCH (imagem própria via pacotes SignalWire, não compilada da fonte — ver docs/FREESWITCH.md; rodando, saudável, ~44MB RAM, senha ESL customizada, nenhuma porta exposta ao host)
- nginx (reverse proxy)
PHASE 05 — FreeSWITCH (agente.md secao 232)
- Imagem própria (
infrastructure/freeswitch/), pacotes SignalWire (PAT via BuildKit secret, nunca na imagem final — verificado comdocker history) - Módulos mínimos carregados: sofia, event_socket, commands, dptools, callcenter, avmd, curl, local_stream, etc. (mod_xml_curl instalado mas desativado até existir b2bcall-fs-config)
- Senha do Event Socket trocada da padrão via entrypoint runtime (nunca fica na imagem); porta 8021 não publicada no host
- docs/FREESWITCH.md, docs/NETWORK_ARCHITECTURE.md (decisão de network_mode adiada pra quando existir tronco SIP real)
- Diretório/dialplan ainda são os estáticos da config vanilla (ramais de teste 1000-1019, senhas fracas) — substituir por mod_xml_curl na fase Extensions/Trunks/Dialplan
PHASE 06 — Event Socket (agente.md secao 21-25, 195)
packages/telephony: interfaceTelephonyProvider+FreeSwitchTelephonyProvider(sobre a libesl, reconexão com backoff já embutida na lib)normalizeEslEvent(): eventos ESL crus → vocabulário interno (secao 24)apps/freeswitch-events(b2bcall-fs-events): conexão ESL permanente, resubscreve a cada reconexão, publica eventos normalizados no canal Redisb2bcall:events- Achado: FreeSWITCH 1.11 aplica ACL implícita (só loopback) sem
apply-inbound-acl— bloqueava conexão de outro container mesmo com senha certa. Corrigido com ACL própria cobrindo loopback + rede Docker. - Testado ponta a ponta com chamada loopback local: CALL_CREATED → CALL_ANSWERED → CALL_ENDED corretos no Redis
- Reconciliação pós-reconexão (calls/agents/queues/registrations/gateways) — não é possível ainda, sem essas tabelas persistidas
PHASE 07 — XML Curl (agente.md secao 26)
apps/freeswitch-config(b2bcall-fs-config): responde ao protocolo XML Curl do FreeSWITCH (POST form-encoded → XML), containerizadomod_xml_curlreativado, binding restrito adirectory|dialplan(nãoconfiguration— evita chamadas HTTP desnecessárias no boot)- Por enquanto sempre "not found" (sem tabela extensions/dialplan ainda);
verificado que a config estática vanilla continua funcionando como
fallback (
user/8888→ SUBSCRIBER_ABSENT via fs-config,user/1000→ USER_NOT_REGISTERED via config estática — achou o usuário) - Sem autenticação HTTP ainda — ok enquanto só responde "not found";
adicionar
gateway-credentialsantes de servir directory/dialplan reais
PHASE 02 — SaaS Core
- Monorepo Node.js/TypeScript (pnpm workspaces, tsconfig base)
- Node 22 LTS + pnpm instalados no host
packages/database(Prisma 7 + driver adapterpg, migration inicial)packages/types(TenantStatus, AgentState),packages/shared- Tabela
tenantscriada via migration (seção 29 do agente.md)
PHASE 03 — Tenant Isolation
- Tabelas
users+tenant_memberships(tenant-scoped) - RLS (
ENABLE/FORCE ROW LEVEL SECURITY+ policy) emtenant_memberships - Tenant context via
set_config('app.current_tenant_id', ..., true)(transaction-local) - Helper
withTenantContext()empackages/database - Role de banco separado para runtime (
b2bcall_app, sem SUPERUSER/BYPASSRLS) — achado crítico: o role padrão do Docker Postgres é SUPERUSER e SEMPRE ignora RLS, até com FORCE. Verdocs/TENANT_ISOLATION.md. - Teste automatizado de isolamento (
pnpm --filter @b2bcall/database run test:isolation)
PHASE 04 — Authentication / RBAC
packages/auth: hash Argon2id (@node-rs/argon2), JWT access token (jose), refresh token opaco com rotation- Tabelas
roles,permissions,role_permissions,user_roles,sessions,audit_logs login()/refreshSession()/logout()/listUserTenants()/setActiveTenant()userHasPermission()(RBAC com scope PLATFORM/TENANT)- Seed: catálogo de permissions + roles de sistema + Platform Super Admin inicial
(senha em
FIRST_LOGIN.txt, fora do Git,mustChangePassword=true) - Teste automatizado (
pnpm --filter @b2bcall/auth run test:auth) apps/api(NestJS + Fastify): endpoints de auth, JwtAuthGuard, DomainExceptionFilter, rate limit de login via Redis (5/min por IP e por e-mail), helmet/cors, health checks — testado ponta a ponta com curl (login, refresh rotation, logout, RBAC, 401/403/429)- Password reset por e-mail — depende de SMTP configurado
PHASE 08 — Extensions (agente.md secao 39-40, 178)
- Tabela
extensions(tenant-scoped, RLS) — number, sip_password_enc, caller_id, context, sofia_profile, codecs, max_registrations packages/shared/src/crypto.ts: AES-256-GCM (senha SIP cifrada em repouso),generateStrongPassword(),maskSecret()apps/api/src/extensions: CRUD (POST/GET/GET:id/DELETE), RBAC via novoPermissionGuardgenérico (@RequirePermission), tenant só do JWT- Senha SIP só aparece em texto puro na resposta do POST, nunca depois (destructuring explícito, não spread — evita vazamento por acidente)
b2bcall-fs-configresolve directory real: Tenant.telephonyDomain → Extension.number, decifra a senha, monta XML com dial-stringTenant.telephonyDomainfixo (b2bcall.local) via patch novars.xmldo FreeSWITCH — antes usava o IP dinâmico do container, instável- HTTP Basic auth entre FreeSWITCH e fs-config (
gateway-credentials, timingSafeEqual) — adicionada nesta mesma fase, não deixada pendente - Testado ponta a ponta: criar ramal →
user/1500dá USER_NOT_REGISTERED (achou, sem telefone) → deletar → volta a SUBSCRIBER_ABSENT - Achado:
PermissionGuardinjetandoReflectorvia construtor davaundefinedem runtime rodando viatsx/esbuild (emissão de metadata de tipo não é 100% confiável cross-file) — corrigido com@Inject()explícito; atenção pra isso em guards/services futuros - Quota de ramais — depende de Plans/Entitlements (não existe ainda)
- Multi-domínio real por tenant — hoje só um domínio fixo pra todos
PHASE 09 — Trunks (agente.md secao 41-42)
- Tabela
trunks(tenant-scoped, RLS) — host/proxy/realm, register, username/password_enc (AES-256-GCM), dtmf_mode, ping, transport, status/status_updated_at apps/api/src/trunks: CRUD (POST/GET/GET:id/DELETE), mesmo padrão de RBAC/tenant de Extensions, senha nunca exposta em nenhum GETpackages/telephony:buildGatewayXml()(XML de gateway Sofia)b2bcall-fs-config: gerasip_profiles/external/<trunk_id>.xml(volume Docker compartilhado com o FreeSWITCH) e rodasofia profile external rescanvia ESL — sincroniza no boot e sob demanda via Redis pub/sub (b2bcall:trunks:sync, publicado pela API a cada create/delete)- Achado: 1º sync no boot corria antes da conexão ESL terminar de se
estabelecer (erro cosmético) — corrigido com
FreeSwitchTelephonyProvider.waitUntilConnected() - Testado ponta a ponta com host fake: criar trunk → arquivo gerado →
sofia status gatewaymostra o gateway real (FAIL_WAIT, esperado) → deletar → arquivo removido (limpeza também tirou oexample.comda vanilla que tinha sido copiado pro volume — comportamento correto) - Lacuna real, não resolvida:
Trunk.statusdeveria ser atualizado via eventossofia::gateway_state(código escrito emapps/freeswitch-events/src/trunk-status.ts, baseado no mesmonormalizeEslEventjá testado pra eventos CHANNEL_), mas o evento não foi observado chegando em ~90s de monitoramento mesmo com o gateway mudando de estado de verdade no FreeSWITCH (FAIL_WAIT/DOWN). Os eventossofia::*(CUSTOM) nunca foram provados funcionando nesta sessão — só CHANNEL_ foi verificado de ponta a ponta até agora. Precisa de investigação com um alvo SIP real (outro FreeSWITCH, por exemplo) antes de confiar em atualização automática de status em produção. Ver docs/TRUNKS.md. - Quota de troncos — depende de Plans/Entitlements (não existe ainda)
PHASE 10 — Dialplan (agente.md secao 43-44)
-
dialplan_extensions(tenant-scoped, RLS) — editor estruturado: context, condition field/expr, actions/anti-actions (JSON), continue, order, enabled -
dialplan_versions(tenant-scoped, RLS) — gerar/validar/versionar/ ativar; reativar versão antiga = rollback (sem endpoint separado) -
apps/api/src/dialplan: extensions CRUD +versions/generate+versions/:id/activate, permissionsfreeswitch.view/.configure -
Allowlist de applications seguras (
ALLOWED_DIALPLAN_APPLICATIONS, semsystem/exec/etc — agente.md secao 180) -
b2bcall-fs-configserve a versão ACTIVE dinamicamente por chamada (resolve tenant viavariable_b2bcall_tenant_id, não domain — não sofre da limitação de multi-domínio do directory) -
Testado ponta a ponta: criar extension → gerar v1 → ativar → originate passando pelo dialplan de verdade → CALL_CREATED/ANSWERED/ENDED com tenantId correto. Criar v2 → ativar (v1 vira SUPERSEDED) → reativar v1 (rollback, v2 vira SUPERSEDED). Tudo confirmado via API.
-
ACHADO CRÍTICO, corrigido nesta fase: testando a allowlist com
application: "system", a API aceitou (201) —ValidationPipedo Nest estava completamente inoperante em todaapps/apidesde que ela foi criada (todo@Body(), todos os controllers) porquetsx(esbuild) não emitedesign:paramtypescorretamente pra tipos importados de outro arquivo, e o Nest pula validação silenciosamente quando não reconhece o tipo. Corrigido:apps/apiagora builda comtscde verdade antes de rodar (tsc && tsx dist/main.js) — nunca maistsx src/main.tsdireto. Ver docs/VALIDATION_PIPE_BUG.md. Reverificado com 2 testes deliberados pós-correção, ambos corretamente rejeitados com 400. -
Só 1 condition por extension (simplificação) — FreeSWITCH suporta múltiplas em sequência, não implementado
-
dialplan.view/.managenão existem — reuseifreeswitch.*
PHASE 11 — mod_callcenter / Queues (agente.md secao 37, 50-51)
- Investigado
help callcenter_configreal antes de codar: filas só têmload/unload/reload(XML estático + reload, semqueue add); agentes e tiers são 100% dinâmicos via comando ESL (agent add,tier add) — próxima fase, sem arquivo nenhum queuestable (tenant-scoped, RLS) — strategy, moh/announce, wait times, tier rules, discard/abandoned, skip-external-calls, recording_enabledpackages/telephony:buildQueueXml()overrides/autoload_configs/callcenter.conf.xmlprópria (zera agents/tiers estáticos da vanilla, incluicallcenter_queues.conf.d/*.xmlvia X-PRE-PROCESS)apps/api/src/queues: CRUD (POST/GET/GET:id/DELETE), permissionsqueues.view/.manageb2bcall-fs-config(queue-sync.ts): 1 arquivo por fila (volume compartilhado), sincroniza via Redis pub/sub (b2bcall:queues:sync)- Achado real, confirmado testando manualmente antes de escrever código:
queue loadfalha se o arquivo foi adicionado depois do boot — precisa dereloadxmlprimeiro; depois disso,queue reloadsozinho serve tanto pra criar quanto atualizar - Testado ponta a ponta: criar fila (ROUND_ROBIN, maxWaitTime=120,
discardAbandonedAfter=90) →
callcenter_config queue listmostra os parâmetros corretos → deletar → lista volta vazia - Agentes/Tiers/Pausas (secao 45-49) — próxima fase
- Monitoramento em tempo real (secao 54) — depende de WebSocket
- Quota de filas — depende de Plans/Entitlements
PHASE 12 — Agentes, Tiers, Pausas (agente.md secao 45-49, 52)
agents/tiers/agent_sessions/agent_state_events/pause_reasons/agent_pause_events(tenant-scoped, RLS) — separa User/Agent/Extension (secao 45)- Corrigidos bugs reais em
FreeSwitchTelephonyProvider(nunca testados antes):addAgentToQueue/removeAgentFromQueueusavam "queue add/del member", que não existe — comando certo étier add/tier del. AdicionadosaddAgent/removeAgent(agent add/agent del), que faltavam por completo. - Confirmado manualmente antes de codar:
agent add/tier addduplicado dá erro ("already exist", capturado e ignorado no sync);agent del/tier delem algo inexistente não dá erro;agent set statussó aceitaAvailable/On Break/Logged Out - Sync 100% dinâmico via ESL (sem arquivo, diferente de Trunks/Queues):
b2bcall:agents:sync/b2bcall:tiers:sync(Redis pub/sub com payload por ação, não um resync geral) apps/api:/agents(CRUD provisionamento),/agents/me/login| logout|pause|resume(sempre sobre o agente do usuário autenticado, nunca um id arbitrário do client),/pause-reasons,/queues/:id/agents(tier assignment)- Achado de corrida real, visto no teste ponta a ponta: atribuir tier antes do primeiro login falha (agente ainda não existe no FreeSWITCH) — login sempre re-sincroniza todos os tiers do agente, autocorrigindo. Confirmado acontecendo exatamente assim no teste.
- Testado ponta a ponta os 4 estados: login→Available, pause→On Break,
resume→Available, logout→Logged Out — todos confirmados batendo
entre
Agent.state(banco) ecallcenter_config agent list(FreeSWITCH) - Estados derivados de chamada (RINGING/IN_CALL/WRAP_UP/RESERVED) —
mecanismo de entrega do
callcenter::infocorrigido e confirmado (ver PHASE 13); persistir emAgent.stateainda não implementado PauseReason.maxDurationnão é aplicado automaticamente- Quota de agentes — depende de Plans/Entitlements
- Achado sistêmico:
@@uniquecombinado com soft delete (sem excluirdeletedAt) emAgent/Extension/Trunk/Queue/PauseReason— não dá pra reusar número/nome/código depois de apagar. Precisa de índice único parcial em cada um, migration própria (ver docs/AGENTS.md)
PHASE 13 — Realtime Monitoring / WebSocket multi-tenant (agente.md secao 54-55, 161)
- Bug real, achado nesta fase: nenhum evento CUSTOM do ESL
(
sofia::register,sofia::gateway_state,callcenter::info) jamais chegava emb2bcall-fs-events—event_json(...)mandava"CUSTOM"como último token do comandoevent json, sem subclass depois (mod_event_socket exige os subclasses logo depois do token CUSTOM no mesmo comando). Corrigido separandoPLAIN_EVENTS/CUSTOM_SUBCLASSES. Resolve as lacunas documentadas em PHASE 09/12 e docs/TRUNKS.md/AGENTS.md. - Corrigido de quebra:
CC-Agent-Status(não existe) →CC-Agent-State(campo real); novos tipos normalizadosAGENT_OFFERED_CALL,AGENT_BRIDGE_FAILED,QUEUE_MEMBER_COUNT,QUEUE_MEMBER_LEFT - Corrigido de quebra:
sofia profile external rescannunca descarregava um gateway cujo arquivo foi apagado (fantasma na memória do Sofia) —trunk-sync.tsagora rodakillgw <nome>pra cada gateway removido tenant-resolve.ts(fs-events): resolve tenantId por fan-out (agente/fila não carregamb2bcall_tenant_id— só existe a partir do Predictive Engine), cacheado por idapps/api:RealtimeGateway(socket.io sobre o Fastify HTTP server), auth via JWT no handshake (monitoring.view), uma room por tenant (tenant:<id>) — nunca broadcast global, sempreserver.to(room)(secao 161: tenant-scoped no servidor, nunca filtrar só no browser)RealtimeRedisBridge: assinab2bcall:events(canal único, mesmo usado desde Event Socket), reencaminha pro tenant certoAGENT_STATE_CHANGEDpublicado direto deagents-me.controller.ts(login/logout/pause/resume) — tenantId já vem do JWT, sem fan-out- Testado ponta a ponta: login/pause/resume/logout via WS, chamada de teste numa fila real (QUEUE_MEMBER_COUNT/LEFT, AGENT_OFFERED_CALL, AGENT_BRIDGE_FAILED, AGENT_STATUS_CHANGED com CC-Agent-State correto), token inválido desconectado na hora
- Ramais/extensões (secao 55 completa: busy/registro) — precisa de SIP real pra testar, e extrair ramal dos headers de canal (não feito)
- TME/TMA/Service Level/Abandon Rate — dependem de CDR (fase futura)
- Snapshot/reconciliação ao reconectar o WebSocket
PHASE 14 — Plans/Entitlements (agente.md secao 56-62)
- Fase que tinha ficado pra trás: a ordem de implementação (secao 232)
coloca Plans/Entitlements logo depois de PostgreSQL RLS, bem antes de
FreeSWITCH — mas o build seguiu direto sem essa peça. Toda fase desde
então documentou "quota depende de Plans/Entitlements" como
pendência. Fechado agora, antes de Campanhas (que dependem de
max_campaigns) e do CPS Limiter (que vai depender demax_cps) plans(catálogo compartilhado, sem RLS — não é tenant-scoped) +tenants.plan_idobrigatório (nunca null: campo de limite null = "sem limite", nunca "sem plano", agente.md secao 56)- Migration hand-escrita: cria
plans, insere seed "trial", faz backfill deplan_idpros tenants existentes, só depoisNOT NULL(Postgres não deixaNOT NULLsem default em tabela não-vazia) packages/entitlements(pacote novo):assertQuota/assertFeatureEnabled, erros mapeados pra 403 noDomainExceptionFilter- Retrofit nos controllers existentes: Extensions/Trunks/Agents/Queues agora contam linhas ativas e checam quota antes de criar
- Testado ponta a ponta: 5 extensões OK (limite do trial), 6a rejeitada com 403 "Quota excedida: maxExtensions (limite do plano: 5)"
PHASE 15 — Campanhas, Leads, Lista de Bloqueio (agente.md secao 63-71)
campaigns/leads/suppression_entries(tenant-scoped, RLS) — só modelo/CRUD/máquina de estados; o motor que origina chamadas de verdade (PredictiveDialerEngine) é uma fase à parte, deliberadamente não implementada aqui (agente.md secao 72: "não é sófor lead -> originate")- Máquina de estados da campanha (secao 64-66): start/pause/drain/stop com tabela de transições válidas — tentar uma transição inválida (ex.: pause numa DRAFT) retorna 400, nunca ignora silenciosamente
packages/shared/src/phone.ts(secao 70): normalização dedicada, preparada pra E.164 completo, só BR implementado por enquanto- Importação CSV em batches de 1000 (secao 69): detecta duplicado (dentro do CSV + contra leads já existentes), checa lista de bloqueio (importa como DO_NOT_CALL, não descarta), retorna resumo {total, valid, invalid, duplicates, imported, suppressed}
- Lista de bloqueio (secao 71): CRUD tenant-scoped
- Testado ponta a ponta: campanha com queueId/trunkId inválido rejeitada, pacingMin > pacingMax rejeitado, CSV de 5 linhas (1 inválida, 1 duplicada, 1 bloqueada) importado corretamente, start->pause->drain->stop e transições inválidas todas corretas, 3a campanha rejeitada por quota (max_campaigns=2 do plano trial)
PredictiveDialerEngine(secao 72-86) — dados em tempo real, EWMA, CPS distribuído, reserva atômica de lead, lock de campanha, originate via bgapi, state machine da chamada, controle de abandono, retry — implementado na PHASE 16- Wizard visual de importação (upload de arquivo) — fase Frontend
- Relatório de campanha (secao 160) — depende de CDR
PHASE 16 — CPS Limiter / Predictive Dialer Engine (agente.md secao 72-86, 77-79)
- Novo serviço
apps/predictive-dialer(mesmo padrão de fs-events/ fs-config: Node standalone em Docker, ESL própria, tick a cada 2s sobre tenants ativos x campanhas RUNNING/WAITING_SCHEDULE) - Lock de campanha (
dialer:campaign:{id}, secao 79): TTL, ownership token, renewal, safe release (Lua compare-and-delete) — testado isolado, outro dono nunca rouba nem renova o lock de quem já tem - CPS distribuído (secao 77, 62): token bucket janela de 1s (Lua atômico), hierarquia GLOBAL/TENANT/TRUNK/CAMPAIGN numa única chamada — testado isolado, nível esgotado bloqueia todos SEM incremento parcial dos que passariam
- Reserva atômica de leads (secao 78):
FOR UPDATE SKIP LOCKEDraw SQL dentro da mesma transaçãowithTenantContext CallAttempt/CampaignStats(schema novo): state machine da chamada (secao 82) + EWMA (secao 75, alpha=0.25) de answer_probability/average_answer_delay/average_talk_time/ abandon_rate, persistida por campanha- Capacidade em tempo real + pacing (secao 73-76, 84-85): conta agentes por estado via Tier->Agent.state, previsão de liberação simplificada (horizonte único de 15s em vez dos 4 buckets da especificação), controle de abandono reduz pacing progressivamente, nunca origina sem capacidade prevista
- Modo simulação (secao 185): DIALER_SIMULATION=true (default) sorteia ANSWER/BUSY/NO_ANSWER/FAILED em software, sem PSTN real. Só quando ANSWERED é que uma chamada sintética (null/dummy, sem PSTN) entra na fila real via mod_callcenter de verdade — maximiza código real exercitado em vez de simular tudo em memória
- Real Outbound Safety (secao 186): as duas flags (DIALER_SIMULATION=false + ALLOW_REAL_OUTBOUND_CALLS=true) checadas no boot, nunca ativado automaticamente — caminho PSTN real implementado mas nunca exercitado (sem trunk real neste laboratório)
- Bug real, achado no teste desta fase: perna sintética (null/
dummy) não tem mídia do outro lado — nunca desliga sozinha depois de
bridgear com um agente. Corrigido com hangup agendado via
uuid_killno talk_time simulado. - Bug real, achado no teste desta fase: corrida entre
queue:syncetier:sync(dois canais Redis independentes, sem ordem garantida) — atribuir tier logo depois de criar a fila podia rodartier addantes doqueue reloadterminar ("-ERR Queue not found!", diferente do já conhecido "already exist"). Corrigido com retry curto emagent-sync.ts::addTierWithRetry. GET /campaigns/:id/stats(secao 227.7 "visualizar pacing"): CampaignStats + contagem de agentes por estado + calls em andamento- Testado ponta a ponta: campanha RUNNING originando 3 tentativas por
tick, outcomes simulados corretos com retry agendado, uma chamada
simulada-ANSWERED completando o ciclo real inteiro (queue -> agente
-> bridge -> hangup -> EWMA atualizada), stop não derruba chamada
ativa (secao 66), calls_answered=3 confirmado no
queue listdo FreeSWITCH ao final - 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, ficam pra fase CDR
- CPS a nível de trunk — só aplica quando o caminho PSTN real rodar
- Relatório de campanha (secao 160), TME/TMA/Service Level/Abandon Rate agregados — dependem de CDR
PHASE 17+ — ver agente.md seções 87 em diante (CDR, Recordings, AI,
Billing, Frontend, Reports, Security, Tests)
Riscos conhecidos
- RAM da VM (1.9GB total): medido com Postgres+Redis+FreeSWITCH rodando juntos — ~91MB no total (Postgres 37MB, Redis 10MB, FreeSWITCH 44MB), bem tranquilo. O risco real ainda não testado é o build/runtime do Next.js (frontend) e vários workers Node simultâneos — reavaliar quando chegarmos lá.
- Disco (26GB livre): build do FreeSWITCH + imagens Docker + gravações vão consumir
espaço rápido. Monitorar com
df -h.