B2BCall-dialer/docs/INBOUND_ROUTES.md

# Rotas de entrada (PHASE 56)

Pedido do usuário: "pode iniciar a montar o IVR e as rotas de entrada". A
investigação achou que **nenhuma chamada de tronco tinha como funcionar
hoje**, IVR ou não — esse documento cobre a fundação (rota por DID →
tenant); o IVR em si (menu com `play_and_get_digits`) é a próxima fase,
construída em cima disso.

## O achado real

Toda chamada originada de um ramal registrado ou de discagem de saída
carrega o channel variable `b2bcall_tenant_id` (setado por
`buildDirectoryUserXml`/originate do discador). **Uma chamada de ENTRADA
por tronco nunca carregava isso** — não existia nenhum mecanismo pra
identificar de qual tenant uma chamada de entrada é, então
`resolveDialplanXml` (`apps/freeswitch-config`) sempre devolvia
"not found" pra ela.

Pior: mesmo se essa variable existisse, o profile `external` do
FreeSWITCH (onde troncos recebem chamada) aponta pro contexto `public`
por padrão — um **arquivo estático** (`dialplan/public.xml`, vanilla).
Config estática sempre ganha de uma consulta ao `mod_xml_curl`, então
mesmo trocando a aplicação, esse contexto nunca seria dinâmico enquanto
se chamasse "public".

## O mecanismo

1. **`InboundRoute`** (nova tabela, tenant-scoped, RLS real) — cada linha
   é `didNumber` (o número que o provedor manda no INVITE) → `tenantId` +
   `destinationContext`/`destinationNumber` (pra onde a chamada cai
   dentro do dialplan do TENANT DONO). `didNumber` é `@unique` **global**
   — mesma exceção já aceita em `Tenant.telephonyDomain` (PHASE 50): é a
   ÚNICA forma de descobrir de qual tenant é uma chamada de entrada
   ANTES de saber o tenant.

2. **Dockerfile**: o profile `external` foi repontado de `context="public"`
   pra `context="inbound"` — um contexto sintético, sem nenhum arquivo
   estático, então toda chamada de entrada cai obrigatoriamente no
   `mod_xml_curl` (`b2bcall-fs-config`, binding já genérico pra qualquer
   contexto do section `dialplan`). `dialplan/public.xml` continua no
   disco, só não é mais alcançado por nenhum profile.

3. **`apps/freeswitch-config`**: quando `resolveDialplanXml` recebe uma
   requisição SEM `variable_b2bcall_tenant_id` e com `Caller-Context ==
   "inbound"`, lê `Caller-Destination-Number` (o DID discado) e faz
   fan-out sobre os tenants ativos (`withTenantContext` por tenant, nunca
   uma query sem contexto — `InboundRoute` tem `FORCE ROW LEVEL
   SECURITY` de verdade) até achar quem é dono do DID.

4. **`buildInboundRouteXml`** (`packages/telephony`) gera um XML de
   dialplan mínimo pro contexto `inbound`: `set b2bcall_tenant_id=<id>`,
   `set domain_name=<domínio do tenant>` (achado real testando com
   chamada de verdade — sem isso o `bridge
   data="user/${destination_number}@${domain_name}"` da regra "Discagem
   interna" resolvia pro domínio GLOBAL default, nunca pro do tenant,
   porque a leg de entrada não é um ramal registrado e nada preenche essa
   variable sozinho), e `transfer <destinationNumber> XML
   <destinationContext>`. O `transfer` dispara uma nova consulta de
   dialplan — agora já com `b2bcall_tenant_id` presente — reaproveitando
   100% do dialplan normal do tenant (a mesma regra "Discagem interna" já
   testada pro pickup de grupo, PHASE 53).

## Testado ponta a ponta com uma chamada real

Nenhum tronco PSTN real disponível neste laboratório — simulado com dois
softphones reais (`linphone-cli`) em containers Docker na mesma rede: um
registrado como ramal normal (`8001@acme.b2bcall.net`), outro discando
DIRETO pro profile `external` (porta 5080, sem registrar — exatamente
como um provedor de tronco manda uma chamada) um número (DID) cadastrado
numa `InboundRoute` apontando pra `8001`. Confirmado via `show channels`:
a chamada de entrada resolveu o tenant certo, transferiu pro contexto
`default` do tenant, bridged com o `user/8001@acme.b2bcall.net` (domínio
correto, não o global) e ficou `ACTIVE` com codec PCMU negociado nos dois
lados — ramal tocou, atendeu, áudio bidirecional confirmado.

(Tentativa inicial usando `originate loopback/.../inbound &park()` como
simulação deu `INCOMPATIBLE_DESTINATION`/488 — isolado como limitação do
canal `loopback` (sem SDP/codec real negociado), não um bug da resolução:
confirmado testando a mesma resolução com destino simples
`answer`+`playback` via loopback (sucesso) e depois com uma chamada SIP
de verdade ponta a ponta (sucesso completo, áudio incluído).)

## IVR (PHASE 56, construído em cima da fundação acima)

`play_and_get_digits` adicionado ao `ALLOWED_DIALPLAN_APPLICATIONS` — só
coleta dígitos numa variable, nunca executa nada, mesmo risco zero dos
outros já permitidos. `ALLOWED_CONDITION_FIELDS` ganhou um segundo modo:
além dos 6 campos fixos, aceita um `${variavel}` simples (regex exige
identificador puro, sem parênteses — nunca bate com `${funcname(...)}`,
então o mesmo risco de RCE já fechado pra `data` não se aplica aqui).

**Achado real construindo o primeiro menu de teste**: FreeSWITCH resolve
TODAS as `<condition>` de um contexto (decide quais `<extension>`
batem) ANTES de executar qualquer `<action>` — variables setadas por uma
action (como o dígito que `play_and_get_digits` guarda) NUNCA afetam o
casamento de outras `<extension>` no MESMO contexto/mesma passada
("Uma condição por extension" já era uma simplificação deliberada desta
implementação, mas mesmo o FreeSWITCH puro com múltiplas `<condition>`
por extension só re-avalia a PRÓXIMA condição da MESMA extension, não
outras extensions). Confirmado testando com DTMF de verdade: duas
extensions separadas (`IVR entrada` fazendo `play_and_get_digits`, `IVR
opcao 1`/`opcao 2` checando `${ivr_choice}`) NUNCA bateu — o regex era
avaliado com a variable ainda vazia.

**A forma que funciona**: dentro da MESMA extension que colheu o dígito,
um `transfer` explícito usando o valor coletado como novo
`destination_number` — `transfer data="${ivr_choice} XML
<mesmo-contexto>"`. `transfer` dispara uma consulta de dialplan
COMPLETAMENTE NOVA (nova passada de parse, variables já setadas
persistem), então as extensions seguintes podem casar por
`destination_number` normal (`^1$`, `^2$`, ...) — nem precisa do
widening de `${variavel}` pra ISSO especificamente (mas o widening
continua útil/correto de se ter, por exemplo pra decisões dentro de uma
única extension com múltiplas conditions no futuro).

Testado ponta a ponta com DTMF de verdade (`fs_cli uuid_recv_dtmf` —
`linphonec` não tem comando de enviar DTMF interativo, então a
verificação usa a API do FreeSWITCH que simula o dígito chegando como
input do chamador, o mesmo caminho que RFC2833/inband usaria): softphone
externo liga pro DID → IVR atende, toca prompt, espera dígito →
dígito `1` → bridge com ramal real registrado (atendeu, áudio PCMU
bidirecional confirmado); dígito `2` → resposta alternativa (tom
diferente + desliga) — confirma que a ramificação distingue de verdade,
não só "sempre cai na primeira opção".

## Tela de autoria de IVR (PHASE 58)

`Telefonia > IVR` (`apps/frontend/.../telefonia/ivr`) — cria um `IvrMenu`
(nome + contexto derivado do nome) com opções (dígito → ramal + rótulo
opcional), sem precisar tocar no editor genérico de dialplan. Por baixo,
`IvrMenusController` (`POST/PATCH/DELETE /ivr-menus`) compila o menu +
opções em `buildIvrDialplanExtensions` (`packages/telephony/src/ivr-xml.ts`)
e já gera + ativa uma nova versão do dialplan do contexto — o mesmo fluxo
generate+activate manual, automático. `IVR_ENTRY_DESTINATION`
("ivr_entry") é o valor fixo que toda `InboundRoute` precisa usar como
`destinationNumber` pra entrar nesse menu (`destinationContext =
IvrMenu.context`).

`greeting` (o prompt tocado ao entrar) passa pela MESMA proteção
anti-RCE de `data` de dialplan (`IsSafeDialplanData`) — é texto livre do
tenant, nunca pode virar `${system(...)}`. Sem pipeline de upload/TTS de
áudio ainda: null usa um tom padrão; texto livre vira o argumento `file`
de `play_and_get_digits` (aceita qualquer caminho/URL que o FreeSWITCH
já resolva, incluindo `tone_stream://`).

Testado ponta a ponta criando um menu de verdade via API (não só
lendo XML manualmente escrito): softphone externo discou o DID, o menu
recém-criado atendeu, tocou o prompt, colheu o dígito com DTMF real
(`uuid_recv_dtmf`), e bridged com o ramal certo — confirmando que o
compilador produz XML funcionalmente idêntico ao testado manualmente na
PHASE 56.

## Upload de áudio pro prompt (PHASE 59)

`POST /ivr-menus/:id/prompt` (multipart, campo `file`) — só aceita WAV
(cabeçalho RIFF/WAVE validado antes de gravar; sem `mod_shout` nesta
implantação, MP3 nunca funcionaria mesmo). Gravado num bind mount NOVO
compartilhado com o container do FreeSWITCH (`./data/ivr-prompts` no
host ↔ `/ivr-prompts` no container) — mesmo raciocínio já usado pras
gravações de chamada (`./data/recordings-spool`), mas na direção
contrária: aqui é `apps/api` (host) que ESCREVE e o FreeSWITCH que LÊ.
Um fetch em rede (S3/HTTP) durante uma chamada ativa foi descartado de
propósito — latência/confiabilidade desnecessárias pra um prompt de
poucos segundos, e esta é a MESMA convenção já usada 3x neste projeto
pra arquivos que o FreeSWITCH precisa enxergar (gateways externos, filas
do callcenter, spool de gravação).

`greeting` passa a guardar o path como o FreeSWITCH enxerga
(`/ivr-prompts/<tenantId>/<menuId>.wav`), nunca o path do host.
`GET /ivr-menus/:id/prompt` (autenticado, `ivr.view`) serve o preview —
mesmo princípio do player de gravações, nunca uma URL direta pro
storage/disco. Deletar o menu ou trocar/remover o prompt sempre limpa o
arquivo do disco (nunca deixa órfão).

Testado ponta a ponta com um WAV real de 44.1kHz/mono (não o formato
"nativo" de telefonia, de propósito — pra confirmar que funciona com o
que uma pessoa qualquer gravaria/exportaria): softphone externo discou
o DID, `play_and_get_digits` abriu e tocou o arquivo até o fim duas
vezes (`mod_sndfile` resample automático, sem erro no log), colheu o
dígito real e bridged corretamente com o ramal de destino.

## Editor visual (PHASE 60)

`apps/frontend/.../telefonia/ivr/ivr-flow-editor.tsx` — canvas de nós e
setas (`@xyflow/react`) em cima do MESMO modelo de sempre (entrada +
opções por dígito), sem nenhuma dependência de execução externa. Um nó
"Entrada" fixo conectado a um nó por opção (dígito + select de ramal +
descrição, editável direto no nó); "Adicionar opção"/"Salvar alterações"
chamam o mesmo `PATCH /ivr-menus/:id` que já existia. Avaliado (e
descartado por enquanto, ver AskUserQuestion desta sessão) integrar
Node-RED de verdade: seria uma plataforma externa completa (motor de
execução próprio, nós "function" = RCE, sem multi-tenancy nativa) —
esforço de vários dias e superfície de risco nova, não um ajuste na tela
atual. Um editor visual próprio, sobre o backend já existente, entrega o
mesmo valor imediato (ver estrutura do menu como grafo, editar visualmente)
sem essas duas desvantagens.

Testado ponta a ponta pela tela de verdade: menu criado, prompt de voz
real enviado (WAV sintetizado com `espeak-ng`, não um tom sintético),
uma segunda opção adicionada via `PATCH` (mesma chamada que o botão
"Salvar" do editor visual faz) — confirmado no banco que a versão 2 do
dialplan compilou as duas opções corretamente, superando a versão 1.

### Posição dos nós persiste entre recargas (PHASE 61)

`IvrMenu.entryPositionX/Y` + `IvrMenuOption.positionX/Y` (nullable,
puramente de apresentação — nunca entram no dialplan compilado). Salvos
no banco (nunca `localStorage`, mesma convenção do resto do app: estado
compartilhado entre quem quer que edite o tenant, não por navegador) a
cada "Salvar alterações" — o editor lê a posição de verdade do estado de
nós do `@xyflow/react` (reflete arrastos feitos na sessão), não do
estado de conteúdo das opções. Sem posição salva (menu novo, opção
recém-adicionada), cai num layout automático em coluna. Testado ponta a
ponta: `PATCH` com coordenadas específicas, `GET` de volta confirma os
mesmos valores, e a página carregada de novo (SSR) já embute essas
coordenadas nos props iniciais do componente.

## Dropdown de destino: ramal, IVR, fila ou grupo (PHASE 62)

Achado real reportado pelo usuário: o destino de uma rota de entrada era
um campo de texto livre — sem dropdown, e (descoberto construindo o
dropdown) fila/grupo nunca tinham sido implementados de verdade como
destino possível, só ramal/IVR funcionavam.

`InboundRoute.destinationType` (novo enum: `EXTENSION`/`IVR`/`QUEUE`/
`CALL_GROUP`) decide como `buildInboundRouteXml` interpreta o destino:

- **EXTENSION/IVR**: comportamento inalterado — `transfer` pro contexto
  do tenant, reaproveitando o dialplan já testado (PHASE 56/58).
- **QUEUE**: `destinationNumber` guarda o `Queue.id`. A resolução de
  entrada emite `answer` + `callcenter data="<queueId>@<domain>"`
  direto — nunca passa pelo dialplan "default" nem precisa de nenhuma
  regra nova lá. `callcenter` entrou no allowlist de applications
  (`packages/telephony/src/dialplan-xml.ts`) com o mesmo risco zero de
  `pickup` — só recebe `<queueId>@<domain>` como texto.
- **CALL_GROUP**: `destinationNumber` guarda o valor de
  `Extension.callGroup`. A resolução de entrada consulta AGORA (nunca um
  snapshot salvo na criação da rota) todos os ramais do tenant com esse
  `callGroup` e emite `bridge` com uma leg por ramal
  (`user/A@domain,user/B@domain,...`) — toca todos ao mesmo tempo, quem
  atender primeiro cancela os outros (ring group de verdade). Trocar
  quem está no grupo depois de criar a rota já vale na PRÓXIMA chamada,
  sem precisar re-salvar nada — a query roda a cada chamada de entrada,
  não uma vez só.

Testado ponta a ponta com chamadas reais nos 2 mecanismos novos: fila —
softphone externo discou o DID, `show channels` confirmou a chamada
dentro da application `callcenter` com o nome certo da fila; grupo — 2
ramais reais registrados no mesmo `callGroup`, a chamada tocou nos DOIS
ao mesmo tempo (mesmo `call_uuid`, ambas as legs `RINGING`), atender em
um cancelou o outro automaticamente.

Tela "Rotas de Entrada": "Tipo de destino" (Ramal/IVR/Fila/Grupo de
ramais) + um segundo dropdown listando as opções reais do tenant pra
cada tipo (ramais cadastrados, menus de IVR, filas, ou os valores
distintos de `callGroup` já usados em algum ramal).

## Dropdown de destino numa opção de IVR: ramal, fila ou outro IVR (PHASE 67)

Mesmo gap da seção acima, um nível abaixo: até aqui, uma OPÇÃO dentro de
um menu de IVR só sabia apontar pra ramal (`bridge` fixo). Rota de
entrada já suportava fila/grupo pra ENTRAR num menu, mas depois de
entrar, cada dígito só discava um ramal.

`IvrMenuOption.destinationType` (novo enum próprio,
`IvrOptionDestinationType`: `EXTENSION`/`QUEUE`/`IVR`) decide a action de
cada branch em `buildIvrDialplanExtensions` (packages/telephony), mesmo
padrão do `InboundRoute` acima:

- **EXTENSION**: inalterado — `bridge` direto pro ramal.
- **QUEUE**: `answer` + `callcenter data="<queueId>@<domain>"`.
- **IVR**: `transfer` pro `IVR_ENTRY_DESTINATION` do contexto do MENU
  ALVO — reaproveita a mesma entrada que uma `InboundRoute` usa pra
  entrar num IVR, então um menu vira efetivamente um sub-menu de outro.

**Sem `CALL_GROUP` aqui, de propósito** (diferente de `InboundRoute`,
que tem os 4 tipos): o dialplan de um IVR é compilado UMA VEZ, ao salvar
o menu (`compileAndActivateIvrDialplan`) — não resolvido a cada chamada
como a resolução de `InboundRoute`. Um destino `CALL_GROUP` ficaria
"quem estava no grupo no momento em que o menu foi salvo por último",
uma defasagem silenciosa que ninguém pediu — melhor não oferecer do que
oferecer errado.

**Ciclos**: "Outro IVR" cria a primeira forma de um menu apontar pra
outro (uma `InboundRoute` nunca é ela mesma um menu, então nunca podia
formar ciclo). `assertNoIvrCycle` (`ivr-menus.controller.ts`) monta o
grafo com todos os menus do tenant antes de compilar e rejeita (409)
qualquer save que criaria um ciclo (A→B→A, ou até A apontando pra si
mesmo) — checado tanto em `create` quanto `update`.

Os dois editores de IVR (form clássico e o editor visual de nós, PHASE
60/61) ganharam o mesmo par de dropdowns "Tipo"/"Destino" já usado em
Rotas de Entrada. Testado ponta a ponta: menu A com opção tipo Fila,
menu B com opção tipo Outro IVR apontando pro menu A — os dois
persistiram certo depois de um reload completo da página.

## O que falta

- Sem TTS (texto→voz) — só upload de arquivo WAV já gravado.
- Grupo de ramais só é alcançável por Rota de Entrada — não existe (e
  não foi pedido) um jeito de discar um grupo de dentro do próprio
  dialplan "default" via feature code.
- Perda das proteções de toll-fraud do `public.xml` vanilla (unroll de
  loop de chamada, etc.) — não replicadas no contexto `inbound` novo.
  Aceitável pra esta fase (sem trunks reais ainda), mas revisar antes de
  conectar um provedor PSTN de verdade.