Convenções de Nomenclatura e Idioma
Regras obrigatórias sobre idioma e casing em cada camada do sistema.
1. Regra Geral
O projeto é bilíngue por camada: banco de dados e domínio de negócio em português, infraestrutura React/TypeScript em inglês. Labels e textos de UI são sempre em português (pt-BR).
2. Banco de Dados (PostgreSQL)
| Elemento | Idioma | Casing | Exemplo |
|---|---|---|---|
| Tabelas | Português | snake_case | escola_olimpiadas, resultados_aluno |
| Colunas | Português | snake_case | criado_em, nome_completo, nota_corte |
| Enums | Português | snake_case | status_escola, permissao_area |
| Valores de enum | Português | snake_case | 'ativa', 'agenda', 'pendente' |
| Funções SQL | Português | snake_case | fn_validar_escola_usuario_papel(), fn_validate_expire_at() |
| Índices | Português | snake_case com prefixo idx_ | idx_alunos_escola_id |
Exceções históricas (não renomear): id, status, email, ip, token, hash — termos universais mantidos em inglês.
3. Edge Functions (Deno Backend)
| Elemento | Idioma | Casing | Exemplo |
|---|---|---|---|
| Nome do diretório/função | Português | kebab-case | gestao-alunos, admin-escolas |
| Prefixos por domínio | — | — | admin-*, especialista-*, escola-*, gestao-*, coordenador-*, diretor-*, portal-* |
Actions (campo action) | Português/Inglês | snake_case | list, create, update, delete, list_public, list_by_olimpiada |
| Variáveis internas | Português | camelCase | escolaId, faseAtual, nivelId |
| Helpers compartilhados | Inglês | kebab-case | cors-helpers.ts, auth-helpers.ts, logging-helper.ts |
Nomenclatura de actions: verbos CRUD em inglês (list, create, update, delete), qualificadores em português (list_by_olimpiada, delete_fase_results).
4. Frontend (React/TypeScript)
| Elemento | Idioma | Casing | Exemplo |
|---|---|---|---|
| Componentes React | Inglês/Misto | PascalCase | Dashboard, MuralLiberacoes, LiberacaoCard |
| Hooks | Inglês com termos PT | camelCase com use | useGestaoAlunos, useMuralEscola, useAdminEscolas |
| Arquivos de componente | Português | kebab-case | mural-liberacoes.tsx, agenda-tarefas-card.tsx |
| Tipos/Interfaces | PascalCase misto | PascalCase | EscolaOlimpiada, LiberacaoStats, AuthenticatedUser |
| Constantes | Inglês | UPPER_SNAKE_CASE | QUERY_KEYS, CACHE_CONFIG, ROLE_TO_PROFILE |
| Labels/textos de UI | Português | — | 'Agenda', 'Inserir Resultados', 'Publicado' |
5. Logs de Auditoria
| Elemento | Formato | Exemplo |
|---|---|---|
Campo acao | <modulo>.<operacao> lowercase PT | escola.create, usuario.update, banner.soft_delete |
Campo entidade | Singular PT | escola, usuario, olimpiada |
Campo tipo | Inglês | create, update, soft_delete |
6. Diretórios e Arquivos
| Local | Convenção | Exemplo |
|---|---|---|
src/components/<dominio>/ | Prefixo do domínio em kebab-case PT | agenda-tarefas-card.tsx, mural-nova-noticia.tsx |
src/hooks/ | use + domínio em PascalCase | useGestaoResultados.ts, useMuralConfig.ts |
src/lib/ | kebab-case descritivo | edge-function.ts, olimpiada-helpers.ts |
supabase/functions/ | kebab-case PT por domínio | gestao-resultados/, admin-logs/ |
docs/ | UPPER_SNAKE_CASE.md | NAMING_CONVENTIONS.md, CODING_STANDARDS.md |
7. Checklist de Validação
Ao criar novo código, verificar:
markdown
□ Tabela/coluna em português snake_case?
□ Edge Function com prefixo de domínio correto?
□ Componente com nome descritivo e prefixo do domínio?
□ Hook com `use` + domínio?
□ Labels de UI em português?
□ Log `acao` no formato `modulo.operacao`?
□ Tipo TypeScript em PascalCase?