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

docs/AGENTS.md

@@ -105,7 +105,8 @@ FreeSWITCH (`agent list`).
   (docs/REALTIME.md); persistir isso em `Agent.state` fica pra quando o
   Predictive Engine/CDR precisarem consultar esse histórico.
 - Tela do agente (secao 49) — fase Frontend.
-- Quota de agentes (`max_agents`) — depende de Plans/Entitlements.
+- ~~Quota de agentes~~ — implementada na fase Plans/Entitlements (ver
+  docs/ENTITLEMENTS.md), `assertQuota` chamado antes de criar.
 - `PauseReason.maxDuration` existe no modelo mas não é aplicado
   automaticamente ainda (ninguém força o fim da pausa ao expirar).
 - **Achado ao testar a fase Realtime Monitoring, sistêmico (não é só

docs/CAMPAIGNS.md

@@ -0,0 +1,122 @@
+# Campanhas, Leads e Lista de Bloqueio
+
+Agente.md secao 63-71. Modelo de dados, CRUD, máquina de estados da
+campanha e importação de leads — o motor que de fato origina chamadas
+(`PredictiveDialerEngine`, secao 72-86) é uma fase à parte, deliberadamente
+não implementada aqui (é um sistema grande o suficiente — pacing por EWMA,
+previsão de liberação de agentes, CPS distribuído, reserva atômica de
+leads — pra merecer o próprio ciclo de design/teste, ver agente.md secao 72
+"Não implementar apenas `for lead -> originate`. Isso não é discador
+preditivo.").
+
+## Modelo
+
+- `campaigns` (tenant-scoped, RLS): liga `Queue`+`Trunk`, janela de
+  funcionamento (`timezone`/`daysOfWeek`/`startTime`/`endTime`/`startDate`/
+  `endDate`), limites (`maxCps`/`maxConcurrentCalls`, além dos globais do
+  Plan), parâmetros de pacing (`pacingInitial`/`Min`/`Max`,
+  `targetAbandonRate` — consumidos pela fase Predictive Engine, só
+  armazenados aqui), `maxAttempts`/`ringTimeout`, flags de gravação/AVMD/IA.
+  `daysOfWeek` é `Int[]` ISO-8601 (1=segunda...7=domingo); `startTime`/
+  `endTime` são `"HH:MM"` string — sem tipo TIME nativo nesta fase (o
+  scheduler de verdade avalia isso na timezone da campanha, é trabalho da
+  fase Predictive Engine).
+- `leads` (tenant-scoped, RLS): `campaignId`, `phoneOriginal`/
+  `phoneNormalized` (E.164), `status` (enum de 16 valores, secao 68),
+  `attemptCount`/`lastAttemptAt`/`nextAttemptAt`/`lastResult`,
+  `customFields` JSONB livre. Único por `(campaignId, phoneNormalized)` —
+  o mesmo telefone pode existir em campanhas diferentes, nunca duas vezes
+  na mesma.
+- `suppression_entries` (tenant-scoped, RLS): lista de bloqueio (secao 71),
+  único por `(tenantId, phoneNormalized)`.
+
+## Máquina de estados da campanha (secao 64-66)
+
+```
+start:  DRAFT|READY|WAITING_SCHEDULE|PAUSED -> RUNNING
+pause:  RUNNING -> PAUSED
+drain:  RUNNING|PAUSED -> DRAINING   (não origina novas, deixa terminar as existentes)
+stop:   qualquer não-terminal -> STOPPED
+```
+
+Cada transição valida o estado atual contra uma tabela de transições
+permitidas (`ALLOWED_TRANSITIONS` em `campaigns.controller.ts`) — tentar
+`pause` numa campanha `DRAFT` retorna 400, não silenciosamente ignora.
+Apagar (soft delete) é bloqueado enquanto `RUNNING`/`DRAINING` — precisa
+parar primeiro.
+
+`COMPLETED`/`ERROR` não são alcançáveis via API nesta fase — são estados
+que só o motor de discagem (fase Predictive Engine) vai setar sozinho
+(leads esgotados / falha operacional).
+
+## `packages/shared/src/phone.ts` — normalização (secao 70)
+
+Serviço dedicado, `normalizePhone(raw, country = "BR")`. Assinatura já
+preparada pra outros países (E.164 completo) — só o normalizador BR está
+implementado. Aceita com/sem "55" na frente, DDD 2 dígitos + 8 ou 9 dígitos
+de número; retorna `null` (nunca lança) pra entrada inválida, já que
+"número inválido" é um resultado esperado de uma importação de CSV.
+
+## Importação CSV (secao 69)
+
+`POST /campaigns/:id/leads/import`, corpo `{ csv: string }` — a versão
+desta fase recebe o CSV como texto no corpo JSON, não upload de arquivo
+multipart; o wizard visual (Upload → Preview → Mapeamento → Validação →
+Normalização → Duplicados → Importação) descrito na especificação é UI,
+fase Frontend. Formato mínimo: cabeçalho com colunas `nome`/`telefone`
+(aceita `name`/`phone` também).
+
+Processamento em streaming/batches (`csv-import.ts`): parseia linha a
+linha (parser CSV mínimo, aceita campos entre aspas), valida telefone,
+detecta duplicado (dentro do próprio CSV E contra leads já existentes na
+campanha, num único `Set` carregado uma vez do banco — não uma query por
+linha), checa contra a lista de bloqueio do tenant, insere em lotes de
+1000 (`createMany`). Lead que bate na lista de bloqueio é importado como
+`DO_NOT_CALL`, não descartado — fica registrado, só não é discado depois
+(quando o motor existir, ele só vai selecionar `status = READY`).
+
+Retorna o resumo pedido pela secao 69: `{ total, valid, invalid,
+duplicates, imported, suppressed }`.
+
+## Lista de bloqueio (secao 71)
+
+CRUD simples (`/suppression`), tenant-scoped. A checagem obrigatória "antes
+de qualquer chamada" é responsabilidade de quem de fato origina (Predictive
+Engine) — aqui ela já é aplicada no momento da importação/criação de lead
+(marca como `DO_NOT_CALL` na hora, não pré-filtra o import).
+
+## Verificado ponta a ponta
+
+```
+POST /campaigns {queueId, trunkId, maxCps:2, daysOfWeek:[1..5], ...}
+  -> pacingMin > pacingMax rejeitado (400)
+  -> queueId inexistente no tenant rejeitado (400)
+
+POST /suppression {phone: "11988887777"}
+POST /campaigns/:id/leads/import (5 linhas: 1 invalida, 1 duplicada, 1 bloqueada)
+  -> {"total":5,"valid":3,"invalid":1,"duplicates":1,"imported":3,"suppressed":1}
+  -> lead bloqueado importado com status DO_NOT_CALL
+
+pause numa campanha DRAFT -> 400 "Nao e' possivel "pause" ... em status DRAFT"
+start -> RUNNING -> pause -> PAUSED -> drain -> DRAINING -> stop -> STOPPED
+start numa campanha STOPPED -> 400 (transição não permitida)
+delete numa campanha RUNNING -> 400 "Pare a campanha antes de apaga-la"
+
+3a campanha (plano trial, max_campaigns=2) -> 403 Quota excedida
+```
+
+## O que falta
+
+- `PredictiveDialerEngine` inteiro (secao 72-86): dados em tempo real
+  (agentes disponíveis/reservados/etc., secao 73), previsão de liberação
+  via EWMA (secao 74-75), cálculo de pacing (secao 76), CPS distribuído
+  via Redis (secao 77), reserva atômica de lead (`FOR UPDATE SKIP LOCKED`,
+  secao 78), lock de campanha com TTL/ownership/renewal (secao 79),
+  originate via `bgapi` (secao 80), state machine da chamada (secao 82),
+  controle de abandono (secao 84), regras de retry (secao 86).
+- Wizard visual de importação (upload de arquivo de verdade) — fase
+  Frontend.
+- Relatório de campanha (secao 160) — depende de CDR.
+- Quota de leads por campanha — não existe campo `max_leads` no Plan
+  (agente.md secao 56 não lista um); se vier a ser necessário, é uma
+  adição pequena ao Plan + `assertQuota`.

docs/ENTITLEMENTS.md

@@ -0,0 +1,94 @@
+# Plans / Entitlements
+
+Agente.md secao 56-62. Fase que ficou 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 pra FreeSWITCH sem essa
+peça, e toda fase desde então documentou "quota depende de Plans/
+Entitlements" como pendência (EXTENSIONS.md, TRUNKS.md, AGENTS.md,
+QUEUES.md). Esta fase fecha essa lacuna antes de avançar pra Campanhas, que
+dependem de `max_campaigns`, e pro CPS Limiter, que depende de `max_cps`/
+`max_concurrent_calls`.
+
+## Modelo
+
+`plans`: catálogo compartilhado entre tenants (não é tenant-scoped, sem
+RLS — é um "menu" de planos, não dado de um tenant específico). Campos de
+limite (`max_extensions`, `max_agents`, `max_trunks`, `max_queues`,
+`max_campaigns`, `max_cps`, `max_concurrent_calls`, `max_daily_calls`,
+`max_monthly_calls`, `max_recording_storage_gb`) são todos `Int?` — **null
+significa sem limite**, nunca "sem plano". Campos de feature flag
+(`recording_enabled`, `ai_enabled`, `ai_transcription_enabled`,
+`ai_analysis_enabled`, `api_access_enabled`) são booleanos.
+
+`tenants.plan_id` é **obrigatório** (nunca null) — agente.md secao 56 pede
+explicitamente pra não espalhar `if plan == PRO` pelo código; em vez disso,
+todo tenant sempre tem um Plan de verdade pra ler, e o código só lê
+limites, nunca checa "qual plano é esse".
+
+Migration `plans_campaigns_leads`: cria a tabela `plans`, insere um plano
+"trial" seed, faz backfill de `plan_id` pros tenants já existentes (havia
+2 tenants de teste no banco), só então torna a coluna `NOT NULL` — nessa
+ordem porque Postgres não deixa adicionar uma coluna `NOT NULL` sem default
+numa tabela não-vazia.
+
+## `packages/entitlements`
+
+Pacote novo, dedicado (mesmo padrão de `packages/telephony`/`packages/
+auth`). Duas funções:
+
+```typescript
+assertQuota(tenantId, key: QuotaKey, currentCount: number): Promise<void>
+// lança QuotaExceededError se currentCount >= limite do plano; no-op se o
+// campo for null (sem limite). Chamar ANTES de criar a linha.
+
+assertFeatureEnabled(tenantId, key: FeatureKey): Promise<void>
+// lança FeatureNotEnabledError se o plano não habilita o recurso.
+```
+
+`DomainExceptionFilter` (apps/api) mapeia os dois erros pra 403 — mesmo
+padrão já usado pra `InvalidCredentialsError`/`NotATenantMemberError`
+(erros de domínio simples, sem depender de NestJS, traduzidos pra HTTP só
+na borda).
+
+## Retrofit nos controllers existentes
+
+`ExtensionsController`, `TrunksController`, `AgentsController`,
+`QueuesController` e o novo `CampaignsController` agora contam as linhas
+ativas (`deletedAt: null`) antes de criar e chamam `assertQuota`. Sempre
+nessa ordem: contar → checar quota → só então criar — nunca criar e
+desfazer se estourar.
+
+## Plano seed: "trial"
+
+```
+max_extensions: 5      max_agents: 5       max_trunks: 2
+max_queues: 3          max_campaigns: 2    max_cps: 3
+max_concurrent_calls: 5
+max_daily_calls: 200   max_monthly_calls: 4000
+max_recording_storage_gb: 1
+recording_enabled: true, resto (ai_*) desabilitado
+```
+
+Números conservadores pra um plano de teste — o fluxo de "escolher/mudar de
+plano" de verdade é da fase Billing (secao 229).
+
+## Verificado ponta a ponta
+
+```
+POST /extensions x5  -> 201 (dentro do limite de 5)
+POST /extensions x6  -> 403 "Quota excedida: maxExtensions (limite do plano: 5)"
+
+POST /campaigns x2   -> 201 (dentro do limite de 2)
+POST /campaigns x3   -> 403 "Quota excedida: maxCampaigns (limite do plano: 2)"
+```
+
+## O que falta
+
+- Fluxo de escolha/upgrade de plano (fase Billing) — hoje todo tenant novo
+  nasce com "trial" via o mesmo default do backfill; não há endpoint pra
+  trocar de plano ainda.
+- `max_cps`/`max_concurrent_calls` só existem como campo lido — a
+  aplicação em tempo real (rejeitar originate além do limite) é da fase
+  CPS Limiter.
+- `max_daily_calls`/`max_monthly_calls`/`max_recording_storage_gb` — sem
+  nenhum consumidor ainda (dependem de CDR/Recording, fases futuras).

docs/EXTENSIONS.md

@@ -115,7 +115,7 @@ configurado) continua funcionando normalmente.
 
 ## O que falta
 
-- Quota de ramais (`max_extensions` do plano, secao 57) — depende da fase
-  Plans/Entitlements, que ainda não existe.
+- ~~Quota de ramais~~ — implementada na fase Plans/Entitlements (ver
+  docs/ENTITLEMENTS.md), `assertQuota` chamado antes de criar.
 - Tela "Telefonia → Ramais" (frontend) — fase Frontend, bem mais adiante.
 - Multi-domínio real por tenant (ver acima).

docs/QUEUES.md

@@ -79,4 +79,5 @@ DELETE /queues/:id
 - `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 (`max_queues`) — depende de Plans/Entitlements.
+- ~~Quota de filas~~ — implementada na fase Plans/Entitlements (ver
+  docs/ENTITLEMENTS.md), `assertQuota` chamado antes de criar.

docs/TRUNKS.md

@@ -92,7 +92,8 @@ Criei um trunk de teste apontando pra um host inexistente
 
 ## O que falta
 
-- Quota de troncos (`max_trunks`, secao 59) — depende de Plans/Entitlements.
+- ~~Quota de troncos~~ — implementada na fase Plans/Entitlements (ver
+  docs/ENTITLEMENTS.md), `assertQuota` chamado antes de criar.
 - `GET /trunks` não mostra `sofia status gateway` ao vivo, só o último
   status conhecido no banco — resolvido na fase Realtime Monitoring via
   WebSocket (ver docs/REALTIME.md).