105 lines
3.6 KiB
Markdown
105 lines
3.6 KiB
Markdown
---
|
|
name: documentar-regras-negocio
|
|
description: Criar ou atualizar o arquivo {modulo}.regras-negocio.md na Wiki de Desenvolvimento (<modulo-wiki>/dev/<modulo-id>/) e garantir consistência com o código TypeScript.
|
|
scope: global
|
|
updatedAt: "2026-09-01"
|
|
---
|
|
|
|
# Workflow / Skill: Documentar Regras de Negócio de um Módulo
|
|
|
|
Use este workflow para criar ou atualizar o arquivo de regras de negócio de qualquer módulo TypeScript com lógica não-trivial, armazenado na **Wiki de Desenvolvimento** em `<modulo-wiki>/dev/<modulo-id>/` (onde `<modulo-wiki>` e `<modulo-id>` são extraídos de `memorias-ia/modulo.yml`, com fallback padrão `../wiki/`).
|
|
|
|
---
|
|
|
|
[1] Ler o módulo TypeScript completamente
|
|
|
|
Identificar e anotar:
|
|
|
|
- Nome do arquivo e localização exata no código
|
|
- Funções exportadas e suas responsabilidades
|
|
- Todos os `if` que representam critérios de decisão
|
|
- Campos lidos e gravados (especialmente JSONB e campos de status)
|
|
- Queries de banco: tabelas acessadas, filtros aplicados, joins
|
|
- Caminhos alternativos (revisão manual, erros, skips)
|
|
- Dependências externas (filas BullMQ, e-mails, serviços)
|
|
|
|
---
|
|
|
|
[2] Verificar se já existe a documentação de regras na Wiki de Desenvolvimento
|
|
|
|
```bash
|
|
ls <modulo-wiki>/dev/<modulo-id>/*regras-negocio*.md 2>/dev/null
|
|
```
|
|
|
|
- **Existe** → ler e identificar o que está desatualizado → ir para o passo [4]
|
|
- **Não existe** → ir para o passo [3]
|
|
|
|
---
|
|
|
|
[3] Criar o arquivo de regras na Wiki de Desenvolvimento
|
|
|
|
**Localização:** `<modulo-wiki>/dev/<modulo-id>/{nome-do-modulo}.regras-negocio.md` (ou `<modulo-wiki>/dev/<modulo-id>/regras-negocio/`).
|
|
|
|
Preencher com a estrutura padrão:
|
|
- Contexto operacional
|
|
- Critérios de Entrada
|
|
- Regras de Processamento (numeradas em ordem estrita)
|
|
- Casos de Revisão Manual
|
|
- Estratégia de Saída / Persistência de Campos
|
|
- Dependências Externas (tabelas, filas, CRONs)
|
|
|
|
---
|
|
|
|
[4] Adicionar ou verificar a referência no `.ts`
|
|
|
|
Garantir que a primeira linha útil do arquivo TypeScript seja:
|
|
|
|
```typescript
|
|
// Regras de negócio: ver <modulo-wiki>/dev/<modulo-id>/{modulo}.regras-negocio.md
|
|
```
|
|
|
|
Se já existia e está correto → sem mudança necessária.
|
|
|
|
---
|
|
|
|
[5] Estruturar JSDoc com aplicação prática e referência ao `.regras-negocio.md`
|
|
|
|
Percorrer cada função do módulo:
|
|
|
|
- Inserir JSDoc explicando a aplicação prática da função no sistema (rule `rules/jsdoc-padrao.md`).
|
|
- Referenciar o arquivo `.regras-negocio.md` para a lista detalhada de regras e critérios de decisão.
|
|
- Manter `@param` com contexto do domínio, `@returns` e `@throws`.
|
|
- Manter comentários inline (`//`) explicando cálculos pontuais ou regras de exceção.
|
|
|
|
---
|
|
|
|
[6] Verificar consistência — código ↔ `.regras-negocio.md`
|
|
|
|
Para cada regra listada no `.regras-negocio.md`:
|
|
|
|
- [ ] Existe `if` correspondente no código
|
|
- [ ] A ordem de avaliação bate entre `.regras-negocio.md` e código
|
|
- [ ] Campos com separador de concatenação batem entre documentação e código
|
|
- [ ] `null` como neutro está implementado corretamente (`!= null`)
|
|
- [ ] Queries têm `orderBy` quando a posição dos resultados importa
|
|
|
|
---
|
|
|
|
[7] Validar tipagem
|
|
|
|
// turbo
|
|
```bash
|
|
npx tsc --noEmit
|
|
```
|
|
|
|
Zero erros = concluído.
|
|
|
|
---
|
|
|
|
[8] Sincronizar com a Wiki de Desenvolvimento e Memórias
|
|
|
|
Se o módulo introduziu ou alterou arquitetura ou regras consolidadas do módulo:
|
|
|
|
- Atualizar a especificação técnica na **Wiki de Desenvolvimento** em `<modulo-wiki>/dev/<modulo-id>/`.
|
|
- Criar ou atualizar ADR em `<modulo-wiki>/dev/<modulo-id>/adrs/` via skill `documentar-decisao-tecnica`.
|
|
- Registrar decisões e ações na memória em `<base_projeto>/memorias-ia/`.
|