70 lines
2.2 KiB
Markdown
70 lines
2.2 KiB
Markdown
# 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. Utilizar a constante canônica `Tabelas` para toda e qualquer referência a tabelas no banco de dados (Knex, migrations, queries);
|
|
2. 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
|
|
import { Tabelas } from "atende-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
|
|
import {
|
|
StatusTicket,
|
|
TipoUsuarioInterno,
|
|
TipoManutencaoSoftware,
|
|
TipoMensagem,
|
|
} from "atende-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 migração).
|