.agent/rules/uso-estrito-enums-tabelas.md

type	name	description	scope	trigger	updatedAt
rule	uso-estrito-enums-tabelas	Uso estrito de constantes canônicas de Tabelas e Enums exportados por *-comuns (proibição de magic strings)	global	always_on	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

db("tickets")
db("usuarios as u")
db("tarefas_manutencao")

✅ Correto

// 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

if (ticket.status === "resolvido") { ... }
if (usuario.papel === "administrador") { ... }
if (tarefa.tipo_manutencao === "corretiva_bug") { ... }
if (msg.tipo_mensagem === "nota_interna_equipe") { ... }

✅ Correto

// 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).