Pular para o conteúdo principal

Runbooks

Procedimentos quando a SPA “quebra” em produção. O front não tem workers: quase sempre é API, CORS, bundle desatualizado ou sessão.

1. Tela branca / chunk failed​

Sintoma: branco após deploy, console Failed to load module.

Checagem:

  1. Hard refresh; index.html aponta para hashes novos?
  2. CDN/Nginx servindo index.html antigo com JS novo (ou o inverso)
  3. try_files SPA ativo? Deep link /directories/... deve devolver index.html, não 404 do Nginx

Ação: republicar dist/ completo; cache bust em index.html; rollback da imagem se o build estiver corrompido.

2. Não entra (login 401/403/CORS)​

  1. Network: o host é Central (VITE_API_BASE_URL)?
  2. CORS: origem do front autorizada na API
  3. 401 auth.invalidCredentials vs 403 auth.accountUnavailable (conta bloqueada)
  4. Relógio do cliente (JWT exp)

Ação: confirmar health da API Central; não “consertar” no front se o backend recusa o user.

3. Login ok, painel vazio / 0 empresas​

  1. Qual host da listagem? GET /api/v1/companies (Central) vs GET /api/companies (Default)
  2. JWT sem perm-user-list / escopo N1 preso a uma empresa
  3. Filtro da UI em “subempresas” sem parentCompanyUuid

Ação: comparar Network com Postman no mesmo token; ver CompanyService.listCompanies vs listRootCompanies.

4. Sessão cai sozinha​

  1. Interceptor 401 (src/auth/sessionExpiry.ts) — algum pedido autenticado falhou
  2. Secret do vault mudou no rebuild
  3. Socket de presença 401 em loop (menos comum)

Ação: correlacionar o primeiro 401 no Network; se for Default down e Central up, o interceptor ainda dispara.

5. Presença / sessões ativas = 0​

  1. WS socket.io contra origem Central (getSocketApiOrigin)
  2. Proxy/ingress WebSocket (Upgrade)
  3. Fallback HTTP GET /api/v1/presence/active-users-global

Ação: DevTools → WS frames; se REST funciona e WS não, é infra de socket, não UI.

6. Governança 404 em form-fields ou /block​

Rotas só na API Default. Se o proxy/prod apontar para Central, 404/405.

Ação: confirmar VITE_GOVERNANCE_API_BASE_URL no bundle (não no runtime do container).

7. Auditoria sem eventos ao vivo​

  1. HTTP GET /api/logs/company/:uuid funciona?
  2. Socket /ws/logs na origem Default; join { companyUuid }

8. Tema / branding “sumiu”​

  1. GET público /api/governance/theme-tokens no login
  2. GET por empresa /api/governance/companies/:uuid/theme-tokens
  3. Jobs 202 de ícone/banner — polling branding-jobs/:jobId

9. Alertas sugeridos (ops)​

O front não emite métricas. Monitore nas APIs / ingress:

  • 5xx e latência em /api/v1/auth/login
  • 5xx em /api/v1/companies e /api/companies
  • erros de handshake /socket.io
  • taxa de 401 (pico = secret rotacionado ou API auth down)

10. Escalada​

  1. Confirmar se é só UI (console) ou Network
  2. Host Central vs Default
  3. Rollback da imagem do front se o último deploy coincidir
  4. Security: SECURITY.md se for IDOR / vazamento de token