docuemntação
This commit is contained in:
parent
9fa1b57614
commit
b92dc7b06e
12 changed files with 432 additions and 4 deletions
40
DOCUMENTACAO/INDICE
Normal file
40
DOCUMENTACAO/INDICE
Normal file
|
|
@ -0,0 +1,40 @@
|
|||
---
|
||||
type: structural
|
||||
name: INDICE
|
||||
description: Índice central navegável de todas as categorias de documentação
|
||||
updatedAt: "2026-08-12"
|
||||
---
|
||||
|
||||
# Índice de Documentação
|
||||
|
||||
Este documento serve como ponto central de navegação para todas as documentações do ecossistema. Os documentos serão listados aqui conforme forem criados.
|
||||
|
||||
## Arquitetura
|
||||
Decisões técnicas e arquiteturais (ADRs) que impactam o sistema.
|
||||
**Template**: `DOCUMENTACAO/arquitetura/_template-adr`
|
||||
|
||||
- *(Nenhum documento criado ainda)*
|
||||
|
||||
## Módulos
|
||||
Documentação do domínio, glossário e entidades de cada módulo do sistema.
|
||||
**Template**: `DOCUMENTACAO/modulos/_template-modulo`
|
||||
|
||||
- *(Nenhum documento criado ainda)*
|
||||
|
||||
## Regras de Negócio
|
||||
Regras operacionais e de negócio extraídas do código ou definidas pelos operadores.
|
||||
**Template**: `DOCUMENTACAO/regras-negocio/_template-regra`
|
||||
|
||||
- *(Nenhum documento criado ainda)*
|
||||
|
||||
## Contratos
|
||||
Definição de contratos de API, schemas de dados e especificações de endpoints.
|
||||
**Template**: `DOCUMENTACAO/contratos/_template-contrato`
|
||||
|
||||
- *(Nenhum documento criado ainda)*
|
||||
|
||||
## Fluxos
|
||||
Mapeamento de jornadas do usuário, interações de interface e fluxos de uso do sistema.
|
||||
**Template**: `DOCUMENTACAO/fluxos/_template-fluxo`
|
||||
|
||||
- *(Nenhum documento criado ainda)*
|
||||
53
DOCUMENTACAO/README
Normal file
53
DOCUMENTACAO/README
Normal file
|
|
@ -0,0 +1,53 @@
|
|||
---
|
||||
type: structural
|
||||
name: README
|
||||
description: Manifesto e guia para o Desenvolvimento Orientado a Documentação (DDD)
|
||||
updatedAt: "2026-08-12"
|
||||
---
|
||||
|
||||
# Documentation-Driven Development (DDD)
|
||||
|
||||
## Manifesto
|
||||
No ecossistema Azteca, a documentação precede o código. Nenhum artefato (regra, skill, workflow, módulo, API, decisão técnica) deve ser implementado sem documentação prévia. A documentação é a especificação viva.
|
||||
|
||||
## Princípios
|
||||
1. **Doc First** — Nenhum artefato novo sem documentação prévia.
|
||||
2. **Doc como Contrato** — A documentação é a especificação; o código a implementa.
|
||||
3. **Código Satisfaz Doc** — Se o código diverge da doc, o código está errado.
|
||||
4. **Sincronia Obrigatória** — Mudança no código → atualização da doc; mudança na doc → atualização no código.
|
||||
5. **Templates Padronizados** — Cada categoria tem seu template; nenhuma documentação é criada do zero.
|
||||
6. **Leitura Antes de Escrita** — Antes de documentar, leia o que já existe.
|
||||
|
||||
## Categorias de Documentação
|
||||
|
||||
| Categoria | Diretório | O que documenta | Template |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| Arquitetura | `DOCUMENTACAO/arquitetura/` | Decisões técnicas e arquiteturais (ADRs) | `_template-adr` |
|
||||
| Módulos | `DOCUMENTACAO/modulos/` | Domínio, glossário e entidades de cada módulo | `_template-modulo` |
|
||||
| Regras de Negócio | `DOCUMENTACAO/regras-negocio/` | Regras extraídas do código ou definidas pelo operador | `_template-regra` |
|
||||
| Contratos | `DOCUMENTACAO/contratos/` | Contratos de API, schemas, endpoints | `_template-contrato` |
|
||||
| Fluxos | `DOCUMENTACAO/fluxos/` | Jornadas do usuário e fluxos de uso | `_template-fluxo` |
|
||||
|
||||
## Workflow DDD
|
||||
1. **Receber demanda**
|
||||
2. **Documentar** (criar/atualizar documentação na categoria apropriada usando o template)
|
||||
3. **Revisar** (apresentar a documentação ao operador para validação)
|
||||
4. **Implementar** (codificar de acordo com a documentação aprovada)
|
||||
5. **Validar** (verificar se o código satisfaz a doc 100%)
|
||||
6. **Sincronizar** (atualizar a documentação se a implementação revelou ajustes necessários)
|
||||
|
||||
## Integração com o Ecossistema
|
||||
|
||||
| Artefato | Como Integra com DDD |
|
||||
| :--- | :--- |
|
||||
| `rules/regras-negocio-md.md` | Define formato e obrigatoriedade de documentar regras de negócio |
|
||||
| `skills/documentar-decisao-tecnica` | Fornece habilidade para criar e atualizar ADRs |
|
||||
| `skills/documentar-dominio-modulo` | Estrutura para levantar glossário e domínio de módulos |
|
||||
| `skills/documentar-regras-negocio` | Habilidade para extrair e redigir regras |
|
||||
| `rules/diagnostico-antes-correcao.md`| Diagnóstico exige leitura e alinhamento com doc antes de corrigir bugs |
|
||||
|
||||
## Referências
|
||||
- `rules/ddd-documentacao-primeiro.md`
|
||||
- `skills/documentar-decisao-tecnica`
|
||||
- `skills/documentar-dominio-modulo`
|
||||
- `skills/documentar-regras-negocio`
|
||||
49
DOCUMENTACAO/arquitetura/_template-adr
Normal file
49
DOCUMENTACAO/arquitetura/_template-adr
Normal file
|
|
@ -0,0 +1,49 @@
|
|||
---
|
||||
type: template
|
||||
name: _template-adr
|
||||
description: Template para Architecture Decision Records (ADRs)
|
||||
updatedAt: "2026-08-12"
|
||||
---
|
||||
|
||||
# ADR: <PREENCHER TÍTULO>
|
||||
|
||||
## Data
|
||||
<PREENCHER DATA>
|
||||
|
||||
## Status
|
||||
<Proposta | Aceita | Rejeitada | Descontinuada>
|
||||
|
||||
## Autores
|
||||
<PREENCHER AUTORES>
|
||||
|
||||
## Contexto
|
||||
<Descrever o cenário que motiva a necessidade de uma decisão técnica. O que está acontecendo? Qual o problema a ser resolvido?>
|
||||
|
||||
## Decisão
|
||||
<Descrever claramente a decisão técnica que está sendo tomada para resolver o problema descrito no contexto.>
|
||||
|
||||
## Alternativas Consideradas
|
||||
<Listar outras abordagens avaliadas e os motivos para não terem sido escolhidas.>
|
||||
- Alternativa 1: [...] (Motivo da rejeição: [...])
|
||||
- Alternativa 2: [...] (Motivo da rejeição: [...])
|
||||
|
||||
## Consequências
|
||||
|
||||
### Positivas
|
||||
- <Listar ganhos com a decisão>
|
||||
- [...]
|
||||
|
||||
### Negativas
|
||||
- <Listar desvantagens, trade-offs ou custos gerados>
|
||||
- [...]
|
||||
|
||||
### Neutras
|
||||
- <Listar impactos que não são inerentemente bons ou ruins>
|
||||
- [...]
|
||||
|
||||
## Impacto no Monorepo
|
||||
<Como essa decisão afeta a estrutura existente? Módulos afetados? Mudanças em dependências?>
|
||||
|
||||
## Referências
|
||||
<Links úteis, issues, PRs ou outras documentações que sustentem a decisão>
|
||||
- [...]
|
||||
70
DOCUMENTACAO/contratos/_template-contrato
Normal file
70
DOCUMENTACAO/contratos/_template-contrato
Normal file
|
|
@ -0,0 +1,70 @@
|
|||
---
|
||||
type: template
|
||||
name: _template-contrato
|
||||
description: Template para definição de contratos de API e schemas
|
||||
updatedAt: "2026-08-12"
|
||||
---
|
||||
|
||||
# Contrato: <PREENCHER NOME DO SERVIÇO OU DOMÍNIO>
|
||||
|
||||
## Serviço
|
||||
<Nome e breve descrição do serviço ou microsserviço responsável por esta API>
|
||||
|
||||
## Base URL
|
||||
`<URL base de desenvolvimento e/ou produção>`
|
||||
|
||||
## Autenticação
|
||||
<Como autenticar? Token Bearer, API Key, sem auth?>
|
||||
|
||||
## Endpoints
|
||||
|
||||
| Método | Rota | Descrição | Auth |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `GET` | `/rota/exemplo` | `<Descrição>` | `Sim/Não` |
|
||||
| `POST` | `/rota/exemplo` | `<Descrição>` | `Sim/Não` |
|
||||
|
||||
---
|
||||
|
||||
## Detalhamento por Endpoint
|
||||
|
||||
### `<MÉTODO>` `<ROTA>`
|
||||
<Breve descrição adicional do endpoint>
|
||||
|
||||
**Request Params**
|
||||
- `param1` (tipo, obrigatório?): <descrição>
|
||||
|
||||
**Body Schema**
|
||||
```json
|
||||
{
|
||||
// Exemplo de body esperado
|
||||
}
|
||||
```
|
||||
|
||||
**Response Schema (Sucesso)**
|
||||
```json
|
||||
{
|
||||
// Exemplo de resposta 200/201
|
||||
}
|
||||
```
|
||||
|
||||
**Códigos de Erro**
|
||||
- `400 Bad Request`: <motivo>
|
||||
- `404 Not Found`: <motivo>
|
||||
|
||||
---
|
||||
|
||||
## Schema Zod de Referência
|
||||
<Adicionar fragmento de código Zod caso o projeto utilize validação via schema>
|
||||
```typescript
|
||||
// z.object({ ... })
|
||||
```
|
||||
|
||||
## Exemplos de Uso
|
||||
<Comandos curl, snippets fetch ou scripts de exemplo>
|
||||
```bash
|
||||
curl -X GET ...
|
||||
```
|
||||
|
||||
## Referências
|
||||
<Links para outras documentações, regras de negócio ou ADRs relacionadas>
|
||||
- [...]
|
||||
48
DOCUMENTACAO/fluxos/_template-fluxo
Normal file
48
DOCUMENTACAO/fluxos/_template-fluxo
Normal file
|
|
@ -0,0 +1,48 @@
|
|||
---
|
||||
type: template
|
||||
name: _template-fluxo
|
||||
description: Template para mapeamento de jornadas do usuário e fluxos de uso
|
||||
updatedAt: "2026-08-12"
|
||||
---
|
||||
|
||||
# Fluxo: <PREENCHER NOME DO FLUXO>
|
||||
|
||||
## Objetivo do Fluxo
|
||||
<O que o usuário ou sistema deseja alcançar ao completar este fluxo?>
|
||||
|
||||
## Ator(es)
|
||||
<Quem inicia e participa do fluxo? (Ex: Cliente, Administrador, Sistema, Job em background)>
|
||||
- [...]
|
||||
|
||||
## Pré-condições
|
||||
<O que precisa ser verdadeiro antes deste fluxo iniciar? (Ex: Usuário estar logado, possuir saldo, etc)>
|
||||
- [...]
|
||||
|
||||
## Fluxo Principal
|
||||
<O caminho feliz. O passo a passo em ordem cronológica de como o objetivo é alcançado>
|
||||
1. [...]
|
||||
2. [...]
|
||||
3. [...]
|
||||
|
||||
## Fluxos Alternativos
|
||||
<Caminhos secundários ou desvios do fluxo principal que ainda levam a um resultado bem sucedido (ou parcial)>
|
||||
- **Alternativa A** (Ocorre no passo X se a condição Y for verdadeira):
|
||||
1. [...]
|
||||
2. [...] (retorna ao passo Z do fluxo principal)
|
||||
|
||||
## Tratamento de Erros
|
||||
<Como o fluxo reage a falhas, validações incorretas ou problemas de sistema>
|
||||
- **Erro 1** (Falha no passo X): Ação de mitigação e mensagem de erro apresentada.
|
||||
|
||||
## Regras de Negócio Aplicáveis
|
||||
<Quais regras validam e controlam este fluxo? Linkar para `DOCUMENTACAO/regras-negocio/`>
|
||||
- `Regra X`: [...]
|
||||
- `Regra Y`: [...]
|
||||
|
||||
## Telas Envolvidas
|
||||
<Se aplicável, quais telas da UI compõem o fluxo>
|
||||
- [...]
|
||||
|
||||
## Referências
|
||||
<Links para protótipos, designs, issues ou módulos relacionados>
|
||||
- [...]
|
||||
36
DOCUMENTACAO/modulos/_template-modulo
Normal file
36
DOCUMENTACAO/modulos/_template-modulo
Normal file
|
|
@ -0,0 +1,36 @@
|
|||
---
|
||||
type: template
|
||||
name: _template-modulo
|
||||
description: Template para documentação de módulos e domínios
|
||||
updatedAt: "2026-08-12"
|
||||
---
|
||||
|
||||
# Módulo: <PREENCHER NOME DO MÓDULO>
|
||||
|
||||
## Área de Conhecimento
|
||||
<Descrever brevemente o domínio de negócio deste módulo. Qual sua responsabilidade principal e área de atuação no ecossistema?>
|
||||
|
||||
## Glossário do Módulo
|
||||
|
||||
| Termo | Definição | Contexto de Uso |
|
||||
| :--- | :--- | :--- |
|
||||
| `<Termo 1>` | `<Definição>` | `<Contexto>` |
|
||||
| `<Termo 2>` | `<Definição>` | `<Contexto>` |
|
||||
|
||||
## Entidades Principais
|
||||
<Descrever as entidades de dados fundamentais que compõem este módulo>
|
||||
- **Entidade A**: <Descrição do papel da entidade e principais atributos>.
|
||||
- **Entidade B**: <Descrição do papel da entidade e principais atributos>.
|
||||
|
||||
## Legislação Aplicável
|
||||
<Listar leis, normas técnicas ou portarias que afetam as regras deste domínio, se aplicável>
|
||||
- [...]
|
||||
|
||||
## Fluxos do Domínio
|
||||
<Listar os fluxos de negócios centrais orquestrados por este módulo, referenciando documentos em `DOCUMENTACAO/fluxos/` se existirem>
|
||||
- **Fluxo Principal X**: [...]
|
||||
- **Fluxo Principal Y**: [...]
|
||||
|
||||
## Vocabulário de Interface
|
||||
<Termos específicos que devem ser usados na UI para manter a consistência com a linguagem ubíqua do domínio>
|
||||
- [...]
|
||||
34
DOCUMENTACAO/regras-negocio/_template-regra
Normal file
34
DOCUMENTACAO/regras-negocio/_template-regra
Normal file
|
|
@ -0,0 +1,34 @@
|
|||
---
|
||||
type: template
|
||||
name: _template-regra
|
||||
description: Template para especificação de regras de negócio
|
||||
updatedAt: "2026-08-12"
|
||||
---
|
||||
|
||||
# Regra: <PREENCHER NOME DA REGRA>
|
||||
|
||||
## Contexto
|
||||
<Descrever em qual situação, processo ou fluxo essa regra é aplicada. Qual o propósito de negócio dela?>
|
||||
|
||||
## Critérios de Entrada / Identificação
|
||||
<O que aciona essa regra? Quais dados ou condições precisam existir para que ela seja avaliada?>
|
||||
- Condição 1: [...]
|
||||
- Condição 2: [...]
|
||||
|
||||
## Regras de Processamento
|
||||
<Passo a passo lógico e determinístico da regra. Como a validação ou transformação acontece?>
|
||||
1. [...]
|
||||
2. [...]
|
||||
3. [...]
|
||||
|
||||
## Casos de Revisão Manual
|
||||
<Existem exceções onde o sistema não decide automaticamente e envia para análise humana? Listar os cenários.>
|
||||
- Cenário A: [...]
|
||||
|
||||
## Estratégia de Fusão / Resultado
|
||||
<Qual é o output da execução dessa regra? (ex: aprovação, recusa, alteração de status, cálculo final)>
|
||||
- [...]
|
||||
|
||||
## Dependências Externas
|
||||
<A regra depende de integrações de terceiros, APIs, ou outras regras do sistema para ser processada?>
|
||||
- [...]
|
||||
Loading…
Add table
Add a link
Reference in a new issue