OLP Docs

Appearance

07 — Anti-padrão: lookup por nome em domínio multi-tenant ​

Ref: 00_INDEX · Frente gerada: F6

Contexto ​

Toda associação entre entidades de domínio DEVE ser por UUID. Lookup por nome/titulo/label (string match) é frágil: homônimos, acentuação, espaços, caixa, idempotência quebrada em re-import, e em sistema multi-escola pode até virar cross-tenant leak se faltar escola_id no filtro.

Evidência (varredura inicial) ​

rg "\.eq\('nome|\.eq\(\"nome|toLowerCase\(\).*===.*toLowerCase":

OcorrênciaPath:linhaAvaliação
papeis.nome = 'escola_trial'cadastro-escola-publica/index.ts:204🟡 aceitável (papéis são constantes de sistema, não dados de usuário)
papeis.nome = 'escola'cadastro-escola-publica/index.ts:753🟡 idem
p.nome.toLowerCase() === nomePapel.toLowerCase()src/contexts/auth-context.tsx:357🟡 idem
tipo === id ou id.toLowerCase() === tipo?.toLowerCase()src/components/usuarios-escola.tsx:364🟡 lookup contra lista enum-like — aceitável
u.role?.toLowerCase() === roleNormalizadogestao-usuarios-escola/index.ts:420🟡 idem

→ Nenhuma ocorrência crítica de lookup por nome em entidades de domínio (alunos, escolas, olimpiadas, inscrições) foi encontrada. Os matches são contra papeis.nome, que é uma constante de sistema (enum em string).

Padrões bons já vigentes ​

resultados-import.ts:

  • Lookup de aluno via matricula (chave única por escola) → alunoMap.set(a.matricula, a) — aceitável porque matricula é canônica e validada server-side. Note que NÃO usa nome_completo.
  • Lookup de inscrição via aluno_id (UUID) → inscricaoMap.set(aluno.id, inscricao.id) — canônico.

alunos-import.ts:

  • Dedup por matricula.toLowerCase() em arquivo — aceitável (mesma escola, chave única).

Regra proposta para o SSOT (99) ​

  1. Domínio (alunos, inscrições, resultados, mensagens, contatos, etc.): lookup APENAS por UUID. Toda chave externa (matrícula, CPF, INEP) deve passar por validação + tradução para UUID logo na entrada.
  2. Constantes de sistema (papéis, tipos, slugs): lookup por nome é OK porque o valor é controlado pelo banco/seed, não pelo usuário.
  3. Multi-escola: TODO lookup por chave externa em entidade de domínio DEVE incluir escola_id no filtro. Falta de escola_id em uma query de alunos é incidente de segurança, não só de performance.

Hipótese ​

P30 — Baixo risco atual, alta importância preventiva. A varredura não revelou caso aberto, mas formalizar a regra agora é barato e blinda contra introdução futura. Justifica entrada na mem:// quando o SSOT 99 for aprovado.

Próximas etapas ​

→ Adicionar item canônico ao 99_REGRA_QUALIDADE_PERFORMANCE.md §7 "Lookup por UUID". → Adicionar regex CI para bloquear .eq('nome', ...) em tabelas de domínio (whitelist papeis, series_escolares).