.agent/global/rules/regras-negocio-md.md

type	name	description	scope	trigger	updatedAt
rule	regras-negocio-md	O conteúdo de regras de negócio deve ficar em <modulo-wiki>/dev/<modulo-id>/ (resolvido via memorias-ia/modulo.yml).	global	always_on	2026-10-14

Regra: Conteúdo de Regras de Negócio em <modulo-wiki>/dev/<modulo-id>/

Escopo global — aplica-se a todos os projetos do ecossistema Azteca.

Contexto

Toda lógica de negócio não-trivial — regras de decisão, critérios de bloqueio, estratégias de processamento, priorizações e fluxos de dados — deve ter seu conteúdo documentado em linguagem natural na Wiki de Desenvolvimento em <modulo-wiki>/dev/<modulo-id>/.

💡 Aplicação VitePress (<modulo-wiki>, padrão: ../wiki/) e Resolução do Módulo:

• O caminho da Wiki <modulo-wiki> DEVE ser obtido dinamicamente a partir do campo modulo-wiki em memorias-ia/modulo.yml (adotando compulsoriamente o fallback padrão ../wiki/ quando omitido ou não configurado).
• Na Wiki resolvida, <modulo-wiki>/<modulo-id>/ é voltado ao acesso dos usuários, e <modulo-wiki>/dev/<modulo-id>/ é reservado ao acesso interno exclusivo da equipe de desenvolvimento.
• O identificador <modulo-id> (ou <modulo>) DEVE ser obtido obrigatoriamente do campo modulo-id em memorias-ia/modulo.yml na raiz do projeto.

Isso garante centralização, governança técnica e facilidade de consulta por desenvolvedores, arquitetos e agentes de IA.

---

Regra

Todo o conteúdo detalhado de regras de negócio DEVE ficar em <modulo-wiki>/dev/<modulo-id>/.

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 útil do arquivo, a referência:

// Regras de negócio: ver <modulo-wiki>/dev/<modulo-id>/{servico}.regras-negocio.md

A documentação na Wiki de Desenvolvimento é a fonte de verdade da lógica operacional. Os comentários JSDoc no código explicam a aplicação prática da função e apontam para a wiki para o detalhamento dos critérios.

---

Estrutura do Documento de Regras na Wiki de Desenvolvimento

Localização: <modulo-wiki>/dev/<modulo-id>/ (ex.: <modulo-wiki>/dev/<modulo-id>/regras-negocio/ ou <modulo-wiki>/dev/<modulo-id>/{servico}.regras-negocio.md)

# Regras de Negócio — [Nome do Módulo / Serviço]

Módulo TypeScript: `_arquivo.ts`
Localização no Código: `caminho/relativo/ao/arquivo`

---

## Contexto
Por que este módulo existe, qual problema operacional 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 estrita 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 / Persistência (quando aplicável)
O que o módulo produz, como campos são combinados ou persistidos.

## Dependências Externas
Tabelas, filas BullMQ, rotas e serviços externos tocados pelo módulo.

---

Exemplos

✅ Correto — referência no topo do módulo apontando para a Wiki de Desenvolvimento:

// Regras de negócio: ver <modulo-wiki>/dev/<modulo-id>/juntar_execucoes.regras-negocio.md

import { ... } from "..."

/**
 * Consolida execuções de condicionantes com base nas datas de vencimento.
 * Aplicação: Processamento noturno de auditoria e saneamento de agenda.
 */
export const compilarJuntarExecucoes = async (...) => {
  // implementação conforme a Wiki de Desenvolvimento
}

❌ Errado — regras embutidas no código como comentário gigante ou arquivos soltos fora da wiki:

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

---

Impacto

• Centralização de todo o conhecimento técnico e operacional na Wiki de Desenvolvimento.
• Regras de negócio claras para humanos e IAs sem poluir o código-fonte.
• Mudanças de regras são auditáveis e versionadas na documentação do repositório.

---

Referências

• Rule: rules/ddd-documentacao-primeiro.md
• Rule: rules/identidade-modulo.md
• Rule: rules/jsdoc-padrao.md
• Skill: skills/documentar-regras-negocio/SKILL.md
• Workflow: global/workflows/documentar-regras-negocio.md
• Wiki de Desenvolvimento: <modulo-wiki>/dev/<modulo-id>/