102 lines
4.5 KiB
Text
102 lines
4.5 KiB
Text
---
|
|
name: documentar-dominio-modulo
|
|
scope: global
|
|
updatedAt: "2026-09-01"
|
|
description: >
|
|
Guia para documentar o domínio científico/técnico de cada módulo nas wikis
|
|
de usuário (<base_projeto>/../wiki/<modulo>/) e de desenvolvimento (<base_projeto>/../wiki/dev/<modulo>/).
|
|
---
|
|
|
|
# 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 ambiental (licenciamento, efluentes, bombeamento, resíduos, projetos, etc.). O repositório `<base_projeto>/../wiki` é uma **aplicação VitePress**, onde a base factual do domínio é estruturada em dois níveis de acesso:
|
|
1. **Wiki do Usuário (`<base_projeto>/../wiki/<modulo>/`):** Aplicação VitePress com **acesso dos usuários e clientes** (linguagem funcional, conceitos, glossário, fluxos e manuais operacionais).
|
|
2. **Wiki de Desenvolvimento (`<base_projeto>/../wiki/dev/<modulo>/`):** 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 o Domínio do Módulo
|
|
|
|
Determinar qual área da ciência/gestão o módulo aborda:
|
|
|
|
| Exemplo de módulo | Domínio | Destino Usuário | Destino Dev |
|
|
|---|---|---|---|
|
|
| SIGMA | Monitoramento ambiental (efluentes, piezometria, bombeamento) | `<base_projeto>/../wiki/e-licencie.sigma/` | `<base_projeto>/../wiki/dev/e-licencie.sigma/` |
|
|
| Licenciamento | Gestão de licenças (LP, LI, LO, condicionantes) | `<base_projeto>/../wiki/e-licencie/` | `<base_projeto>/../wiki/dev/e-licencie/` |
|
|
| Resíduos | Gestão de resíduos sólidos (PGRS, MTR, MTR-e) | `<base_projeto>/../wiki/e-licencie.residuos/` | `<base_projeto>/../wiki/dev/e-licencie.residuos/` |
|
|
| Qualificação | Qualificação e conformidade de fornecedores | `<base_projeto>/../wiki/e-licencie.qualifica/` | `<base_projeto>/../wiki/dev/e-licencie.qualifica/` |
|
|
|
|
---
|
|
|
|
## PASSO 2 — Criar Documentação na Wiki do Usuário (`<base_projeto>/../wiki/<modulo>/`)
|
|
|
|
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 pontos de monitoramento.
|
|
2. Lançamento e importação de medições.
|
|
3. Emissão de relatórios e acompanhamento de conformidade.
|
|
```
|
|
|
|
---
|
|
|
|
## PASSO 3 — Criar Documentação na Wiki de Desenvolvimento (`<base_projeto>/../wiki/dev/<modulo>/`)
|
|
|
|
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:** `sigma_pontos`, `sigma_medicoes`, `sigma_parametros`
|
|
- **Schemas Zod canônicos:** `zPontoCriar`, `zMedicaoRegistrar` em `*-comuns`
|
|
|
|
## Processamento Assíncrono e Filas (BullMQ)
|
|
- **Fila `calcular_agenda`:** Recalcula status e prazos de monitoramento.
|
|
|
|
## 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 Vue possuem `modalX.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` co-localizado (rule `regras-negocio-md`).
|
|
|
|
---
|
|
|
|
## Checklist Final
|
|
|
|
- [ ] Documentação de usuário criada/atualizada em `<base_projeto>/../wiki/<modulo>/`?
|
|
- [ ] Documentação técnica criada/atualizada em `<base_projeto>/../wiki/dev/<modulo>/`?
|
|
- [ ] Glossário com os termos centrais do domínio documentado?
|
|
- [ ] Regras e entidades técnicas alinhadas com os schemas Zod do `*-comuns`?
|
|
- [ ] Rota `/llm.md` no backend reflete o módulo?
|
|
|
|
---
|
|
|
|
## Referências
|
|
|
|
- Rule: `rules/ddd-documentacao-primeiro.md`
|
|
- Rule: `rules/jsdoc-padrao.md`
|
|
- Rule: `rules/regras-negocio-md.md`
|
|
- Skill: `skills/adicionar-ajuda/SKILL.md`
|
|
|