82 lines
2.7 KiB
Markdown
82 lines
2.7 KiB
Markdown
---
|
|
type: rule
|
|
name: uso-estrito-enums-tabelas
|
|
description: Uso estrito de constantes canônicas de Tabelas e Enums exportados por *-comuns (proibição de magic strings)
|
|
scope: global
|
|
trigger: always_on
|
|
updatedAt: "2026-10-14"
|
|
---
|
|
|
|
# Regra: Uso Estrito de Enums e Constantes de Tabelas (Eliminação de Strings Literais)
|
|
|
|
## Contexto
|
|
|
|
A utilização de strings mágicas (magic strings) e literais soltos para representar tabelas de banco de dados ou valores de enums é uma fonte crônica de bugs silenciosos em runtime. Quando um valor de enum ou nome de tabela é refatorado, o TypeScript não detecta comparações literais soltas (`u.papel === "administrador"`, `db("tickets")`), quebrando regras de negócio e consultas.
|
|
|
|
---
|
|
|
|
## Regra Fundamental
|
|
|
|
**É terminantemente proibido utilizar strings literais para referenciar tabelas do banco de dados ou valores que pertençam a enums canônicos.**
|
|
|
|
Todo desenvolvedor e agente de IA deve obrigatoriamente:
|
|
1. Consultar `memorias-ia/modulo.yml` para identificar o módulo e importar as definições a partir do pacote compartilhado `<modulo>-comuns`;
|
|
2. Utilizar a constante canônica `Tabelas` (ou `tabelas`) para toda e qualquer referência a tabelas no banco de dados (Knex, migrations, queries);
|
|
3. Utilizar os objetos de Enum canônicos correspondentes para toda comparação, atribuição e checagem condicional de estado, papel, tipo ou severidade.
|
|
|
|
---
|
|
|
|
## 1. Referência a Tabelas de Banco de Dados
|
|
|
|
### ❌ Proibido
|
|
```typescript
|
|
db("tickets")
|
|
db("usuarios as u")
|
|
db("tarefas_manutencao")
|
|
```
|
|
|
|
### ✅ Correto
|
|
```typescript
|
|
// Importar do pacote <modulo>-comuns do projeto atual
|
|
import { Tabelas } from "<modulo>-comuns";
|
|
|
|
db(Tabelas.tickets)
|
|
db(`${Tabelas.usuarios} as u`)
|
|
db(Tabelas.tarefas_manutencao)
|
|
```
|
|
|
|
---
|
|
|
|
## 2. Comparações e Atribuições de Enums
|
|
|
|
### ❌ Proibido
|
|
```typescript
|
|
if (ticket.status === "resolvido") { ... }
|
|
if (usuario.papel === "administrador") { ... }
|
|
if (tarefa.tipo_manutencao === "corretiva_bug") { ... }
|
|
if (msg.tipo_mensagem === "nota_interna_equipe") { ... }
|
|
```
|
|
|
|
### ✅ Correto
|
|
```typescript
|
|
// Importar os enums canônicos do pacote <modulo>-comuns
|
|
import {
|
|
StatusTicket,
|
|
TipoUsuarioInterno,
|
|
TipoManutencaoSoftware,
|
|
TipoMensagem,
|
|
} from "<modulo>-comuns";
|
|
|
|
if (ticket.status === StatusTicket.resolvido) { ... }
|
|
if (usuario.papel === TipoUsuarioInterno.administrador) { ... }
|
|
if (tarefa.tipo_manutencao === TipoManutencaoSoftware.corretiva_bug) { ... }
|
|
if (msg.tipo_mensagem === TipoMensagem.nota_interna_equipe) { ... }
|
|
```
|
|
|
|
---
|
|
|
|
## Impacto
|
|
|
|
- Refatorações seguras assistidas pelo compilador TypeScript (`tsc --noEmit`);
|
|
- Zero regressões causadas por erros tipográficos em nomes de tabelas ou enums;
|
|
- Código fortemente tipado em todas as camadas (`*-comuns`, `*-back`, `*-front` e `*-migracao`).
|