melhorias ts

rules/typescript-sem-any.md

@@ -38,35 +38,28 @@ Regras obrigatórias para TypeScript neste projeto:
   3. inferir a partir do contexto sempre que possível;
   4. deixar um `TODO de tipagem` explícito, mas sem usar `any`.
 
-Regras obrigatórias para uso de enums:
+## Regras Inegociáveis para Uso de Enums e zEnums
 
-- Quando um valor estiver associado a um `enum`, é obrigatório utilizar o enum, nunca strings literais.
-- O acesso deve seguir o padrão: `<NomeEnum>.VALOR`.
+> 🚨 **REGRA DE OURO:** **SE EXISTE ENUM OU zENUM DISPONÍVEL (EM QUALQUER MÓDULO OU APLICAÇÃO), O USO DO ENUM É 100% OBRIGATÓRIO — SEM NENHUMA EXCEÇÃO.**
 
-Também é proibido, quando existir `enum` correspondente:
+1. **Proibição Universal de Strings Literais (Magic Strings):**
+   - É **estritamente proibido** utilizar strings literais no lugar de qualquer enum ou zEnum existente no sistema (seja para tabelas, colunas, status, tipos, categorias, eventos, ações, etc.).
+   - É proibido utilizar casts para forçar compatibilidade com tipos de domínio (ex: `"ativo" as StatusConta` ou `"pontos" as TipoNomeTabela`).
 
-- utilizar strings literais no lugar do enum (ex: `"ativo"`, `"inativo"`, `"automatica"`, `"criar"`);
-- utilizar cast para forçar compatibilidade com enum (ex: `"ativo" as StatusConta`).
+2. **Padrão Canônico de Acesso:**
+   - Enums TypeScript nativos: `<NomeEnum>.VALOR` (ex: `CategoriasSuporte.ADMIN`, `TipoProcessamento.BATCH`).
+   - Enums Zod / Objetos derivados: `<zSchema>.enum.VALOR` ou `<enumDerivado>.<membro>` (ex: `enumTabelas.pontos`, `enumColunas.codigo`, `zStatus.enum.ativo`, `zTipoPessoa.enum.fisica`).
 
-Proibido gerar código que apenas "faça compilar" usando:
+3. **Operações em Todas as Camadas (Banco, Filas, APIs e Frontend):**
+   - **Banco de dados & Queries:** Nomes de tabelas, entidades e colunas DEVEM consumir os enums correspondentes do pacote `*-comuns` (nunca strings hardcoded em queries de banco).
+   - **Regras de Negócio & Lógica:** Comparações condicionais, transições de estado, status e categorias DEVEM usar os membros do enum.
+   - **Frontend & Telas:** Filtros, selects, badges e renderizações condicionais DEVEM importar e referenciar os enums canônicos.
 
-- `as any`
-- `: any`
-- `[] as any`
-- `{ } as any`
-- dupla coerção como `as unknown as any`
-
-Em casos excepcionais, preferir:
-
-- `as unknown as TipoEspecifico` somente se houver justificativa clara e comentário técnico.
-
-Diretriz para o agente:
-
-Se encontrar uma string que represente um valor de domínio do sistema, o agente deve:
-
-1. procurar se já existe um `enum` correspondente no projeto;
-2. usar o `enum` existente;
-3. se não existir, propor a criação de um `enum` explícito, em vez de manter strings soltas.
+4. **Diretriz de Busca Prévia Obrigatória:**
+   Antes de escrever qualquer string que represente conceito de domínio, entidade, tabela, coluna, status ou opção, o agente **DEVE**:
+   1. Inspecionar o pacote `*-comuns` (`src/enums/`, `src/tabelas/`, `src/tipos/`) da respectiva aplicação;
+   2. Se existir qualquer enum correspondente, **é obrigatório utilizar o enum existente**;
+   3. Se não existir, propor/criar o `enum` ou `z.enum` no `*-comuns` em vez de espalhar strings literais.
 
 ---