B2BCall-dialer

Matheus/B2BCall-dialer

Fork 0

Commit Graph

Author	SHA1	Message	Date
Matheus	7b62ad3d82	feat(entitlements,campaigns): plans/quotas + campanhas, leads, lista de bloqueio Fecha duas fases: Plans/Entitlements (agente.md secao 56-62), que tinha ficado pra trás desde o inicio, e Campanhas/Leads/Lista de Bloqueio (secao 63-71). ## Plans/Entitlements A ordem de implementacao da propria especificacao (secao 232) coloca Plans/Entitlements logo depois de PostgreSQL RLS, bem antes de FreeSWITCH — mas o build seguiu direto sem essa peca, e toda fase desde entao documentou "quota depende de Plans/Entitlements" como pendencia (EXTENSIONS.md, TRUNKS.md, AGENTS.md, QUEUES.md, agora todas atualizadas). Fechado agora porque Campanhas precisa de max_campaigns e o proximo CPS Limiter vai precisar de max_cps/max_concurrent_calls. - plans: catalogo compartilhado entre tenants (sem RLS, nao e' tenant- scoped) com todos os campos de entitlement da secao 56. Campo de limite null = "sem limite", nunca "sem plano" — tenants.plan_id e' obrigatorio, nunca null (secao 56: nao espalhar `if plan == PRO` pelo codigo). - Migration hand-escrita: cria plans, insere seed "trial", faz backfill de plan_id pros tenants ja existentes, so' depois torna NOT NULL (Postgres nao deixa NOT NULL sem default em tabela nao-vazia). - packages/entitlements (pacote novo): assertQuota/assertFeatureEnabled, erros mapeados pra 403 no DomainExceptionFilter. - Retrofit em Extensions/Trunks/Agents/Queues: contam linhas ativas e checam quota antes de criar. ## Campanhas, Leads, Lista de Bloqueio Deliberadamente so' o modelo/CRUD/maquina de estados — o motor que de fato origina chamadas (PredictiveDialerEngine, secao 72-86: dados em tempo real, EWMA, CPS distribuido, reserva atomica de lead, lock de campanha, bgapi originate, controle de abandono, retry) e' um sistema grande o suficiente pra merecer fase propria (secao 72: "nao e' so' `for lead -> originate`"). - campaigns/leads/suppression_entries (tenant-scoped, RLS). - Maquina de estados da campanha (secao 64-66): start/pause/drain/stop com tabela de transicoes validas — transicao invalida retorna 400, nunca ignora silenciosamente. Apagar bloqueado enquanto RUNNING/DRAINING. - packages/shared/src/phone.ts (secao 70): normalizacao dedicada, preparada pra E.164 completo, so' BR implementado. - Importacao CSV em batches de 1000 (secao 69): detecta duplicado (dentro do CSV + contra leads existentes), checa lista de bloqueio (importa como DO_NOT_CALL, nao descarta), retorna {total, valid, invalid, duplicates, imported, suppressed}. - Lista de bloqueio (secao 71): CRUD tenant-scoped. Verificado ponta a ponta: campanha com queueId/trunkId invalido e pacingMin > pacingMax rejeitados; CSV de 5 linhas (1 invalida, 1 duplicada, 1 bloqueada) importado corretamente; start->pause->drain->stop e transicoes invalidas todas corretas; 3a campanha rejeitada por quota (max_campaigns=2 do plano trial); 6a extensao rejeitada por quota (max_extensions=5). Suites de teste existentes (tenant-isolation, auth) atualizadas pro novo Tenant.planId obrigatorio e passando. 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 12:26:47 -03:00
Matheus	a05104a05f	feat(agents): agentes, tiers e pausas — call center completo Fecha agente.md secao 45-49/52. Depois desta fase, um usuario autenticado consegue logar como agente, entrar numa fila real, se pausar e voltar, tudo refletido de verdade no FreeSWITCH. Schema (migration 20260828124245_agents): - agents (tenant-scoped, RLS): User -> Extension -> identidade de agente, state (enum AgentState de 8 valores) espelhando o estado real, so alterado via login/logout/pause/resume, nunca escrito direto pela API. - tiers: Queue<->Agent (level/position 1:1 com mod_callcenter). - agent_sessions: um ciclo login->logout por linha. - agent_state_events: historico de transicoes de estado. - pause_reasons / agent_pause_events (secao 48). Dois bugs reais corrigidos em FreeSwitchTelephonyProvider, presentes desde a fase de Event Socket original: - "queue add/del member" nao existe no mod_callcenter — membership de fila usa tier add/tier del. So foi pego agora ao confirmar de novo a sintaxe via `help callcenter_config` antes de codar esta fase. - addAgent/removeAgent nao existiam ainda (agent add/del). Mecanismo de sync: agentes e tiers nao tem representacao em XML, so comando ESL direto — diferente do padrao "regenera todos os arquivos" usado em Trunks/Queues. apps/api publica uma mensagem por acao com payload (b2bcall:agents:sync, b2bcall:tiers:sync); b2bcall-fs-config aplica o comando correspondente (agent-sync.ts). Achados confirmados manualmente contra o FreeSWITCH real antes de codar: - `agent add`/`tier add` nao sao idempotentes (erro em duplicata) — sync ignora esse erro (.catch), condicao esperada em resync. - `agent del`/`tier del` em algo inexistente nao da erro — seguro chamar sem checar existencia antes. - `agent set status` so aceita 3 valores exatos (Available/On Break/ Logged Out) — testado deliberadamente com valor invalido. - Corrida real: atribuir tier antes do primeiro login do agente falha silenciosamente do lado do FreeSWITCH (agente so existe la a partir do `agent add` no login). Login sempre re-sincroniza todos os tiers do agente depois de garantir que ele existe — auto-correcao confirmada no teste ponta a ponta. apps/api: AgentsController (CRUD), AgentsMeController (login/logout/ pause/resume — sempre resolve o agente via JWT, nunca um agentId arbitrario do client), PauseReasonsController (CRUD), QueueAgentsController (POST/DELETE de tier em /queues/:id/agents). Verificado ponta a ponta via curl + fs_cli contra o FreeSWITCH real: login -> Available, pause -> On Break, resume -> Available, logout -> Logged Out, todos batendo entre Agent.state (banco) e `agent list` (FreeSWITCH). typecheck do workspace inteiro limpo. ~350MB de memoria total (docker stats). Documentado em docs/AGENTS.md, incluindo lacuna conhecida: estados derivados de chamada (RINGING/IN_CALL/WRAP_UP/RESERVED) dependem do evento CUSTOM callcenter::info, ainda nao comprovado chegando em fs-events nesta sessao (mesma lacuna de sofia::gateway_state ja documentada em docs/TRUNKS.md) — precisa de uma chamada real passando pela fila pra investigar. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01X1HxY46WGU4G1zmVDNKcWw	2026-08-28 09:58:45 -03:00
Matheus	6628578c42	feat: implement Call Center queues (mod_callcenter) - Investigated the real callcenter_config command surface via 'help callcenter_config' on the running FreeSWITCH before writing any code: queues only have load/unload/reload (static XML + reload, no 'queue add' exists), while agents and tiers are fully dynamic via ESL commands (agent add, tier add) -- no file involved. This shapes the next phase (Agents/Tiers) differently from this one. - queues table (tenant-scoped, RLS): strategy, moh/announce, wait times, tier rules, discard/abandoned handling, skip-agents-with-external-calls, recording_enabled - packages/telephony: buildQueueXml() - infrastructure/freeswitch: our own callcenter.conf.xml override (empties the vanilla static agents/tiers -- those become fully dynamic in the next phase) that includes callcenter_queues.conf.d/*.xml via X-PRE-PROCESS, same pattern as the Sofia gateway directory - apps/api/src/queues: CRUD (POST/GET/GET:id/DELETE) using the queues.view/ .manage permissions already in the seed - b2bcall-fs-config (queue-sync.ts): one XML file per queue on a shared volume, synced via Redis pub/sub (b2bcall:queues:sync) on create/delete and once at boot -- same shape as trunk-sync.ts - confirmed manually against the real FreeSWITCH, before coding the sync logic: 'queue load <name>' fails ('Invalid Queue not found!') for a file added after boot -- needs 'reloadxml' first to repopulate the in-memory XML tree from disk; after that, 'queue reload <name>' alone handles both create and update, no need to distinguish load vs reload - verified end-to-end: created a queue (ROUND_ROBIN, maxWaitTime=120, discardAbandonedAfter=90), 'callcenter_config queue list' showed the correct values on the FreeSWITCH side; deleted it, list went back empty docs/QUEUES.md	2026-08-28 09:15:11 -03:00

Author

SHA1

Message

Date

Matheus

7b62ad3d82

feat(entitlements,campaigns): plans/quotas + campanhas, leads, lista de bloqueio

Fecha duas fases: Plans/Entitlements (agente.md secao 56-62), que tinha
ficado pra trás desde o inicio, e Campanhas/Leads/Lista de Bloqueio (secao
63-71).

## Plans/Entitlements

A ordem de implementacao da propria especificacao (secao 232) coloca
Plans/Entitlements logo depois de PostgreSQL RLS, bem antes de FreeSWITCH
— mas o build seguiu direto sem essa peca, e toda fase desde entao
documentou "quota depende de Plans/Entitlements" como pendencia
(EXTENSIONS.md, TRUNKS.md, AGENTS.md, QUEUES.md, agora todas atualizadas).
Fechado agora porque Campanhas precisa de max_campaigns e o proximo CPS
Limiter vai precisar de max_cps/max_concurrent_calls.

- plans: catalogo compartilhado entre tenants (sem RLS, nao e' tenant-
  scoped) com todos os campos de entitlement da secao 56. Campo de limite
  null = "sem limite", nunca "sem plano" — tenants.plan_id e' obrigatorio,
  nunca null (secao 56: nao espalhar `if plan == PRO` pelo codigo).
- Migration hand-escrita: cria plans, insere seed "trial", faz backfill de
  plan_id pros tenants ja existentes, so' depois torna NOT NULL (Postgres
  nao deixa NOT NULL sem default em tabela nao-vazia).
- packages/entitlements (pacote novo): assertQuota/assertFeatureEnabled,
  erros mapeados pra 403 no DomainExceptionFilter.
- Retrofit em Extensions/Trunks/Agents/Queues: contam linhas ativas e
  checam quota antes de criar.

## Campanhas, Leads, Lista de Bloqueio

Deliberadamente so' o modelo/CRUD/maquina de estados — o motor que de fato
origina chamadas (PredictiveDialerEngine, secao 72-86: dados em tempo
real, EWMA, CPS distribuido, reserva atomica de lead, lock de campanha,
bgapi originate, controle de abandono, retry) e' um sistema grande o
suficiente pra merecer fase propria (secao 72: "nao e' so' `for lead ->
originate`").

- campaigns/leads/suppression_entries (tenant-scoped, RLS).
- Maquina de estados da campanha (secao 64-66): start/pause/drain/stop com
  tabela de transicoes validas — transicao invalida retorna 400, nunca
  ignora silenciosamente. Apagar bloqueado enquanto RUNNING/DRAINING.
- packages/shared/src/phone.ts (secao 70): normalizacao dedicada,
  preparada pra E.164 completo, so' BR implementado.
- Importacao CSV em batches de 1000 (secao 69): detecta duplicado (dentro
  do CSV + contra leads existentes), checa lista de bloqueio (importa como
  DO_NOT_CALL, nao descarta), retorna {total, valid, invalid, duplicates,
  imported, suppressed}.
- Lista de bloqueio (secao 71): CRUD tenant-scoped.

Verificado ponta a ponta: campanha com queueId/trunkId invalido e
pacingMin > pacingMax rejeitados; CSV de 5 linhas (1 invalida, 1
duplicada, 1 bloqueada) importado corretamente; start->pause->drain->stop
e transicoes invalidas todas corretas; 3a campanha rejeitada por quota
(max_campaigns=2 do plano trial); 6a extensao rejeitada por quota
(max_extensions=5). Suites de teste existentes (tenant-isolation, auth)
atualizadas pro novo Tenant.planId obrigatorio e passando.

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 12:26:47 -03:00

Matheus

a05104a05f

feat(agents): agentes, tiers e pausas — call center completo

Fecha agente.md secao 45-49/52. Depois desta fase, um usuario autenticado
consegue logar como agente, entrar numa fila real, se pausar e voltar,
tudo refletido de verdade no FreeSWITCH.

Schema (migration 20260828124245_agents):
- agents (tenant-scoped, RLS): User -> Extension -> identidade de agente,
  state (enum AgentState de 8 valores) espelhando o estado real, so
  alterado via login/logout/pause/resume, nunca escrito direto pela API.
- tiers: Queue<->Agent (level/position 1:1 com mod_callcenter).
- agent_sessions: um ciclo login->logout por linha.
- agent_state_events: historico de transicoes de estado.
- pause_reasons / agent_pause_events (secao 48).

Dois bugs reais corrigidos em FreeSwitchTelephonyProvider, presentes desde
a fase de Event Socket original:
- "queue add/del member" nao existe no mod_callcenter — membership de
  fila usa tier add/tier del. So foi pego agora ao confirmar de novo a
  sintaxe via `help callcenter_config` antes de codar esta fase.
- addAgent/removeAgent nao existiam ainda (agent add/del).

Mecanismo de sync: agentes e tiers nao tem representacao em XML, so
comando ESL direto — diferente do padrao "regenera todos os arquivos"
usado em Trunks/Queues. apps/api publica uma mensagem por acao com
payload (b2bcall:agents:sync, b2bcall:tiers:sync); b2bcall-fs-config
aplica o comando correspondente (agent-sync.ts).

Achados confirmados manualmente contra o FreeSWITCH real antes de codar:
- `agent add`/`tier add` nao sao idempotentes (erro em duplicata) — sync
  ignora esse erro (.catch), condicao esperada em resync.
- `agent del`/`tier del` em algo inexistente nao da erro — seguro chamar
  sem checar existencia antes.
- `agent set status` so aceita 3 valores exatos (Available/On Break/
  Logged Out) — testado deliberadamente com valor invalido.
- Corrida real: atribuir tier antes do primeiro login do agente falha
  silenciosamente do lado do FreeSWITCH (agente so existe la a partir do
  `agent add` no login). Login sempre re-sincroniza todos os tiers do
  agente depois de garantir que ele existe — auto-correcao confirmada no
  teste ponta a ponta.

apps/api: AgentsController (CRUD), AgentsMeController (login/logout/
pause/resume — sempre resolve o agente via JWT, nunca um agentId
arbitrario do client), PauseReasonsController (CRUD), QueueAgentsController
(POST/DELETE de tier em /queues/:id/agents).

Verificado ponta a ponta via curl + fs_cli contra o FreeSWITCH real:
login -> Available, pause -> On Break, resume -> Available, logout ->
Logged Out, todos batendo entre Agent.state (banco) e `agent list`
(FreeSWITCH). typecheck do workspace inteiro limpo. ~350MB de memoria
total (docker stats).

Documentado em docs/AGENTS.md, incluindo lacuna conhecida: estados
derivados de chamada (RINGING/IN_CALL/WRAP_UP/RESERVED) dependem do
evento CUSTOM callcenter::info, ainda nao comprovado chegando em
fs-events nesta sessao (mesma lacuna de sofia::gateway_state ja
documentada em docs/TRUNKS.md) — precisa de uma chamada real passando
pela fila pra investigar.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X1HxY46WGU4G1zmVDNKcWw

2026-08-28 09:58:45 -03:00

Matheus

6628578c42

feat: implement Call Center queues (mod_callcenter)

- Investigated the real callcenter_config command surface via
  'help callcenter_config' on the running FreeSWITCH before writing any
  code: queues only have load/unload/reload (static XML + reload, no
  'queue add' exists), while agents and tiers are fully dynamic via ESL
  commands (agent add, tier add) -- no file involved. This shapes the next
  phase (Agents/Tiers) differently from this one.
- queues table (tenant-scoped, RLS): strategy, moh/announce, wait times,
  tier rules, discard/abandoned handling, skip-agents-with-external-calls,
  recording_enabled
- packages/telephony: buildQueueXml()
- infrastructure/freeswitch: our own callcenter.conf.xml override (empties
  the vanilla static agents/tiers -- those become fully dynamic in the next
  phase) that includes callcenter_queues.conf.d/*.xml via X-PRE-PROCESS,
  same pattern as the Sofia gateway directory
- apps/api/src/queues: CRUD (POST/GET/GET:id/DELETE) using the queues.view/
  .manage permissions already in the seed
- b2bcall-fs-config (queue-sync.ts): one XML file per queue on a shared
  volume, synced via Redis pub/sub (b2bcall:queues:sync) on create/delete
  and once at boot -- same shape as trunk-sync.ts
- confirmed manually against the real FreeSWITCH, before coding the sync
  logic: 'queue load <name>' fails ('Invalid Queue not found!') for a file
  added after boot -- needs 'reloadxml' first to repopulate the in-memory
  XML tree from disk; after that, 'queue reload <name>' alone handles both
  create and update, no need to distinguish load vs reload
- verified end-to-end: created a queue (ROUND_ROBIN, maxWaitTime=120,
  discardAbandonedAfter=90), 'callcenter_config queue list' showed the
  correct values on the FreeSWITCH side; deleted it, list went back empty

docs/QUEUES.md

2026-08-28 09:15:11 -03:00

3 Commits