agente documentação

2026-08-12 15:26:26 -03:00 · 2026-08-12 15:26:26 -03:00 · 5f11352ab7
commit 5f11352ab7
parent b92dc7b06e
11 changed files with 239 additions and 158 deletions
--- a/DOCUMENTACAO/_templates/_template-adr
+++ b/DOCUMENTACAO/_templates/_template-adr
@ -0,0 +1,46 @@
+---
+type: template
+name: _template-adr
+description: Template para Architecture Decision Records (ADRs) — decisões transversais
+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? Funcionalidades afetadas? Mudanças em dependências?>
+
+## Referências
+<Links úteis, issues, PRs ou outras documentações que sustentem a decisão>
+- [...]
--- a/DOCUMENTACAO/_templates/_template-contrato
+++ b/DOCUMENTACAO/_templates/_template-contrato
@ -0,0 +1,69 @@
+---
+type: template
+name: _template-contrato
+description: Template para definição de contratos de API e schemas de uma funcionalidade
+updatedAt: "2026-08-12"
+---
+
+# Contrato de API — <PREENCHER NOME DA FUNCIONALIDADE>
+
+## Serviço
+<Nome e breve descrição do serviç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
+```typescript
+// z.object({ ... })
+```
+
+## Exemplos de Uso
+```bash
+curl -X GET ...
+```
+
+## Referências
+- Especificação: `especificacao.md` (co-localizado)
+- Regras de negócio: `regras-negocio.md` (co-localizado)
+- [...]
--- a/DOCUMENTACAO/_templates/_template-especificacao
+++ b/DOCUMENTACAO/_templates/_template-especificacao
@ -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)
+- [...]
--- a/DOCUMENTACAO/_templates/_template-fluxo
+++ b/DOCUMENTACAO/_templates/_template-fluxo
@ -0,0 +1,48 @@
+---
+type: template
+name: _template-fluxo
+description: Template para mapeamento de jornadas do usuário e fluxos de uso de uma funcionalidade
+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?>
+- [...]
+
+## Pré-condições
+<O que precisa ser verdadeiro antes deste fluxo iniciar?>
+- [...]
+
+## Fluxo Principal
+<O caminho feliz, passo a passo em ordem cronológica>
+1. [...]
+2. [...]
+3. [...]
+
+## Fluxos Alternativos
+<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 apresentada.
+
+## Regras de Negócio Aplicáveis
+<Quais regras validam e controlam este fluxo? Referenciar `regras-negocio.md` co-localizado>
+- Regra X: [...]
+
+## Telas Envolvidas
+<Quais telas da UI compõem o fluxo?>
+- [...]
+
+## Referências
+- Especificação: `especificacao.md` (co-localizado)
+- Regras de negócio: `regras-negocio.md` (co-localizado)
+- [...]
--- a/DOCUMENTACAO/_templates/_template-regras-negocio
+++ b/DOCUMENTACAO/_templates/_template-regras-negocio
@ -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)
+- [...]