b2bcall/docs/TROUBLESHOOTING.md

B2BCall — Troubleshooting

Problemas reais encontrados durante o desenvolvimento deste projeto e como foram diagnosticados/resolvidos — mantido como referência para o futuro.

Softphone não registra ("timeout")

Sintoma: usuário criou um ramal, colocou usuário/senha num softphone real e o registro dava timeout (sem resposta nenhuma do servidor).

Causa raiz nº 1 — firewall: nftables bloqueava incondicionalmente SIP (5060/udp) e RTP (10000-20000) vindos da interface LAN (ens18) — regra criada na Fase 2 como proteção, mas que também bloqueia qualquer uso real, já que o OpenSIPS que ficaria na frente (docs/OPENSIPS.md) nunca foi implantado. Diagnosticado direto pelo contador da regra: nft list table inet b2bcall_fw mostrando udp dport 5060 ... drop com contador subindo a cada tentativa. Fix: liberar SIP/RTP para origem RFC1918 (rede privada), mantendo AMI/ARI sempre bloqueados — ver docs/SECURITY.md.

Causa raiz nº 2 — depois de liberar o firewall, "Failed to authenticate": o usuário estava digitando a senha de login web (a do admin@b2bcall. local) no campo de senha do softphone, em vez da senha SIP do próprio ramal (que é uma credencial completamente diferente, gerada por ramal). Confirmado ativando pjsip set logger on e vendo o REGISTER chegando e falhando na autenticação. Lição: deixar claro na interface (ou pelo menos na documentação) que são dois sistemas de credenciais distintos — fácil de confundir porque os dois são "a senha que o sistema gerou".

Melhoria feita por causa disso: antes, a única forma de recuperar uma senha SIP esquecida era resetá-la (invalidando a anterior). Agora dá para ver e editar a senha SIP diretamente no formulário de edição do ramal (GET /extensions/:id/password, decifra sob demanda) — diferente da senha de login (hash argon2id, irreversível por design), a senha SIP é cifrada (reversível) porque o próprio Asterisk precisa dela em texto puro para autenticar.

"Body cannot be empty when content-type is set to 'application/json'" em quase todo botão de ação

Sintoma: usuário real testando no navegador (não curl) relatou erro "body is empty" ao clicar em redefinir senha de um ramal. Investigação mostrou que o mesmo bug afetava todo botão de ação sem payload: disponibilizar agente, pausar/despausar, publicar dialplan, iniciar/ pausar/parar campanha, etc.

Causa: o cliente HTTP central do frontend (apps/frontend/src/lib/api-client.ts) sempre enviava Content-Type: application/json mesmo em requisições sem corpo. O Fastify rejeita isso com 400 antes de a requisição chegar ao controller — o @Body() do NestJS nem entra em cena, o parser de body do Fastify já barra antes.

Por que passou despercebido por tanto tempo: todo teste de API deste projeto, em toda fase anterior, foi feito via curl — e curl -X POST sem -H 'Content-Type: ...' e sem -d não define esse header. O fetch() do navegador (usado pelo cliente HTTP real do frontend) sempre define o header por padrão. Ou seja: testar só via curl não teria pegado nunca esse bug — só apareceu quando um usuário de verdade clicou em botões reais no navegador. Lição: curl prova que o backend funciona: não prova que o frontend consegue falar com ele.

Fix: só incluir o header Content-Type quando body !== undefined, na única função request() usada por get/post/patch/delete.

Bug relacionado, achado na mesma revisão: DELETE /api/suppression/:id exige removalReason no corpo, mas api.delete() nem aceitava um argumento de corpo — o botão "Desbloquear" da lista de bloqueio sempre falhava com 403. Mesma causa raiz (função de ação sem forma de levar payload), mesmo tipo de bug que só um clique real revela.

"Argument calledNumber is missing" ao originar chamada

Sintoma: PrismaClientValidationError ao reservar um lead, mesmo a query SQL parecendo correta.

Causa: $queryRaw do Prisma não aplica o mapeamento camelCase automático que findMany/update aplicam — colunas retornadas por SQL cru mantêm o nome exato da coluna (phone_normalized, não phoneNormalized).

Fix: sempre usar alias explícito no SQL: phone_normalized AS "phoneNormalized". Ver apps/dialer-worker/src/lead-repository.ts.

Pacing do discador oscilando/nunca parando de subir mesmo sem atividade

Sintoma: no cenário de teste da seção 66 (20 agentes/10 CPS/30% taxa de atendimento), o pacingFactor continuava subindo mesmo em períodos ociosos, gerando concorrência muito acima do esperado.

Causas (três, compostas):

1. O cálculo de concorrência total não incluía chamadas já conectadas ao agente (agentConnectedCalls), subestimando quanto já estava "em uso".
2. O ajuste de pacing subia mesmo sem nenhuma atividade de discagem no ciclo (nada "deu errado", então ele interpretava como "pode subir mais").
3. Uma única iteração fechava 100% da diferença entre o alvo e o atual, causando overshoot.

Fix: agentConnectedCalls entra no total de concorrência; pacing nunca sobe durante ociosidade (hasActivity gate); fechamento de gap limitado a 50% por ciclo (RAMP_FRACTION); e dampening por raiz quadrada do próprio pacingFactor. Ver apps/dialer-worker/src/predictive-engine.ts e docs/PREDICTIVE_DIALER.md.

AMI: comando Command não retorna o output esperado

Sintoma: parsing manual do protocolo AMI para a action Command (usada por diagnóstico) não batia com a documentação legada (Response: Follows / --END COMMAND--).

Causa: o Asterisk 22 usa um formato diferente para Command: múltiplos headers Output: repetidos, um por linha de saída — não o bloco Follows/END COMMAND de versões antigas.

Fix: reverse-engineering via socket TCP cru (script de debug dedicado) para confirmar o formato real antes de implementar o parser em packages/telephony.

Erro de sintaxe no schema.prisma: @default(1_000_000)

Sintoma: prisma generate falha com erro de parsing.

Causa: separador de milhar com underscore (1_000_000) não é suportado na sintaxe do .prisma — é um recurso de JS/TS, não do DSL do Prisma.

Fix: escrever o número sem separadores: 1000000.

Prisma.InputJsonValue rejeita instância de DTO

Sintoma: Index signature for type 'string' is missing ao passar um objeto DTO diretamente para um campo Json do Prisma (ex.: AuditLog.after).

Causa: uma instância de classe (mesmo com os campos certos) não satisfaz a assinatura de índice que InputJsonValue exige — só um objeto literal simples satisfaz.

Fix: espalhar em um objeto literal: after: { ...dto } em vez de after: dto.

Redis: agentes travados em IN_CALL para sempre

Sintoma: depois de uma chamada, o agente nunca voltava a AVAILABLE.

Causa: o "claim" de agente disponível só marcava IN_CALL na conexão — não havia nenhum mecanismo simétrico de liberação após o fim da chamada.

Fix: agent-call-binding.ts#releaseAgentAfterCall, chamado explicitamente quando a chamada termina, com suporte a WRAP_UP intermediário antes de AVAILABLE.

Corrida entre duas campanhas reivindicando o mesmo agente

Sintoma (encontrado em revisão de código, não em produção): implementação inicial de claimAvailableAgent usava findFirst + update separado — janela de corrida entre duas campanhas concorrentes.

Fix: reescrito com UPDATE ... WHERE id = (SELECT ... FOR UPDATE SKIP LOCKED LIMIT 1) RETURNING ..., mesmo padrão atômico já usado para reserva de leads.

Diagnóstico geral

Para qualquer problema não listado acima:

1. bash scripts/healthcheck.sh — descarta problema de infraestrutura básica primeiro.
2. docker compose logs -f <serviço> — logs estruturados JSON, procurar por "level":50 (error) ou "level":40 (warn).
3. docker exec b2bcall-asterisk asterisk -rx "..." — ver docs/ASTERISK.md para comandos úteis.
4. Consultar AuditLog (GET /api/audit) se o problema envolve uma ação específica de um usuário.
5. Verificar docker compose ps — um container "unhealthy" quase sempre aponta a causa raiz de problemas em cascata nos serviços que dependem dele.