Matheus
7b62ad3d82
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
95 lines
3.9 KiB
Markdown
95 lines
3.9 KiB
Markdown
# 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).
|