B2BCall-dialer/docs/ENTITLEMENTS.md

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:

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).