B2BCall-dialer/docs/REALTIME.md

Monitoramento em tempo real (WebSocket)

Agente.md secao 54-55 (filas/ramais) e 161 (WebSocket multi-tenant). Esta fase entrega a infraestrutura de push em tempo real — o consumo visual ("Monitoramento → Filas/Ramais", cards coloridos) fica pra fase Frontend.

Requisito central: tenant-scoped no servidor

Secao 161: "Não transmitir tudo e filtrar somente no browser." O gateway (apps/api/src/realtime/realtime.gateway.ts) só tem um ponto de emissão, broadcastToTenant(), e ele sempre usa server.to(room) — nunca server.emit() global. Cada socket só entra na room do próprio tenant (tenant:<tenantId>) na conexão, nunca escolhe a room ele mesmo.

Autenticação na conexão

Socket.io não usa headers HTTP como uma request REST — o client manda o access token em socket.handshake.auth.token (não em Authorization). RealtimeGateway.handleConnection:

1. Rejeita (disconnect(true)) se não tiver token.
2. Valida o JWT (verifyAccessToken, mesmo helper usado no JwtAuthGuard).
3. Exige tenantId no token (mesmo princípio do PermissionGuard: nunca um tenant vindo do client, só do JWT já emitido por /auth/select-tenant).
4. Exige a permission monitoring.view (userHasPermission, já existia desde a fase RBAC — só não tinha nenhum consumidor ainda).
5. Só então entra na room do tenant.

Testado: token ausente/inválido → desconectado na hora, nenhum evento vaza. Token válido → entra na room certa, recebe eventos do próprio tenant.

Origem dos eventos

Um único canal Redis, b2bcall:events (o mesmo que já existia desde a fase Event Socket) — o RealtimeRedisBridge (apps/api) assina esse canal com uma conexão dedicada (pub/sub exige conexão própria, não pode compartilhar com a usada pra comandos) e reencaminha pra broadcastToTenant() quando o evento já tem tenantId resolvido; sem tenant resolvido, o evento é descartado (nenhuma room saberia receber).

Dois produtores publicam nesse canal:

1. b2bcall-fs-events (eventos do FreeSWITCH, normalizados — ver packages/telephony/src/normalize-event.ts). A maioria desses eventos (callcenter::info, sofia::gateway_state) não carrega b2bcall_tenant_id como channel variable (só existe a partir do Predictive Engine) — o tenant é resolvido pelo id do agente/fila embutido no nome FreeSWITCH (<uuid>@dominio), com fan-out sobre os tenants ativos (mesmo padrão de trunk-status.ts), cacheado por id em tenant-resolve.ts (agente/fila nunca troca de tenant, cache nunca fica desatualizado). Isso só passou a funcionar depois da correção do bug de subscrição de eventos CUSTOM — ver docs/AGENTS.md e docs/EVENT_SOCKET.md.
2. apps/api (mudanças no nosso próprio Agent.state, via realtime-publish.helper.ts, chamado de dentro de agents-me.controller.ts em login/logout/pause/resume). Aqui o tenantId já vem direto do JWT da requisição HTTP — sem fan-out.

Tipos de evento emitidos

• AGENT_STATE_CHANGED: nosso enum próprio (OFFLINE/AVAILABLE/ PAUSED/...), só muda via login/logout/pause/resume.
• AGENT_STATUS_CHANGED: CC-Agent-State bruto do mod_callcenter (Waiting/Receiving/...) — vocabulário diferente do de cima, não dá pra misturar (mesmo agente pode estar "AVAILABLE" no nosso enum e "Receiving" no mod_callcenter simultaneamente, description de momentos diferentes do ciclo de uma chamada).
• QUEUE_MEMBER_COUNT: contagem ao vivo de chamadas esperando por fila (CC-Count) — a peça central da secao 54 ("Chamadas esperando").
• QUEUE_MEMBER_LEFT: uma chamada saiu da fila, com cause/cancelReason e timestamps de entrada/saída — atendida vs. abandonada, base pro cálculo futuro de Service Level/Abandon Rate.
• AGENT_OFFERED_CALL / AGENT_BRIDGE_FAILED: uma chamada foi ofertada a um agente / falhou ao bridgear (ex.: USER_NOT_REGISTERED).
• CALL_CREATED/CALL_ANSWERED/CALL_ENDED: já existiam desde a fase Event Socket, mas só carregam tenantId quando o b2bcall_tenant_id channel variable existir (chamadas puramente sintéticas de teste, como as usadas pra verificar esta fase, não têm — não chegam no WebSocket).

Verificado ponta a ponta

Client de teste com socket.io-client, autenticado com o JWT de um tenant de teste, na room tenant:<id>:

login do agente          → AGENT_STATE_CHANGED {state: "AVAILABLE"}
pause                     → AGENT_STATE_CHANGED {state: "PAUSED"}
resume                    → AGENT_STATE_CHANGED {state: "AVAILABLE"}
logout                    → AGENT_STATE_CHANGED {state: "OFFLINE"}

originate null/dummy &callcenter(fila@dominio), com agente logado numa fila:
  → QUEUE_MEMBER_COUNT {count: 3}
  → AGENT_STATUS_CHANGED {state: "Receiving"}
  → AGENT_OFFERED_CALL
  → AGENT_BRIDGE_FAILED {hangupCause: "USER_NOT_REGISTERED"}  (ramal sem SIP real registrado)
  → QUEUE_MEMBER_LEFT {cause: "Cancel", cancelReason: "TIMEOUT"}
  → QUEUE_MEMBER_COUNT {count: 2}

token ausente/inválido → socket desconectado na hora, nenhum evento recebido.

Todos chegaram só na room do tenant certo, com o tenantId batendo.

O que falta

• Ramais/extensões (secao 55 completa): as cores dependem de "ocupado" (busy — CHANNEL_ANSWER/HANGUP tied a um ramal específico) e "offline" (registro SIP — sofia::register/unregister, cujo mecanismo de entrega agora funciona, mas nunca foi exercitado com um client SIP real nesta sessão). Além disso, resolver qual ramal um evento de canal pertence exige extrair o número de discagem dos headers (Caller-Destination-Number/ Channel-Name), não implementado ainda — e o mesmo limite de domínio compartilhado entre tenants já documentado em docs/EXTENSIONS.md afeta esse mapeamento. Não implementado; fica pra quando houver um client SIP de verdade pra testar.
• Persistir AGENT_STATUS_CHANGED/QUEUE_MEMBER_COUNT em Agent.state ou numa tabela de snapshot de fila: hoje só passam pelo WebSocket, não gravam nada — suficiente pro requisito "tempo real", mas sem histórico consultável fora da tabela agent_state_events (que só reflete login/logout/pause/resume, não os estados derivados de chamada).
• TME/TMA/Service Level/Abandon Rate (secao 54): dependem de CDR (fase futura, depois do Predictive Engine na ordem do agente.md secao 232) — QUEUE_MEMBER_LEFT já traz os dados brutos (cause, cancelReason, timestamps) que vão alimentar esse cálculo quando CDR existir.
• Dashboard Tenant/Platform (secao 162-163) — fase Frontend.
• Reconexão/reconciliação de estado ao reconectar o WebSocket (perder um evento por queda de rede momentânea não é recuperável hoje — o client precisa buscar o snapshot atual via REST depois de reconectar; não existe endpoint de snapshot ainda).