124 lines
4.7 KiB
Markdown
124 lines
4.7 KiB
Markdown
---
|
|
type: rule
|
|
name: regras-negocio-md
|
|
description: O conteúdo de regras de negócio deve ficar em <modulo-wiki>/dev/<modulo-id>/ (resolvido via memorias-ia/modulo.yml).
|
|
scope: global
|
|
trigger: always_on
|
|
updatedAt: "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:
|
|
|
|
```typescript
|
|
// 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`)
|
|
|
|
```markdown
|
|
# 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:
|
|
```typescript
|
|
// 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:
|
|
```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.
|
|
*/
|
|
```
|
|
|
|
---
|
|
|
|
## 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>/`
|