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
122 lines
5.8 KiB
Markdown
122 lines
5.8 KiB
Markdown
# Extensions (Ramais)
|
|
|
|
Primeira fase que dá dado real de negócio ao FreeSWITCH via `mod_xml_curl`
|
|
(agente.md secao 39-40, 178).
|
|
|
|
## Modelo
|
|
|
|
`extensions` (tenant-scoped, RLS — mesmo padrão de `tenant_memberships`):
|
|
`number`, `name`, `domain`, `sip_password_enc`, `caller_id_name/number`,
|
|
`context`, `sofia_profile`, `codecs`, `max_registrations`, `enabled`.
|
|
`UNIQUE(tenant_id, number)` — números só precisam ser únicos dentro do
|
|
tenant (secao 34).
|
|
|
|
## Senha SIP (secao 178)
|
|
|
|
- Gerada com `generateStrongPassword()` (24 caracteres alfanuméricos,
|
|
`crypto.randomBytes`).
|
|
- Cifrada em repouso com AES-256-GCM (`packages/shared/src/crypto.ts`),
|
|
chave em `ENCRYPTION_KEY` (.env, 32 bytes hex) — nunca no PostgreSQL.
|
|
- **Só aparece em texto puro na resposta do `POST /extensions`, uma única
|
|
vez.** `GET`/`list` nunca devolvem `sipPasswordEnc` nem a senha — a função
|
|
`toPublicExtension()` faz destructuring explícito do campo (não spread) pra
|
|
garantir isso é removido de fato, não só "esquecido" no tipo TypeScript.
|
|
|
|
## API (`apps/api/src/extensions`)
|
|
|
|
```
|
|
POST /extensions extensions.manage cria (gera+cifra senha, devolve 1x)
|
|
GET /extensions extensions.view lista (sem senha)
|
|
GET /extensions/:id extensions.view detalhe (sem senha)
|
|
DELETE /extensions/:id extensions.manage soft delete (deletedAt + enabled=false)
|
|
```
|
|
|
|
Novo `PermissionGuard` genérico (`@RequirePermission('extensions.manage')`)
|
|
— roda depois do `JwtAuthGuard`, exige tenant selecionado no JWT (nunca
|
|
aceita tenant_id do client) e chama `userHasPermission()` de `packages/auth`.
|
|
|
|
**Achado real durante os testes**: o `PermissionGuard` injeta `Reflector` via
|
|
construtor — padrão documentado do NestJS. Rodando via `tsx` (esbuild), o
|
|
`reflector` chegava `undefined` em runtime (`TypeError: Cannot read
|
|
properties of undefined`), porque esbuild não faz emissão de
|
|
`design:paramtypes` com checagem de tipos completa entre arquivos (limitação
|
|
conhecida do esbuild, diferente do `tsc`). Resolvido com `@Inject(Reflector)`
|
|
explícito no construtor. Isso é um risco real pra qualquer guard/serviço
|
|
futuro que dependa de injeção implícita de tipo — **usar `@Inject()`
|
|
explícito sempre que o dev/runtime for via `tsx`**, ou considerar migrar
|
|
`apps/api` pra build real (`tsc`) mais adiante.
|
|
|
|
**Atualização (fase Dialplan)**: esse "considerar migrar" virou obrigatório
|
|
— o mesmo problema de metadata do esbuild também desativava silenciosamente
|
|
o `ValidationPipe` inteiro (sem crash, sem log, só aceitando qualquer
|
|
entrada). `apps/api` agora sempre builda com `tsc` antes de rodar. Ver
|
|
docs/VALIDATION_PIPE_BUG.md.
|
|
|
|
## `b2bcall-fs-config` agora responde directory de verdade
|
|
|
|
Fluxo `section === "directory"`:
|
|
|
|
1. `Tenant.findFirst({ telephonyDomain: domain, status: "ACTIVE" })` — tenants
|
|
não são RLS-protected (é o registro da plataforma).
|
|
2. `withTenantContext(tenant.id) → Extension.findFirst({ number: user, enabled: true })`.
|
|
3. `buildDirectoryUserXml()` (`packages/telephony`) monta o XML, incluindo
|
|
`b2bcall_tenant_id`/`b2bcall_extension_id` como channel variables (secao 81
|
|
— assim qualquer chamada desse ramal já carrega a origem).
|
|
|
|
**Achado real**: a primeira versão do XML não incluía o bloco
|
|
`<domain><params><param name="dial-string".../></params></domain>` que a
|
|
config vanilla tem em `directory/default.xml`. Sem isso, `originate
|
|
user/1500 &park()` falhava com `MANDATORY_IE_MISSING` em vez do
|
|
`USER_NOT_REGISTERED` esperado — o FreeSWITCH não sabia montar o dialstring
|
|
pro endpoint `user/`. Corrigido copiando o mesmo template de `dial-string` da
|
|
config vanilla.
|
|
|
|
## `$${domain}` fixo
|
|
|
|
`Tenant.telephonyDomain` precisa bater com o que o FreeSWITCH manda como
|
|
`domain` no POST do xml_curl. Por padrão, a config vanilla usa
|
|
`domain=$${local_ip_v4}` — o IP do container, que muda a cada restart e
|
|
nunca seria estável o suficiente pra configurar em um tenant. Corrigido no
|
|
`Dockerfile` do FreeSWITCH com um `sed` fixando `$${domain}` pra
|
|
`b2bcall.local` (configurável via `ARG DEFAULT_SIP_DOMAIN`). Multi-domínio
|
|
real por tenant (múltiplos domínios simultâneos, um por tenant) ainda não
|
|
está resolvido — hoje só suporta um domínio fixo pra todos; isso é uma
|
|
limitação genuína a resolver quando existir gestão de domínio por tenant de
|
|
verdade (fora do escopo desta fase).
|
|
|
|
## Verificado ponta a ponta
|
|
|
|
```bash
|
|
POST /extensions {"number":"1500","name":"Ramal de Teste"} # 201, senha aparece 1x
|
|
GET /extensions/:id # confirma senha nunca reaparece
|
|
|
|
# fs-config resolve com a senha certa (decifrada corretamente):
|
|
curl -d "section=directory&user=1500&domain=b2bcall.local" http://fs-config:8080/
|
|
|
|
# FreeSWITCH:
|
|
originate user/1500 &park() # USER_NOT_REGISTERED (achou o ramal, sem telefone registrado)
|
|
originate user/1501 &park() # SUBSCRIBER_ABSENT (nao existe)
|
|
|
|
DELETE /extensions/:id
|
|
originate user/1500 &park() # volta a SUBSCRIBER_ABSENT
|
|
```
|
|
|
|
## Autenticação HTTP `fs-config` ↔ FreeSWITCH
|
|
|
|
Adicionada nesta mesma fase (assim que o serviço passou a devolver dados
|
|
reais, deixou de ser opcional): HTTP Basic, credenciais em `FS_CONFIG_USER`/
|
|
`FS_CONFIG_PASSWORD` (.env, geradas com `openssl rand`). FreeSWITCH manda via
|
|
`gateway-credentials` em `xml_curl.conf.xml` (substituído em runtime pelo
|
|
`entrypoint.sh`, mesmo padrão do `ESL_PASSWORD` — nunca fica na imagem).
|
|
`fs-config` compara com `timingSafeEqual` (evita timing attack), libera só
|
|
`/health` sem auth (usado pelo healthcheck do Docker). Verificado: requisição
|
|
sem credenciais recebe 401; o FreeSWITCH (com `gateway-credentials`
|
|
configurado) continua funcionando normalmente.
|
|
|
|
## O que falta
|
|
|
|
- ~~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).
|