agente documentação

This commit is contained in:
Luiz Silva 2026-08-12 15:26:26 -03:00
parent b92dc7b06e
commit 5f11352ab7
11 changed files with 239 additions and 158 deletions

View file

@ -1,40 +1,64 @@
---
type: structural
name: INDICE
description: Índice central navegável de todas as categorias de documentação
description: Índice central navegável da documentação organizada por funcionalidade
updatedAt: "2026-08-12"
---
# Índice de Documentação
# Índice de Documentação — Qualifica
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.
Este documento serve como ponto central de navegação para toda a documentação do módulo Qualifica. A documentação é organizada por **funcionalidade**, onde cada pasta agrupa especificação técnica, regras de negócio, contratos e fluxos.
## Arquitetura
Decisões técnicas e arquiteturais (ADRs) que impactam o sistema.
**Template**: `DOCUMENTACAO/arquitetura/_template-adr`
**Templates**: `DOCUMENTACAO/_templates/`
**Funcionalidades**: `DOCUMENTACAO/funcionalidades/`
---
## Avaliações
Ciclos de avaliação, envios, análise e preenchimento — funcionalidade core do sistema.
- `funcionalidades/avaliacoes/especificacao.md` — Spec técnica (schemas Zod, DDL, fluxos)
- `funcionalidades/avaliacoes/regras-negocio.md` — Ciclos, prazos, envios e reenvios
## Empresas
Cadastro de empresas, painel da empresa, empreendedores, empreendimentos e contatos.
- *(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`
## Formulários
Builder de formulários, seções, campos e respostas.
- *(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`
## Contratos Comerciais
Gestão de contratos comerciais.
- *(Nenhum documento criado ainda)*
## Contratos
Definição de contratos de API, schemas de dados e especificações de endpoints.
**Template**: `DOCUMENTACAO/contratos/_template-contrato`
## Relatórios
Relatórios em PDF, histórico, documentos e eventos.
- *(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`
## Importador
Importação de dados externos.
- *(Nenhum documento criado ainda)*
## Ajuda e Suporte
Sistema de chamados, diagnóstico de ambiente e suporte contextual.
- `funcionalidades/ajuda-suporte/especificacao.md` — Arquitetura, componentes, fluxos e UX
## Validade
Controle de validade.
- *(Nenhum documento criado ainda)*
---
## Transversais
Decisões arquiteturais (ADRs) e documentação que cruza funcionalidades.
**Template ADR**: `_templates/_template-adr`
- *(Nenhum documento criado ainda)*

View file

@ -8,33 +8,72 @@ 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.
No ecossistema Azteca, a documentação precede o código. Nenhum artefato (regra, skill, workflow, funcionalidade, 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.
5. **Templates Padronizados** — Cada tipo de documento tem seu template centralizado em `_templates/`.
6. **Co-localização** — Toda documentação de uma funcionalidade fica na pasta daquela funcionalidade.
7. **Leitura Antes de Escrita** — Antes de documentar, leia o que já existe.
## Categorias de Documentação
## Organização — Por Funcionalidade
| 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` |
A `DOCUMENTACAO/` é organizada por **funcionalidade/domínio funcional** do módulo Qualifica, não por tipo de documento.
### Estrutura
```text
DOCUMENTACAO/
├── README.md ← Índice geral (público)
├── funcionalidades/ ← Subdivisão por funcionalidade
│ └── <funcionalidade>/ ← Uma pasta por funcionalidade
│ ├── especificacao.md ← Spec técnica (schemas, DDL, componentes)
│ ├── regras-negocio.md ← Regras de negócio em linguagem natural
│ ├── contratos.md ← Endpoints de API (quando aplicável)
│ └── fluxo.md ← Fluxograma detalhado (quando aplicável)
├── _transversais/ ← ADRs e decisões que cruzam funcionalidades
│ └── adr-NNN-titulo.md
└── _templates/ ← Templates (espelhados de .agent/DOCUMENTACAO/_templates/)
```
### Funcionalidades do Qualifica
| Funcionalidade | Pasta | Domínio |
| :--- | :--- | :--- |
| Avaliações | `funcionalidades/avaliacoes/` | Ciclos de avaliação, envios, análise, preenchimento |
| Empresas | `funcionalidades/empresas/` | Cadastro, painel, empreendedores, contatos |
| Formulários | `funcionalidades/formularios/` | Builder, seções, campos, respostas |
| Contratos Comerciais | `funcionalidades/contratos-comerciais/` | Gestão de contratos |
| Relatórios | `funcionalidades/relatorios/` | PDFs, histórico, documentos, eventos |
| Importador | `funcionalidades/importador/` | Importação de dados |
| Ajuda e Suporte | `funcionalidades/ajuda-suporte/` | Chamados, diagnóstico, suporte contextual |
| Validade | `funcionalidades/validade/` | Controle de validade |
### Tipos de Documento (dentro de cada funcionalidade)
| Arquivo | Template | Quando criar |
| :--- | :--- | :--- |
| `especificacao.md` | `_templates/_template-especificacao` | Sempre — é o doc mínimo de cada funcionalidade |
| `regras-negocio.md` | `_templates/_template-regras-negocio` | Quando a funcionalidade tem lógica de decisão não-trivial |
| `contratos.md` | `_templates/_template-contrato` | Quando a funcionalidade expõe endpoints de API |
| `fluxo.md` | `_templates/_template-fluxo` | Quando a funcionalidade tem ciclo de vida complexo |
### Documentação Transversal
Decisões arquiteturais (ADRs) e documentação que cruza múltiplas funcionalidades ficam em `_transversais/`, usando o template `_templates/_template-adr`.
## 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)
2. **Identificar funcionalidade** — Determinar a qual funcionalidade a demanda pertence
3. **Consultar template** — Usar o template adequado de `_templates/`
4. **Documentar** — Criar/atualizar documentação na pasta da funcionalidade
5. **Revisar** — Apresentar a documentação ao operador para validação
6. **Implementar** — Codificar de acordo com a documentação aprovada
7. **Validar** — Verificar se o código satisfaz a doc 100%
8. **Sincronizar** — Atualizar a documentação se a implementação revelou ajustes
## Integração com o Ecossistema
@ -42,7 +81,7 @@ No ecossistema Azteca, a documentação precede o código. Nenhum artefato (regr
| :--- | :--- |
| `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-dominio-modulo` | Estrutura para levantar glossário e domínio |
| `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 |

View file

@ -1,7 +1,7 @@
---
type: template
name: _template-adr
description: Template para Architecture Decision Records (ADRs)
description: Template para Architecture Decision Records (ADRs) — decisões transversais
updatedAt: "2026-08-12"
---
@ -31,18 +31,15 @@ updatedAt: "2026-08-12"
### 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?>
<Como essa decisão afeta a estrutura existente? Funcionalidades afetadas? Mudanças em dependências?>
## Referências
<Links úteis, issues, PRs ou outras documentações que sustentem a decisão>

View file

@ -1,14 +1,14 @@
---
type: template
name: _template-contrato
description: Template para definição de contratos de API e schemas
description: Template para definição de contratos de API e schemas de uma funcionalidade
updatedAt: "2026-08-12"
---
# Contrato: <PREENCHER NOME DO SERVIÇO OU DOMÍNIO>
# Contrato de API — <PREENCHER NOME DA FUNCIONALIDADE>
## Serviço
<Nome e breve descrição do serviço ou microsserviço responsável por esta API>
<Nome e breve descrição do serviço responsável por esta API>
## Base URL
`<URL base de desenvolvimento e/ou produção>`
@ -54,17 +54,16 @@ updatedAt: "2026-08-12"
---
## 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>
- Especificação: `especificacao.md` (co-localizado)
- Regras de negócio: `regras-negocio.md` (co-localizado)
- [...]

View file

@ -0,0 +1,52 @@
---
type: template
name: _template-especificacao
description: Template para especificação técnica de uma funcionalidade do módulo
updatedAt: "2026-08-12"
---
# Especificação: <PREENCHER NOME DA FUNCIONALIDADE>
## Área de Conhecimento
<Descrever brevemente o domínio de negócio desta funcionalidade. Qual sua responsabilidade principal dentro do módulo?>
## Glossário
| Termo | Definição | Contexto de Uso |
| :--- | :--- | :--- |
| `<Termo 1>` | `<Definição>` | `<Contexto>` |
## Entidades Principais
<Descrever as entidades de dados que compõem esta funcionalidade>
- **Entidade A**: <Descrição do papel e principais atributos>.
## Schemas Zod
<Referenciar os schemas Zod em `qualifica-comuns/src/tabelas/` que sustentam esta funcionalidade>
- `_entidade.ts` — <descrição>
## Estrutura de Dados (DDL)
<Se aplicável, descrever a estrutura SQL das tabelas envolvidas>
```sql
-- DDL da tabela principal
```
## Componentes de Interface
<Listar as páginas e componentes Vue envolvidos nesta funcionalidade>
- `PaginaX/` — <descrição>
- `ComponenteY.vue` — <descrição>
## Fluxos do Domínio
<Listar os fluxos de negócio orquestrados por esta funcionalidade, referenciando `fluxo.md` co-localizado se existir>
- **Fluxo Principal**: [...]
## Legislação Aplicável
<Listar leis, normas técnicas ou portarias que afetam esta funcionalidade, se aplicável>
- [...]
## Vocabulário de Interface
<Termos específicos que devem ser usados na UI para manter consistência com a linguagem ubíqua do domínio>
- [...]
## Referências
- Regras de negócio: `regras-negocio.md` (co-localizado)
- [...]

View file

@ -1,7 +1,7 @@
---
type: template
name: _template-fluxo
description: Template para mapeamento de jornadas do usuário e fluxos de uso
description: Template para mapeamento de jornadas do usuário e fluxos de uso de uma funcionalidade
updatedAt: "2026-08-12"
---
@ -11,38 +11,38 @@ updatedAt: "2026-08-12"
<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)>
<Quem inicia e participa do fluxo?>
- [...]
## Pré-condições
<O que precisa ser verdadeiro antes deste fluxo iniciar? (Ex: Usuário estar logado, possuir saldo, etc)>
<O que precisa ser verdadeiro antes deste fluxo iniciar?>
- [...]
## Fluxo Principal
<O caminho feliz. O passo a passo em ordem cronológica de como o objetivo é alcançado>
<O caminho feliz, passo a passo em ordem cronológica>
1. [...]
2. [...]
3. [...]
## Fluxos Alternativos
<Caminhos secundários ou desvios do fluxo principal que ainda levam a um resultado bem sucedido (ou parcial)>
<Caminhos secundários ou desvios do fluxo principal>
- **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.
- **Erro 1** (Falha no passo X): Ação de mitigação e mensagem apresentada.
## Regras de Negócio Aplicáveis
<Quais regras validam e controlam este fluxo? Linkar para `DOCUMENTACAO/regras-negocio/`>
- `Regra X`: [...]
- `Regra Y`: [...]
<Quais regras validam e controlam este fluxo? Referenciar `regras-negocio.md` co-localizado>
- Regra X: [...]
## Telas Envolvidas
<Se aplicável, quais telas da UI compõem o fluxo>
<Quais telas da UI compõem o fluxo?>
- [...]
## Referências
<Links para protótipos, designs, issues ou módulos relacionados>
- Especificação: `especificacao.md` (co-localizado)
- Regras de negócio: `regras-negocio.md` (co-localizado)
- [...]

View file

@ -0,0 +1,43 @@
---
type: template
name: _template-regras-negocio
description: Template para especificação de regras de negócio de uma funcionalidade
updatedAt: "2026-08-12"
---
# Regras de Negócio — <PREENCHER NOME DA FUNCIONALIDADE>
Funcionalidade: `<nome da funcionalidade>`
Localização: `DOCUMENTACAO/<funcionalidade>/`
---
## Contexto
<Descrever em qual situação, processo ou fluxo estas regras são aplicadas. Qual o propósito de negócio?>
## Critérios de Entrada / Identificação
<O que aciona estas regras? Quais dados ou condições precisam existir?>
- Condição 1: [...]
- Condição 2: [...]
## Regras de Processamento
<Passo a passo lógico e determinístico. 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?>
- Cenário A: [...]
## Estratégia de Fusão / Resultado
<Qual é o output da execução destas regras? (ex: aprovação, recusa, alteração de status, cálculo final)>
- [...]
## Dependências Externas
<As regras dependem de integrações de terceiros, APIs, ou outras funcionalidades do sistema?>
- [...]
## Referências
- Especificação: `especificacao.md` (co-localizado)
- [...]

View file

@ -1,36 +0,0 @@
---
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>
- [...]

View file

@ -1,34 +0,0 @@
---
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?>
- [...]