| name | api-rules-documentation |
| description | Documentar regras de negócio e contratos da API com rastreabilidade total ao código, garantindo cobertura completa, clareza de consumo e consistência entre backend e frontend. |
API Rules Documentation
Objetivo
Criar ou atualizar documentação técnica da API garantindo:
- Cobertura completa das regras implementadas no backend
- Contrato de consumo detalhado, realista e utilizável
- Rastreabilidade direta ao código
- Clareza suficiente para consumo sem necessidade de leitura do código
Usar references/doc-template.md como base quando não houver template do time.
Destinos padrões:
documentações tecnica/../Core-Front/documentação tecnica/API/
Fonte de verdade
A documentação deve ser baseada EXCLUSIVAMENTE em:
- Código fonte
- Testes automatizados
Nunca assumir comportamento sem evidência.
Regras obrigatórias permanentes
1) Índice "Resumo" (OBRIGATÓRIO)
Deve conter:
- descrição do módulo/controller
- lista de TODOS endpoints atuais
- endpoints descontinuados (quando identificados)
2) Cobertura total da controller
Ao atualizar documentação:
- Documentar TODA a controller
- Nunca documentar apenas endpoints alterados
3) Contrato completo (OBRIGATÓRIO)
Para cada endpoint:
- Request completo (body, params, query)
- Response completo (JSON realista)
Se houver DTO compartilhado:
→ criar seção Contratos completos
4) Exemplos reais (CRÍTICO)
-
Exemplos devem refletir:
- estrutura real
- nomes reais
- tipos reais
-
Nunca usar:
- exemplos genéricos
- campos fictícios
5) Regras de negócio (OBRIGATÓRIO)
Para cada endpoint, detalhar:
- validações
- condicionais
- limites
- bloqueios
E também o fluxo:
- Validação
- Processamento
- Persistência
- Retorno
6) Efeitos colaterais (OBRIGATÓRIO)
Descrever explicitamente:
- alterações em outras entidades
- logs
- eventos
- integrações externas
7) Autorização (OBRIGATÓRIO)
Informar claramente:
- quem pode acessar
- regras de permissão
- dependência de usuário/autenticação
8) Enums e valores possíveis
Para campos relevantes, documentar:
- valores possíveis
- significado de cada valor
9) Erros (OBRIGATÓRIO)
Nunca usar linguagem vaga.
Para cada erro:
- status HTTP
- condição de disparo
- mensagem/código (quando possível)
10) Rastreabilidade (OBRIGATÓRIO)
Sempre citar:
- Controller
- Service / UseCase
- DTOs
- Repository
- Enums
- Exceptions
- Testes (quando existirem)
11) Fato vs Inferência
Separar:
- Fato confirmado
- Inferência
12) Sincronização Frontend
Fluxo de execução
- Identificar escopo
- Analisar código completo
- Mapear regras reais
- Mapear contrato completo
- Documentar controller inteira
- Replicar no frontend
Estrutura recomendada
- Resumo (índice geral)
- Contratos completos (DTOs)
- Endpoints detalhados
- Matriz de erros
- Efeitos colaterais
- Rastreabilidade
- Fatos vs inferências
- Pendências
Checklist por endpoint
- Objetivo
- Autorização
- Validações
- Regras de negócio
- Fluxo de execução
- Efeitos colaterais
- Response completo
- Erros detalhados
- Exemplo real
Validação final
Antes de concluir:
- Conferir nomes reais (rotas, DTOs, enums)
- Validar consistência com código
- Validar consistência com frontend
- Validar ausência de lacunas
Se houver dúvidas:
→ registrar em Pendências
Formato de entrega
A resposta deve conter:
- Arquivos criados/atualizados
- Resumo das regras documentadas
- Pendências identificadas
- Divergências entre front e back (se houver)
