B2BCall-dialer/docs/AGENTS.md

Agentes, Tiers e Pausas

Agente.md secao 45-49 e 52. Completa o Call Center: depois desta fase, um usuário autenticado consegue logar como agente, entrar numa fila real, se pausar e voltar — tudo refletido de verdade no FreeSWITCH.

Modelo

• agents (tenant-scoped, RLS): liga User (login) → Extension (ramal SIP) → identidade de agente (User/Agent/Extension separados, agente.md secao 45). state espelha o estado real (secao 46), nunca escrito direto pela API — só via login/logout/pause/resume.
• tiers: Queue↔Agent (secao 52) — level/position espelham 1:1 o mod_callcenter.
• agent_sessions: uma linha por ciclo login→logout.
• agent_state_events: histórico de transições de estado (auditoria).
• pause_reasons/agent_pause_events (secao 48).

Mecanismo: 100% dinâmico, sem arquivo

Confirmado na fase anterior (Queues) via help callcenter_config: agentes e tiers não têm representação em XML — só comandos ESL diretos (agent add/del/set status/set contact, tier add/del). Isso muda o padrão de sincronização: em vez de "regenerar todos os arquivos" (Trunks/Queues), apps/api publica uma mensagem por ação, com payload ({tenantId, agentId, action} em b2bcall:agents:sync; {tenantId, queueId, agentId, level, position, action} em b2bcall:tiers:sync) — b2bcall-fs-config recebe e aplica o comando correspondente.

Achados reais confirmados manualmente antes de codar

Rodei cada comando contra o FreeSWITCH real antes de escrever qualquer lógica de sync (mesmo método usado nas fases anteriores):

• agent add em cima de um agente que já existe: erro ("Agent already exist!") — não é idempotente. tier add duplicado: mesmo erro ("Tier already exist!"). Ambos capturados e ignorados no sync (.catch(() => undefined)), já que essa condição é esperada em qualquer resync.
• tier del/agent del em algo que não existe: não dá erro (+OK) — seguro chamar sem checar existência antes.
• agent set status só aceita 3 valores exatos: Available, On Break, Logged Out — qualquer outro string dá -ERR Invalid Agent Status! (testado deliberadamente). Os estados derivados de chamada do nosso enum (RESERVED/RINGING/IN_CALL/WRAP_UP) não têm status próprio no mod_callcenter — mapeiam pra "Available" (só o state, campo separado, muda sozinho conforme a chamada progride — não escrevemos isso).
• Achado de corrida real, visto ao testar o fluxo completo: como um agente só passa a existir no FreeSWITCH no login (agent add roda ali, não na criação do registro Agent), atribuir um tier (POST /queues/:id/agents) antes do primeiro login do agente falha silenciosamente do lado do FreeSWITCH (-ERR Agent not found!, logado mas não propagado como erro HTTP). Por isso o login sempre re-sincroniza todos os tiers do agente depois de garantir que ele existe — a auto-correção aconteceu exatamente assim no teste real.

Fluxo de login (agente.md secao 47)

POST /agents/me/login
  → valida usuário (JWT) e ramal (Agent.extensionId precisa existir)
  → cria agent_session
  → agent add (idempotente via catch) + set contact (dial-string do ramal)
  → set status Available
  → re-sincroniza todos os tiers do agente
  → Agent.state = AVAILABLE

POST /agents/me/logout|pause|resume seguem o mesmo padrão — sempre sobre o agente do próprio usuário autenticado (nunca um agentId arbitrário do client, mesmo princípio de nunca confiar em tenant_id/ids sensíveis vindo do frontend sem checar contra o JWT).

Verificado ponta a ponta

POST /extensions {"number":"2000",...}
POST /agents {userId, extensionId, name}
POST /queues {"name":"Suporte"}
POST /queues/:queueId/agents {agentId}          → tier add falha (agente ainda nao existe)
POST /agents/me/login                            → agent add + contact + status Available
                                                  → tier re-sync (dessa vez funciona)

callcenter_config agent list
→ status=Available, contact={ignore_early_media=true}user/2000@b2bcall.local ✓
callcenter_config tier list
→ queue|agent com state=Ready ✓

POST /agents/me/pause {pauseReasonId}  → status=On Break ✓
POST /agents/me/resume                 → status=Available ✓
POST /agents/me/logout                 → status=Logged Out ✓

Todos os 4 estados confirmados batendo entre o banco (Agent.state) e o FreeSWITCH (agent list).

O que falta

• Estados derivados de chamada (RINGING, IN_CALL, WRAP_UP, RESERVED) — dependem de callcenter::info (CUSTOM event), que ainda não foi provado funcionando nesta sessão (mesma lacuna de sofia::gateway_state documentada em docs/TRUNKS.md). Não implementado; precisa de uma chamada real passando pela fila pra testar.
• Tela do agente (secao 49) — fase Frontend.
• Monitoramento de filas/ramais em tempo real (secao 54-55) — depende de WebSocket multi-tenant.
• Quota de agentes (max_agents) — depende de Plans/Entitlements.
• PauseReason.maxDuration existe no modelo mas não é aplicado automaticamente ainda (ninguém força o fim da pausa ao expirar).