Como contribuir
Comece pela definição humana
Este repositório é um quadro em branco orientado por engenheiros e arquitetos. Antes de preencher uma camada, obtenha as definições do responsável ou a indicação expressa do material e do escopo a documentar. A IA pode organizar esse conteúdo; não deve inferir o que falta a partir dos repositórios.
Leia AGENTS.md, architecture.md e a skill nead-domain-docs. Para contratos, aplique também nead-api-contracts; para regras de negócio, nead-business-rules.
Sete camadas obrigatórias
- Overview: propósito, vocabulário, escopo e fronteiras definidos.
- Entidades e relacionamentos: entidades, atributos, chaves, cardinalidades, integridade e diagrama fornecidos.
- Histórias do usuário: atores, necessidades, benefícios e critérios informados.
- Casos de uso: condições, fluxos, alternativas e resultados definidos.
- Sitemap: rotas, páginas, acessos e transições indicados.
- API Reference: operações e contratos de entrada, saída, erros e acesso fornecidos.
- Regras de negócio: enunciados, condições, restrições, exceções, vigência e decisões dos responsáveis.
Use as perguntas de cada página como pauta. Registre dúvidas e pendências sem preenchê-las com hipóteses. Uma página vazia não significa que a funcionalidade inexista.
Criar um espaço de domínio
npm run docs:new -- meu-dominio "Meu domínio"
O comando cria sete roteiros vazios. O nome e o escopo devem ser orientados pelo responsável. Nenhum repositório é consultado para gerar conteúdo.
Preencher e revisar
Cada página exporta o registro documentation como JSON em uma linha e exibe DocumentationStatus. Os campos são:
| Campo | Como preencher |
|---|---|
| status | empty, draft ou approved. |
| owner | Identificação do responsável humano pelo conteúdo; null no quadro vazio. |
| source | Referência localizável à instrução, documento, issue ou decisão fornecida pelo responsável; null no quadro vazio. |
| approvedBy | Humano que aprovou expressamente; null até aprovação. |
| approvedAt | Data da aprovação expressa em YYYY-MM-DD; null até aprovação. |
Quadro em branco (empty): mantenha o roteiro intacto. Seu propósito é orientar a coleta de definições.
Rascunho (draft): ao receber material humano, registre responsável e fonte, substitua os campos pertinentes e preserve o que estiver pendente. Não registre aprovação antecipadamente.
Aprovado (approved): somente após decisão humana expressa, registre aprovador, data e referência da decisão. Uma aprovação do deploy ou sucesso de CI não aprova o conteúdo do produto. Mudanças de significado voltam a rascunho e removem a aprovação anterior do registro atual.
Identificadores e vínculos
Use US-DOMINIO-NNN, UC-DOMINIO-NNN e RN-DOMINIO-NNN para histórias, casos de uso e regras efetivamente definidos. Vincule as camadas conforme as relações indicadas pelo responsável. Não crie exemplos de negócio, regras complementares ou relações por inferência.
Diagramas ER podem ser fornecidos em Mermaid e apresentados com ERDiagram. O desenho e suas cardinalidades precisam refletir o material orientador. Nenhum contrato, modelo ER ou regra deve ser importado automaticamente.
Validar e publicar
npm run check
npm run build
O validador aceita quadros vazios intactos e exige autoria/fonte para conteúdo preenchido. Ele verifica estrutura, estados e links; a revisão humana verifica o significado e a origem das definições. Confira navegação, busca, tabelas e diagramas das páginas afetadas.
Registre na revisão quais definições foram fornecidas, o que mudou e quais pendências permanecem. A publicação preserva o estado editorial visível. Não recupere conteúdo antigo do histórico para preencher lacunas.