OLP Docs

Appearance

Audit — "Todas as turmas" vazio para escola (regressão) ​

Data: 2026-05-03 Escopo: src/hooks/useGestaoTurmas.ts, tab Turmas em alunos-escola.tsxSeveridade: Alta — escola não enxergava nenhuma turma cadastrada Status: Resolvido (Wave 6)

1. Sintoma ​

Usuário escola na tela Alunos → tab Turmas via lista vazia mesmo com turmas 2026 existentes. Filtros e dropdown de "Todas as turmas" também vinham vazios em componentes de Transferência e Importação.

2. Causa raiz ​

Cache-key mismatch no useGestaoTurmas:

  • A leitura do useQuery usava uma chave genérica (sem filtros).
  • As mutations e os setQueryData escreviam na chave filtrada (TURMAS_KEYS.list(filters)).
  • Resultado: o consumidor lia de um cache que nunca era populado, retornando [] indefinidamente.

Não é problema de RLS nem de query SQL — o backend retornava as turmas corretamente, mas o frontend descartava o resultado pela chave divergente.

3. Correção aplicada ​

Arquivo: src/hooks/useGestaoTurmas.ts

  • Refatorado para useQuery reativo amarrado ao state filters.
  • queryKey: TURMAS_KEYS.list(filters) é agora SSOT para leitura e escrita.
  • Invalidações e atualizações otimistas usam exatamente a mesma chave.

Componentes afetados (sem mudança de código, mas validados): Transferência de aluno, Importação, modal de criação de turma, filtro "Todas as turmas".

4. Reforço de padrão ​

Esta regressão reforça a memória React Query Standard e a Core rule:

queryKeys MUST include escola_id (multi-escola) e quaisquer filtros que afetam o resultado. Leitura e escrita devem usar a MESMA factory de chaves.

5. Validação ​

  • Escolas com turmas 2026 voltaram a exibir a lista completa.
  • Filtros descendentes em "Todas as séries" (ordem decrescente por ordem) operam sobre dataset correto.
  • Sem regressão em mutations (criar/editar/excluir turma propaga via mesma key).

6. Referências ​

  • src/hooks/useGestaoTurmas.ts
  • src/components/alunos-escola.tsx
  • ADR React Query: docs/architecture/adrs/ (factory de queryKeys)