Files

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

3.7 KiB

Raw Blame History

Filas (mod_callcenter)

Agente.md secao 37 (mod_callcenter como ACD) e 50-51 (Filas/Estratégias). Primeira peça do Call Center — Agentes/Tiers/Pausas ficam pra próxima fase (dependem do fluxo de login do agente, seção 45-49, escopo maior).

Descoberta real sobre `callcenter_config`

Antes de escrever qualquer código, rodei help callcenter_config no FreeSWITCH real pra ver a sintaxe exata — e ela é bem diferente do que os Trunks fizeram supor:

Filas: só queue load/unload/reload/list — não existe queue add nem queue set param. Filas só podem vir de XML estático, carregado/recarregado por nome.
Agentes: agent add/del/set status/set state/... — 100% dinâmico via comando ESL, sem XML.
Tiers: tier add/del/set state/set level/set position — também 100% dinâmico.

Ou seja, filas usam o mesmo padrão "arquivo + reload" dos Trunks; agentes e tiers (próxima fase) vão usar comandos ESL diretos, sem arquivo nenhum.

Mecanismo

Mesmo padrão dos gateways Sofia: um arquivo XML por fila (autoload_configs/callcenter_queues.conf.d/<queue_id>.xml, volume Docker compartilhado), incluído via X-PRE-PROCESS no nosso callcenter.conf.xml próprio (agente.md secao 15 — "carregar somente o necessário": zeramos os <agents>/<tiers> estáticos da vanilla, já que essas partes vão ser 100% dinâmicas).

Sequência de comandos confirmada manualmente contra o FreeSWITCH real (testei cada passo antes de escrever o código):

queue load <nome> falha ("Invalid Queue not found!") se o arquivo foi adicionado depois do boot — a árvore XML em memória não sabe do arquivo novo ainda.
reloadxml primeiro repopula essa árvore a partir do disco.
Depois disso, queue reload <nome> sozinho já serve tanto pra criar quanto atualizar — não precisa distinguir load de reload.
Fila removida: apagar o arquivo, reloadxml, queue unload <nome>.

b2bcall-fs-config (queue-sync.ts) reescreve todos os arquivos de fila habilitada (todos os tenants) a cada sync, remove os obsoletos, roda reloadxml uma vez, depois queue reload por fila desejada e queue unload por fila removida. Disparado por Redis pub/sub (b2bcall:queues:sync, mesmo mecanismo dos Trunks) a cada create/delete via API, e uma vez no boot do serviço.

Nome da fila no FreeSWITCH

<queue.id>@<tenant.telephonyDomain> — mesma convenção UUID dos gateways. Como o telephonyDomain hoje é compartilhado entre tenants (limitação já documentada em docs/EXTENSIONS.md), o unload de uma fila apagada usa o domain de "qualquer tenant ativo" como aproximação, já que o registro no banco já não existe mais nesse ponto pra sabermos o domain exato.

Verificado ponta a ponta

POST /queues {"name":"Suporte","strategy":"ROUND_ROBIN","maxWaitTime":120,"discardAbandonedAfter":90}
→ fs-config sincroniza (desired:1) → reloadxml + queue reload

callcenter_config queue list
→ <id>@b2bcall.local|round-robin|...|90|false|120|...  (parâmetros batem)

DELETE /queues/:id
→ fs-config sincroniza (removed:1) → reloadxml + queue unload
→ callcenter_config queue list volta vazia

O que falta

Agentes, Tiers, Pausas (secao 45-49) — implementados na fase seguinte, ver docs/AGENTS.md.
Monitoramento em tempo real das filas (secao 54) — depende de WebSocket multi-tenant, que ainda não existe.
tier-rule-wait-multiply-level e tier-rule-no-agent-no-wait (vistos no queue list da config vanilla) não são expostos como campos próprios ainda — ficaram de fora do escopo desta fase.
~~Quota de filas~~ — implementada na fase Plans/Entitlements (ver docs/ENTITLEMENTS.md), assertQuota chamado antes de criar.

3.7 KiB Raw Blame History