112 lines
4.9 KiB
Markdown
112 lines
4.9 KiB
Markdown
---
|
|
name: documentar-dominio-modulo
|
|
scope: global
|
|
updatedAt: "2026-10-14"
|
|
description: >
|
|
Guia para documentar o domínio científico/técnico de cada módulo nas wikis
|
|
de usuário (<modulo-wiki>/<modulo-id>/) e de desenvolvimento (<modulo-wiki>/dev/<modulo-id>/).
|
|
---
|
|
|
|
# Skill: Documentar Domínio de um Módulo
|
|
|
|
Use esta skill ao iniciar um novo módulo SaaS ou ao perceber que o agente não conhece o vocabulário e as regras do domínio que o módulo aborda.
|
|
|
|
Cada módulo opera em uma disciplina diferente da ciência/gestão operacional ou ambiental (licenciamento, efluentes, bombeamento, resíduos, projetos, atendimento, etc.). O repositório `<modulo-wiki>` (configurado em `memorias-ia/modulo.yml`, com fallback padrão para `../wiki/`) é uma **aplicação VitePress**, onde a base factual do domínio é estruturada em dois níveis de acesso:
|
|
1. **Wiki do Usuário (`<modulo-wiki>/<modulo-id>/`):** Aplicação VitePress com **acesso dos usuários e clientes** (linguagem funcional, conceitos, glossário, fluxos e manuais operacionais).
|
|
2. **Wiki de Desenvolvimento (`<modulo-wiki>/dev/<modulo-id>/`):** Aplicação VitePress com **acesso interno exclusivo da equipe de desenvolvimento e arquitetura** (arquitetura técnica, diagramas, modelos de banco, regras de negócio e ADRs).
|
|
|
|
---
|
|
|
|
## PASSO 1 — Identificar a Identidade e Domínio do Módulo via `memorias-ia/modulo.yml`
|
|
|
|
Consultar obrigatoriamente `<base_projeto>/memorias-ia/modulo.yml` na raiz do projeto pai:
|
|
- `modulo-id`: identificador canônico do módulo
|
|
- `modulo-caminho`: rota base na URL
|
|
- `modulo-descricao`: escopo funcional e propósito do módulo
|
|
- `modulo-tipo`: stack tecnológica e arquitetura
|
|
- `modulo-wiki`: caminho relativo ou absoluto para a Wiki (fallback: `../wiki/`)
|
|
|
|
Os destinos canônicos da documentação na aplicação VitePress (`<modulo-wiki>`) são:
|
|
- **Wiki do Usuário:** `<modulo-wiki>/<modulo-id>/`
|
|
- **Wiki de Desenvolvimento:** `<modulo-wiki>/dev/<modulo-id>/`
|
|
|
|
---
|
|
|
|
## PASSO 2 — Criar Documentação na Wiki do Usuário (`<modulo-wiki>/<modulo-id>/`)
|
|
|
|
Estruturar o guia do usuário e conceitos de negócio em linguagem clara e acessível:
|
|
|
|
```markdown
|
|
# [Nome do Módulo] — Guia do Usuário
|
|
|
|
## Visão Geral
|
|
Breve descrição do propósito do módulo para o gestor e operador.
|
|
|
|
## Glossário do Domínio
|
|
| Termo | Definição | Sigla |
|
|
|---|---|---|
|
|
| Ponto de Monitoramento | Local físico onde são coletadas amostras | PM |
|
|
| Parâmetro Ambiental | Variável físico-química monitorada (ex: DBO, DQO) | — |
|
|
|
|
## Fluxos Operacionais do Usuário
|
|
1. Cadastro de entidades base.
|
|
2. Lançamento e acompanhamento de registros.
|
|
3. Emissão de relatórios e acompanhamento de conformidade.
|
|
```
|
|
|
|
### Inclusão de Imagens, Diagramas e Manuais em PDF
|
|
Para enriquecer a Wiki com capturas de tela ou manuais, envie os arquivos para o MinIO Paiol antes de incluí-los no Markdown:
|
|
```bash
|
|
./.agent/scripts/upload-paiol-wiki.sh <caminho-do-arquivo> <slug-funcionalidade>
|
|
```
|
|
Utilize exclusivamente a URL pública gerada (`https://paiol.idz.one/wiki/...`) no Markdown. **Nunca comite arquivos binários no Git da Wiki.**
|
|
|
|
---
|
|
|
|
## PASSO 3 — Criar Documentação na Wiki de Desenvolvimento (`<modulo-wiki>/dev/<modulo-id>/`)
|
|
|
|
Estruturar a especificação técnica, modelos de banco e arquitetura:
|
|
|
|
```markdown
|
|
# [Nome do Módulo] — Arquitetura e Engenharia
|
|
|
|
## Modelo de Dados e Entidades
|
|
- **Tabelas principais:** `<modulo>_entidade_a`, `<modulo>_entidade_b`, `<modulo>_parametros`
|
|
- **Schemas Zod canônicos:** `zEntidadeCriar`, `zRegistroAtualizar` em `<modulo>-comuns`
|
|
|
|
## Processamento Assíncrono e Filas (BullMQ)
|
|
- **Fila `processar_agenda`:** Recalcula status e prazos operacionais.
|
|
|
|
## Rotas e Integração de IA
|
|
- **Rota `/llm.md`:** Disponibiliza catálogo dinâmico de endpoints e contratos.
|
|
```
|
|
|
|
---
|
|
|
|
## PASSO 4 — Conectar com Código e UI
|
|
|
|
1. Verificar se mensagens e labels na UI seguem o vocabulário definido (rule `mensagens-usuario`).
|
|
2. Verificar se componentes e modais possuem `{componente}.ajuda.md` co-localizado (skill `adicionar-ajuda`).
|
|
3. Garantir que funções centrais e serviços possuem comentários claros de aplicação (rule `jsdoc-padrao`).
|
|
4. Assegurar que regras com 3+ critérios possuam `.regras-negocio.md` na Wiki de Desenvolvimento (rule `regras-negocio-md`).
|
|
|
|
---
|
|
|
|
## Checklist Final
|
|
|
|
- [ ] Documentação de usuário criada/atualizada em `<modulo-wiki>/<modulo-id>/`?
|
|
- [ ] Documentação técnica criada/atualizada em `<modulo-wiki>/dev/<modulo-id>/`?
|
|
- [ ] Glossário com os termos centrais do domínio documentado?
|
|
- [ ] Regras e entidades técnicas alinhadas com os schemas Zod do `<modulo>-comuns`?
|
|
- [ ] Rota `/llm.md` no backend reflete o módulo?
|
|
- [ ] Imagens, manuais e anexos hospedados no MinIO Paiol (sem binários no Git da Wiki)?
|
|
|
|
---
|
|
|
|
## Referências
|
|
|
|
- Rule: `rules/ddd-documentacao-primeiro.md`
|
|
- Rule: `rules/identidade-modulo.md`
|
|
- Rule: `rules/jsdoc-padrao.md`
|
|
- Rule: `rules/regras-negocio-md.md`
|
|
- Skill: `skills/adicionar-ajuda/SKILL.md`
|