---
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.md`
- Workflow: `global/workflows/documentar-regras-negocio.md`