120 lines
3.7 KiB
Markdown
120 lines
3.7 KiB
Markdown
---
|
|
type: rule
|
|
name: regras-negocio-md
|
|
description: Arquivo {modulo}.regras-negocio.md obrigatório para módulos com lógica complexa
|
|
scope: global
|
|
trigger: always_on
|
|
updatedAt: "2026-06-01"
|
|
---
|
|
|
|
# Regra: Arquivo `{modulo}.regras-negocio.md` Obrigatório para Módulos com Lógica Complexa
|
|
|
|
> **Escopo global** — aplica-se a todos os projetos do ecossistema Azteca.
|
|
|
|
## Contexto
|
|
|
|
Qualquer arquivo TypeScript que contenha lógica de negócio não-trivial — múltiplas regras de decisão, critérios de bloqueio, estratégias de processamento — deve ter suas regras documentadas em linguagem natural em um arquivo Markdown co-localizado.
|
|
|
|
Isso garante que produto, suporte e desenvolvimento possam entender as regras sem precisar ler TypeScript, e que o agente de IA encontre rapidamente os critérios corretos antes de alterar qualquer código.
|
|
|
|
## Regra
|
|
|
|
**Todo módulo com lógica de negócio não-trivial DEVE ter um arquivo `{modulo}.regras-negocio.md` co-localizado.**
|
|
|
|
Considera-se lógica não-trivial qualquer módulo que:
|
|
- possui 3 ou mais critérios de decisão distintos
|
|
- realiza eleição/priorização entre registros
|
|
- aplica diferentes estratégias por tipo de dado
|
|
- pode resultar em revisão manual (caminho alternativo ao fluxo automático)
|
|
- é consumido por CRON, worker ou importador automático
|
|
|
|
O módulo TypeScript deve conter, na primeira linha do arquivo, a referência:
|
|
|
|
```typescript
|
|
// Regras de negócio: ver {modulo}.regras-negocio.md
|
|
```
|
|
|
|
O arquivo `.md` é a **fonte de verdade**. Os JSDoc do código devem referenciar o `.md`, não duplicá-lo.
|
|
|
|
## Estrutura Obrigatória do Arquivo
|
|
|
|
```markdown
|
|
# Regras de Negócio — [Nome do Módulo]
|
|
|
|
Módulo: `_arquivo.ts`
|
|
Localização: `caminho/relativo/ao/arquivo`
|
|
|
|
---
|
|
|
|
## Contexto
|
|
Por que este módulo existe, qual problema resolve.
|
|
|
|
## Critérios de Entrada / Identificação
|
|
O que aciona o módulo, quais dados recebe, filtros aplicados.
|
|
|
|
## Regras de Processamento
|
|
As regras numeradas em ordem de avaliação.
|
|
|
|
## Casos de Revisão Manual (quando aplicável)
|
|
Quando o processamento automático não pode prosseguir.
|
|
|
|
## Estratégia de Fusão / Resultado (quando aplicável)
|
|
O que o módulo produz, como campos são combinados.
|
|
|
|
## Dependências Externas
|
|
Tabelas, filas, serviços externos tocados pelo módulo.
|
|
```
|
|
|
|
## Exemplos
|
|
|
|
✅ **Correto** — referência no topo do módulo, regras no `.md`:
|
|
```typescript
|
|
// Regras de negócio: ver juntar_execucoes.regras-negocio.md
|
|
|
|
import { ... } from "..."
|
|
|
|
export const compilarJuntarExecucoes = async (...) => {
|
|
// implementação conforme regras-negocio.md
|
|
}
|
|
```
|
|
|
|
❌ **Errado** — regras embutidas no código como comentário de bloco:
|
|
```typescript
|
|
/**
|
|
* Regras de negócio:
|
|
* [x] Pode ter apenas uma execução por data de vencimento.
|
|
* [x] Se tiver apenas uma execução consolidada → ela é a principal.
|
|
* ...
|
|
*/
|
|
```
|
|
|
|
❌ **Errado** — JSDoc duplicando as regras em vez de referenciar o `.md`:
|
|
```typescript
|
|
/**
|
|
* Retorna false quando:
|
|
* - vencimentos divergentes
|
|
* - executada com datas distintas
|
|
* - vencimento_prorrogado distintos
|
|
* ...
|
|
*/
|
|
```
|
|
|
|
## Impacto
|
|
|
|
Sem este padrão:
|
|
- Regras de negócio ficam implícitas no código ou em JSDoc que envelhece sem controle
|
|
- O agente de IA precisa inferir regras do código ao invés de lê-las diretamente
|
|
- Produto e suporte não conseguem validar o comportamento sem ajuda técnica
|
|
- Mudanças de regra geram JSDoc desatualizado espalhado pelo código
|
|
|
|
## Aplicação
|
|
|
|
- Módulos de CRON com lógica de auditoria/fusão
|
|
- Importadores automáticos (ex: importação de licenças via IA)
|
|
- Workers de processamento em lote
|
|
- Qualquer utilitário com lógica de decisão multi-critério
|
|
|
|
## Referências
|
|
|
|
- Skill: `global/skills/documentar-regras-negocio/SKILL`
|
|
- Workflow: `global/workflows/documentar-regras-negocio`
|