@audit Controle — 2026-04-12

Resumo

Auditoria completa da seção Controle (Coordenador) após ciclo de 4 etapas de refatoração e otimização.

Domínios Auditados

#	Domínio	Status	Detalhes
1	Logging	✅ OK	3 ações CUD: controle.toggle_acao_chave, controle.update_aplicacao, controle.batch_update_aplicacoes. registrarLog() com req em todas as writes. Reads não logam.
2	Validação	✅ OK	Zod schemas (UpdateAcaoChaveSchema, UpdateAplicacaoSchema) + whitelist de campos.
3	RLS	✅ OK	controle_acoes_chave e controle_aplicacoes com policies coordenador (SELECT, INSERT, UPDATE).
4	Auth/CORS	✅ OK	requireRole(["coordenador"]) + getCorsHeaders() em todas as respostas incluindo catch.
5	Feature Flag	✅ OK	requireFeatureFlag("controle") no handler.
6	Error Handling	✅ OK	getUserFriendlyError() em todas as mutations. olpToast (nunca alert()).
7	React Query	✅ OK	Cache com escola_id, staleTime configurado, invalidação granular por tab.
8	Renderização Atômica	✅ CORRIGIDO	Flash de skeleton ao trocar tabs → isLoading && !data nas 3 tabs.
9	Testes	✅ OK	Contract (Deno) + Integration (hooks) + Unit (helpers) + Isolamento cross-tab (12 testes).
10	Performance	✅ OK	batch_init, Lazy Mount Once, React.memo, refs estáveis, payload reduzido (select explícito).
11	Documentação SSOT	✅ ATUALIZADO	CONTROLE_SECTION.md atualizado com anti-flash pattern, lazy mount once, invalidação granular, otimizações de query.

Itens Encontrados e Resolução

Severidade	Item	Status	Ação
Crítico	Flash de skeleton viola ATOMIC_RENDERING.md	✅ Resolvido	isLoading && !data nas 3 tabs
Atenção	Documentação desatualizada	✅ Resolvido	CONTROLE_SECTION.md reescrito
Recomendação	Edge function >1100 linhas (>400 regra)	📋 Backlog	Code-split por action (dívida técnica catalogada)

Arquitetura Final

Frontend                           Backend                           Banco
────────                           ───────                           ─────
Container (ControleSkeleton)       coordenador-controle              controle_acoes_chave
├── TabAcoesChave ─┐               ├── batch_init (3-in-1)           controle_aplicacoes
├── TabAplicacoes ─┤── useControle ├── list_acoes_chave              tarefas (read-only)
└── TabTarefasKanban─┘             ├── update_acao_chave
                                   ├── list_aplicacoes
                                   ├── update_aplicacao
                                   ├── batch_update_aplicacoes
                                   ├── list_tarefas_kanban
                                   └── count_coordenadores

Padrões Implementados

1. Lazy Mount Once: Tabs montam no primeiro clique, nunca desmontam (hidden CSS)
2. Anti-Flash: isLoading && !data — skeleton só aparece quando cache está vazio
3. Invalidação Granular: Mutations invalidam apenas o cache da sua tab
4. Batch Init: 3 queries consolidadas em 1 chamada, derivação em memória
5. Dirty-State: Tab Aplicações com salvamento manual em lote

Referências

• docs/features/CONTROLE.md — arquitetura SSOT (migrado de docs/architecture/CONTROLE_SECTION.md)
• docs/development/ATOMIC_RENDERING.md — regra de renderização atômica
• src/hooks/useControle.ts — hooks React Query
• supabase/functions/coordenador-controle/index.ts — edge function