Pular para o conteúdo principal

Runbook — Presença e WebSocket

Sintomas​

  • GET /api/v1/presence/active-users vazio com utilizadores “online” no CRM
  • Front admin sem eventos em admin:observer
  • Socket recusado no handshake
  • Contagens divergentes entre pods

Causas frequentes​

  1. JWT do default-crm assinado com outro JWT_SECRET que o CentralCRM.
  2. Handshake sem { token: "<JWT>" } no namespace /presence.
  3. Falta tenantId no token (e sem x-tenant-id nas rotas REST).
  4. Admin não entra na sala admin:observer (claim role: admin).
  5. Várias réplicas da API: o mapa é in-process (ADR 0003). Cada pod tem o seu conjunto de sockets.

Mitigação​

  • Uma réplica de presença ou sticky sessions no load balancer para /socket.io até existir adapter Redis.
  • Reinício do pod zera sessões — esperado; clientes reconectam.
  • Confirmar CORS e allowedHeaders (Authorization, x-tenant-id) se o cliente REST e o socket partilham origem.

Fluxo end-to-end: arquitetura/entendimento.md.