Pular para conteúdo

Runbook — diagnóstico diferencial de estado cliente/sessão

Objetivo

Isolar problemas de exibição que persistem para um usuário específico quando dados, HTTP, assets públicos e renderização React → DOM já foram validados em ambiente limpo.

Este procedimento foi formalizado a partir do incidente gutenberggt/sigesc#357, após a classificação PUBLIC_BROWSER_RENDER_CURRENT da F4.1.5.

Princípios

  • começar sempre por comparação não destrutiva;
  • não limpar cache/site data antes de obter o resultado do contexto limpo;
  • não coletar senha, token JWT, cookie de sessão ou conteúdo de armazenamento sensível;
  • quando for necessário inspecionar armazenamento, registrar inicialmente apenas nomes de chaves, existência e contagens;
  • não atribuir a causa a cache/PWA apenas porque um teste automatizado passou;
  • preservar evidência antes de remediar;
  • qualquer investigação de servidor continua read-only até existir causa demonstrada.

Etapa 1 — reproduzir no perfil atual

No dispositivo/navegador em que a falha foi relatada:

  1. acessar o SIGESC normalmente;
  2. autenticar com a própria conta do usuário;
  3. abrir exatamente a mesma turma e componente relatados;
  4. verificar separadamente:
  5. Objetos de Conhecimento;
  6. Frequência → Registros;
  7. registrar somente:
  8. navegador e versão;
  9. sistema operacional/dispositivo;
  10. modo normal ou PWA/standalone;
  11. turma/componente;
  12. se conteúdo aparece;
  13. se frequência aparece;
  14. data/hora da observação.

Não registrar senha, token, CPF de estudantes, conteúdo pedagógico ou attendance.records.

Etapa 2 — teste limpo antes de qualquer limpeza

Executar com as mesmas credenciais do usuário em um contexto sem estado persistente anterior. Preferência:

  1. janela anônima/privada do mesmo navegador, quando a política do navegador efetivamente isolar armazenamento e Service Worker; ou
  2. perfil novo do navegador; ou
  3. navegador alternativo que nunca tenha acessado o SIGESC naquele dispositivo.

Repetir exatamente a mesma turma/componente e as duas superfícies.

Classificação diferencial

Perfil atual Contexto limpo Classificação
falha funciona CLIENT_STATE_DIFFERENTIAL_CONFIRMED
falha falha CLIENT_STATE_NOT_ISOLATED
funciona funciona INCIDENT_NOT_REPRODUCED
funciona falha CLEAN_CONTEXT_ANOMALY — investigar sem limpeza

Etapa 3 — somente se CLIENT_STATE_DIFFERENTIAL_CONFIRMED

Antes da limpeza, capturar metadados mínimos do perfil problemático, quando tecnicamente viável:

  • existe registro de Service Worker para a origem SIGESC? sim/não;
  • quantidade de caches no Cache Storage;
  • nomes dos caches, desde que não contenham dados pessoais;
  • nomes das chaves de localStorage;
  • nomes das chaves de sessionStorage;
  • modo PWA instalado/standalone: sim/não;
  • versão pública indicada por /version.json, quando disponível.

Não copiar valores de tokens, cookies ou credenciais para tickets, logs ou documentação.

Etapa 4 — remediação reversível por ordem de impacto

Aplicar uma ação por vez e retestar depois de cada uma.

4.1 Fechar abas e reiniciar o navegador

Menor impacto. Retestar antes de prosseguir.

4.2 Recarregamento forçado

Forçar recarga da página ignorando o cache HTTP, conforme suporte do navegador. Retestar.

4.3 Remover instalação PWA específica, se houver

Se o SIGESC estiver instalado como PWA e o problema ocorrer somente nessa instalação, desinstalar apenas a PWA e testar pelo navegador normal antes de reinstalar.

4.4 Limpar dados do site somente para a origem SIGESC

Se a divergência persistir e já houver evidência CLIENT_STATE_DIFFERENTIAL_CONFIRMED, remover dados armazenados somente para a origem do SIGESC, incluindo cache/Cache Storage/Service Worker quando o navegador oferecer essa opção.

Consequências esperadas:

  • encerramento da sessão local;
  • necessidade de novo login;
  • perda de preferências locais não sincronizadas.

Não executar limpeza global do navegador como primeira medida.

4.5 Reautenticar e retestar

Após a limpeza específica da origem:

  1. abrir novamente o SIGESC;
  2. autenticar;
  3. repetir a mesma turma/componente;
  4. registrar o resultado.

Se passar a funcionar, classificar CLIENT_STATE_REMEDIATION_CONFIRMED.

Etapa 5 — se o contexto limpo também falhar

Não limpar o dispositivo por tentativa e erro. O próximo ramo é servidor/sessão específica, ainda read-only:

  • confirmar a identidade efetiva retornada para o usuário autenticado;
  • confirmar tenant/escola/escopos/RBAC efetivos;
  • comparar o conjunto de vínculos efetivamente projetado para a sessão real com o conjunto validado nas fases anteriores;
  • confirmar parâmetros enviados pelo frontend para turma/componente/ano;
  • comparar respostas HTTP reais da sessão apenas no nível estritamente necessário, sem registrar dados de estudantes ou conteúdo pedagógico.

Classificação provisória: AUTH_SESSION_DIFFERENTIAL_REQUIRED.

Critério de encerramento

O incidente só deve ser encerrado quando existir uma destas evidências:

  • CLIENT_STATE_REMEDIATION_CONFIRMED — o contexto limpo funcionou e a limpeza específica da origem corrigiu o perfil original;
  • causa de autenticação/sessão demonstrada e corrigida com teste de regressão;
  • INCIDENT_NOT_REPRODUCED documentado em múltiplas tentativas controladas, com concordância do usuário afetado.

Nunca encerrar apenas porque o backend possui registros ou porque um smoke test genérico passou.

Registro mínimo recomendado

Data/hora:
Usuário afetado:
Escola:
Turma/componente:
Dispositivo/SO:
Navegador/versão:
Modo: navegador | PWA
Perfil atual: PASS | FAIL
Contexto limpo: PASS | FAIL
Classificação diferencial:
Ação aplicada:
Resultado após ação:
Observações sem dados sensíveis:

Referência