212 lines
6 KiB
Markdown
212 lines
6 KiB
Markdown
---
|
|
name: documentar-regras-negocio
|
|
scope: global
|
|
updatedAt: "2026-06-01"
|
|
description: >
|
|
Guia operacional para criar, preencher e manter arquivos {modulo}.regras-negocio.md
|
|
co-localizados com módulos TypeScript de lógica de negócio complexa.
|
|
---
|
|
|
|
# Skill: Documentar Regras de Negócio em Módulos
|
|
|
|
Use esta skill sempre que um módulo TypeScript contiver lógica de decisão não-trivial
|
|
que precise ser rastreável por produto, suporte e desenvolvimento sem exigir leitura de código.
|
|
|
|
---
|
|
|
|
## Quando usar esta skill
|
|
|
|
- Módulo com 3+ critérios de decisão distintos
|
|
- Lógica de eleição/priorização entre registros
|
|
- Processamento que pode resultar em revisão manual
|
|
- Worker/CRON consumindo dados com estratégias diferenciadas por tipo
|
|
- Importador automático com regras de aceite/rejeição
|
|
|
|
---
|
|
|
|
## PASSO 1 — Identificar o escopo das regras
|
|
|
|
Antes de escrever o `.md`, percorrer o módulo e identificar:
|
|
|
|
| Categoria | O que procurar |
|
|
|---|---|
|
|
| **Critérios de entrada** | Filtros de query (excluido, vencimento, etc.) |
|
|
| **Critérios de bloqueio** | Condições que bloqueiam o fluxo automático |
|
|
| **Estratégia por tipo de dado** | Concatenação vs. primeiro-não-nulo vs. outros |
|
|
| **Eleição de principal** | Regras de prioridade entre registros |
|
|
| **Estado contraditório** | Combinações de campos mutuamente exclusivas |
|
|
| **Dependências externas** | Tabelas, filas, serviços tocados |
|
|
|
|
---
|
|
|
|
## PASSO 2 — Criar o arquivo
|
|
|
|
Nomenclatura: `{nome-do-modulo-sem-underline-inicial}.regras-negocio.md`
|
|
|
|
Localizar **na mesma pasta** do arquivo TypeScript:
|
|
|
|
```
|
|
modulo/
|
|
_meuModulo.ts
|
|
meu-modulo.regras-negocio.md ← co-localizado
|
|
```
|
|
|
|
Se o módulo for arquivo isolado (não pasta):
|
|
```
|
|
CRONS/
|
|
_cron_nome.ts
|
|
_cron_nome.regras-negocio.md ← mesmo diretório
|
|
```
|
|
|
|
---
|
|
|
|
## PASSO 3 — Preencher com o template
|
|
|
|
```markdown
|
|
# Regras de Negócio — [Nome Legível do Módulo]
|
|
|
|
Módulo: `_arquivo.ts`
|
|
Localização: `caminho/relativo/ao/workspace`
|
|
|
|
---
|
|
|
|
## Contexto
|
|
|
|
[Por que este módulo existe. Qual problema de negócio resolve.
|
|
Inclua o cenário que levou à sua criação — ex: "O sistema pode gerar duplicatas
|
|
por importações simultâneas..."]
|
|
|
|
---
|
|
|
|
## Critérios de Entrada
|
|
|
|
[O que aciona o módulo. Filtros aplicados na query de identificação.
|
|
Ex: `excluido = false`, mesmo `(codigo_origem, vencimento)`, etc.]
|
|
|
|
---
|
|
|
|
## Regras de Processamento
|
|
|
|
[Numeradas em ordem de avaliação. Cada regra deve incluir:
|
|
- Condição de ativação
|
|
- O que acontece quando ativada
|
|
- Se bloqueia ou direciona]
|
|
|
|
### Regra 1 — [Nome]
|
|
...
|
|
|
|
### Regra 2 — [Nome]
|
|
...
|
|
|
|
---
|
|
|
|
## Casos de Revisão Manual
|
|
|
|
[Quando o fluxo automático não pode prosseguir.
|
|
Liste as condições que enviam para revisão manual.
|
|
Se aplicável: como o caso é reportado (e-mail, log, fila de revisão).]
|
|
|
|
> **`null` é neutro** quando aplicável: descrever aqui se a lógica usa null como ausência neutra.
|
|
|
|
---
|
|
|
|
## Estratégia de Saída / Fusão de Campos
|
|
|
|
[Como os dados são combinados ou qual resultado é produzido.
|
|
Usar tabela para clareza:]
|
|
|
|
| Campo | Estratégia |
|
|
|---|---|
|
|
| `campo_textual` | Concatenação sem repetição |
|
|
| `campo_data` | Primeiro valor não-nulo vence |
|
|
| `campo_booleano` | Primeiro valor não-nulo vence |
|
|
|
|
---
|
|
|
|
## Dependências Externas
|
|
|
|
[Tabelas lidas/escritas, filas disparadas, serviços externos.
|
|
Incluir colunas de relacionamento quando relevante.]
|
|
|
|
- Tabelas de negócio: `tabela_a`, `tabela_b`
|
|
- Relacionamentos re-apontados: `tabela_c` via `(codigo_origem, tabela_origem)`
|
|
- Filas: nenhuma / `nome-da-fila`
|
|
- E-mails: nenhum / destinatários e gatilho
|
|
```
|
|
|
|
---
|
|
|
|
## PASSO 4 — Adicionar referência no módulo TypeScript
|
|
|
|
Na **primeira linha útil** do arquivo `.ts` (após shebang ou licença, se houver):
|
|
|
|
```typescript
|
|
// Regras de negócio: ver {modulo}.regras-negocio.md
|
|
|
|
import { ... } from "..."
|
|
```
|
|
|
|
---
|
|
|
|
## PASSO 5 — Limpar JSDoc duplicados
|
|
|
|
Percorrer os JSDoc do módulo e:
|
|
|
|
| Se encontrar | Ação |
|
|
|---|---|
|
|
| JSDoc listando as regras de negócio | Substituir por referência ao `.md` |
|
|
| JSDoc descrevendo critérios de bloqueio | Simplificar para "ver `.md`" |
|
|
| JSDoc com listas de condições | Manter apenas `@param` e `@returns` |
|
|
| Comentário inline explicando uma regra | Manter — comentários de linha são aceitáveis |
|
|
|
|
Exemplo de simplificação:
|
|
|
|
```typescript
|
|
// ❌ Antes — JSDoc duplicando as regras
|
|
/**
|
|
* Retorna false quando:
|
|
* - vencimentos divergentes
|
|
* - executada com datas distintas e não-nulas
|
|
* - vencimento_prorrogado distintos
|
|
* - estado contraditório: nao_executada=true + executada!=null
|
|
*/
|
|
|
|
// ✅ Depois — referência ao .md
|
|
/**
|
|
* Verifica se o grupo pode ser fundido e elege o registro principal.
|
|
* Critérios de bloqueio e regras de eleição: ver regras-negocio.md
|
|
*
|
|
* @param execs - Registros do grupo, ordenados do mais antigo para o mais recente
|
|
* @returns Código do eleito, ou `undefined` quando o grupo vai para revisão manual
|
|
*/
|
|
```
|
|
|
|
---
|
|
|
|
## PASSO 6 — Verificar consistência código ↔ `.md`
|
|
|
|
Percorrer cada regra listada no `.md` e verificar que há código correspondente:
|
|
|
|
- [ ] Cada critério de bloqueio tem um `if (...) return undefined / return retornoVazio`
|
|
- [ ] Cada estratégia de campo tem implementação em `fundirCampos` ou equivalente
|
|
- [ ] A ordem de avaliação no código bate com a ordem no `.md`
|
|
- [ ] Campos exclusivos de certas tabelas estão guardados pelo `if (tabela === ...)`
|
|
- [ ] queries têm `orderBy` quando a posição dos resultados tem significado (ver skill `consultar-banco-knex`)
|
|
|
|
---
|
|
|
|
## Checklist Final
|
|
|
|
- [ ] Arquivo `.md` criado co-localizado com o módulo
|
|
- [ ] Referência `// Regras de negócio: ver ...` na primeira linha do `.ts`
|
|
- [ ] JSDoc simplificados — sem duplicar conteúdo do `.md`
|
|
- [ ] Todas as regras do `.md` têm implementação correspondente no código
|
|
- [ ] Código e `.md` estão consistentes (separadores, campos, condições)
|
|
- [ ] `tsc --noEmit` passa sem erros após qualquer mudança de código
|
|
|
|
---
|
|
|
|
## Referências
|
|
|
|
- Rule: `global/rules/regras-negocio-md`
|
|
- Workflow: `global/workflows/documentar-regras-negocio`
|