aplimoramento de agent
This commit is contained in:
parent
b361f25955
commit
f597436be3
83 changed files with 1312 additions and 574 deletions
|
|
@ -14,39 +14,43 @@ Este documento serve como mapa de navegação para os **6 pilares de documentaç
|
|||
## 1. Código-Fonte (JSDoc e Comentários de Aplicação)
|
||||
Documentação interna nos arquivos `.ts`, `.vue`, `.js` com foco na aplicação prática no sistema.
|
||||
- **Regra:** `rules/jsdoc-padrao.md`
|
||||
- **Referência de regras de negócio no código:** `// Regras de negócio: ver ../../wiki/dev/<modulo>/...`
|
||||
- **Referência de regras de negócio no código:** `// Regras de negócio: ver <base_projeto>/../wiki/dev/<modulo-id>/...`
|
||||
|
||||
## 2. Ajuda na Tela (UI - `.ajuda.md`)
|
||||
Arquivos Markdown co-localizados nos componentes de tela e modais.
|
||||
- **Padrão:** `modalX.vue` $\rightarrow$ `modalX.ajuda.md`
|
||||
- **Skill / Workflow:** `skills/adicionar-ajuda/SKILL.md`
|
||||
|
||||
## 3. Wiki do Usuário (`../../wiki/<modulo>/`)
|
||||
## 3. Wiki do Usuário (`<base_projeto>/../wiki/<modulo-id>/`)
|
||||
Aplicação VitePress voltada ao **acesso dos usuários e clientes**. Contém manuais operacionais, tutoriais e conceitos funcionais.
|
||||
- **Estrutura:** `../../wiki/<modulo>/` (ex: `../../wiki/e-licencie.sigma/`)
|
||||
- **Estrutura:** `<base_projeto>/../wiki/<modulo-id>/` (ex: `<base_projeto>/../wiki/e-licencie.sigma/`)
|
||||
- **Skill:** `skills/documentar-dominio-modulo/SKILL.md`
|
||||
|
||||
## 4. Wiki de Desenvolvimento (`../../wiki/dev/<modulo>/`)
|
||||
## 4. Wiki de Desenvolvimento (`<base_projeto>/../wiki/dev/<modulo-id>/`)
|
||||
Aplicação VitePress com **acesso interno exclusivo pela equipe de desenvolvimento e arquitetura**. Contém arquitetura técnica, modelos de banco, regras de negócio detalhadas (`{modulo}.regras-negocio.md`), fluxos de filas, CRONs e ADRs.
|
||||
- **Estrutura:** `../../wiki/dev/<modulo>/` (ex: `../../wiki/dev/e-licencie.sigma/`)
|
||||
- **Regras de Negócio:** `../../wiki/dev/<modulo>/` (ver `rules/regras-negocio-md.md`)
|
||||
- **ADRs Técnicos:** `../../wiki/dev/<modulo>/adrs/` (ver `skills/documentar-decisao-tecnica/SKILL.md`)
|
||||
- **Estrutura:** `<base_projeto>/../wiki/dev/<modulo-id>/` (ex: `<base_projeto>/../wiki/dev/e-licencie.sigma/`)
|
||||
- **Regras de Negócio:** `<base_projeto>/../wiki/dev/<modulo-id>/` (ver `rules/regras-negocio-md.md`)
|
||||
- **ADRs Técnicos:** `<base_projeto>/../wiki/dev/<modulo-id>/adrs/` (ver `skills/documentar-decisao-tecnica/SKILL.md`)
|
||||
|
||||
## 5. Rota de Integração de IA (`/llm.md`)
|
||||
Especificação dinâmica servida pelo backend para consumo por agentes e LLMs.
|
||||
- **Rota padrão:** `GET /llm.md` ou `GET /sigma/llm.md`
|
||||
- **Rota padrão:** `GET /llm.md` ou `GET <modulo-caminho>llm.md`
|
||||
|
||||
## 6. Memória das Ações da IA (`<base_projeto>/memorias-ia/`)
|
||||
Registros de sessões, otimizações executadas e decisões de arquitetura.
|
||||
## 6. Memória das Ações da IA e Identidade (`<base_projeto>/memorias-ia/`)
|
||||
Identidade canônica do projeto pai e registros de sessões, otimizações e decisões da IA.
|
||||
- **Identidade do Módulo:** `<base_projeto>/memorias-ia/modulo.yml` (mandatório com `modulo-id`, `modulo-caminho`, `modulo-descricao`, `modulo-tipo`)
|
||||
- **Regra:** `rules/identidade-modulo.md`
|
||||
- **Diretório:** `<base_projeto>/memorias-ia/` (na raiz do projeto pai)
|
||||
- **Workflow:** `global/workflows/aprimora-ia.md`
|
||||
|
||||
---
|
||||
|
||||
## Templates Padronizados (`DOCUMENTACAO/`)
|
||||
## Templates Padronizados (`DOCUMENTACAO/templates/`)
|
||||
|
||||
- **ADRs:** `DOCUMENTACAO/arquitetura/_template-adr`
|
||||
- **Módulos / Domínio:** `DOCUMENTACAO/modulos/_template-modulo`
|
||||
- **Regras de Negócio:** `DOCUMENTACAO/regras-negocio/_template-regra`
|
||||
- **Contratos de API:** `DOCUMENTACAO/contratos/_template-contrato`
|
||||
- **Fluxos:** `DOCUMENTACAO/fluxos/_template-fluxo`
|
||||
- **Identidade do Módulo (Pilar 6):** [`DOCUMENTACAO/templates/modulo.yml.template`](file:///home/luiz/Arquivos/DEV/Industria/SIGMA2026/.agent/DOCUMENTACAO/templates/modulo.yml.template)
|
||||
- **Domínio do Módulo (Pilares 3 e 4):** [`DOCUMENTACAO/templates/modulo-dominio.md.template`](file:///home/luiz/Arquivos/DEV/Industria/SIGMA2026/.agent/DOCUMENTACAO/templates/modulo-dominio.md.template)
|
||||
- **Regras de Negócio (Pilar 4):** [`DOCUMENTACAO/templates/regra-negocio.md.template`](file:///home/luiz/Arquivos/DEV/Industria/SIGMA2026/.agent/DOCUMENTACAO/templates/regra-negocio.md.template)
|
||||
- **Decisões Arquiteturais - ADRs (Pilar 4):** [`DOCUMENTACAO/templates/adr.md.template`](file:///home/luiz/Arquivos/DEV/Industria/SIGMA2026/.agent/DOCUMENTACAO/templates/adr.md.template)
|
||||
- **Ajuda na Tela / UI (Pilar 2):** [`DOCUMENTACAO/templates/ajuda-tela.md.template`](file:///home/luiz/Arquivos/DEV/Industria/SIGMA2026/.agent/DOCUMENTACAO/templates/ajuda-tela.md.template)
|
||||
- **Contratos de API (Pilar 5):** [`DOCUMENTACAO/templates/contrato-api.md.template`](file:///home/luiz/Arquivos/DEV/Industria/SIGMA2026/.agent/DOCUMENTACAO/templates/contrato-api.md.template)
|
||||
- **Fluxos de Usuário (Pilar 3):** [`DOCUMENTACAO/templates/fluxo-usuario.md.template`](file:///home/luiz/Arquivos/DEV/Industria/SIGMA2026/.agent/DOCUMENTACAO/templates/fluxo-usuario.md.template)
|
||||
|
|
|
|||
|
|
@ -30,27 +30,32 @@ No ecossistema Azteca, a documentação precede o código. Nenhum artefato (regr
|
|||
| :--- | :--- | :--- | :--- | :--- |
|
||||
| **1. Código-Fonte** | `.ts`, `.vue`, `.js` | JSDoc + comentários inline | Desenvolvedores / IA | Comentários claros e coerentes quanto à aplicação prática e contexto de negócio. |
|
||||
| **2. Ajuda na Tela (UI)** | `*-front/.../{componente}.ajuda.md` | Markdown co-localizado | Usuários da UI | Para `modalX.vue`, o arquivo **DEVE** ser `modalX.ajuda.md`. Explica objetivo, botões, campos e instruções de uso. |
|
||||
| **3. Wiki do Usuário** | `../../wiki/<modulo>/` | Markdown (VitePress) | Usuários / Clientes | Aplicação VitePress voltada ao acesso dos usuários. Manuais operacionais, tutoriais de uso, conceitos de negócio e fluxos da aplicação. |
|
||||
| **4. Wiki de Desenvolvimento** | `../../wiki/dev/<modulo>/` | Markdown (VitePress) | Desenvolvedores / Arquitetos | Aplicação VitePress com acesso interno exclusivo da equipe de desenvolvimento. Arquitetura técnica, modelos de banco, regras de negócio (`{modulo}.regras-negocio.md`), filas BullMQ, CRONs e ADRs. |
|
||||
| **3. Wiki do Usuário** | `<base_projeto>/../wiki/<modulo-id>/` | Markdown (VitePress) | Usuários / Clientes | Aplicação VitePress voltada ao acesso dos usuários. Manuais operacionais, tutoriais de uso, conceitos de negócio e fluxos da aplicação. |
|
||||
| **4. Wiki de Desenvolvimento** | `<base_projeto>/../wiki/dev/<modulo-id>/` | Markdown (VitePress) | Desenvolvedores / Arquitetos | Aplicação VitePress com acesso interno exclusivo da equipe de desenvolvimento. Arquitetura técnica, modelos de banco, regras de negócio (`{modulo}.regras-negocio.md`), filas BullMQ, CRONs e ADRs. |
|
||||
| **5. Integração de IA** | Rota Backend `/llm.md` | Markdown dinâmico | Agentes de IA / LLMs | Catálogo vivo de schemas Zod, enums canônicos e contratos de API para consumo por LLMs. |
|
||||
| **6. Memória das Ações da IA** | `<base_projeto>/memorias-ia/` | Markdown com frontmatter | Agentes de IA / Auditoria | Registros de sessões, otimizações executadas, histórico de decisões arquiteturais. |
|
||||
| **6. Memória das Ações da IA e Identidade** | `<base_projeto>/memorias-ia/` | YAML / Markdown | Agentes de IA / Auditoria | Arquivo mandatório `modulo.yml` (`modulo-id`, `modulo-caminho`, `modulo-descricao`, `modulo-tipo`), registros de sessões e decisões arquiteturais. |
|
||||
|
||||
> ℹ️ **Arquitetura VitePress (`../../wiki`)**:
|
||||
> - `../../wiki/` é uma aplicação **VitePress**.
|
||||
> - `../../wiki/<modulo>/` representa a documentação de **acesso dos usuários e operadores**.
|
||||
> - `../../wiki/dev/<modulo>/` representa a documentação de **acesso interno pela equipe de desenvolvimento e arquitetura**.
|
||||
> ℹ️ **Arquitetura VitePress (`<base_projeto>/../wiki`) e Identidade do Projeto**:
|
||||
> - `<base_projeto>/../wiki/` é uma aplicação **VitePress**.
|
||||
> - `<base_projeto>/../wiki/<modulo-id>/` representa a documentação de **acesso dos usuários e operadores** (onde `<modulo-id>` provém de `memorias-ia/modulo.yml`).
|
||||
> - `<base_projeto>/../wiki/dev/<modulo-id>/` representa a documentação de **acesso interno pela equipe de desenvolvimento e arquitetura**.
|
||||
> - O arquivo `<base_projeto>/memorias-ia/modulo.yml` é **obrigatório em todos os projetos** e define `modulo-id`, `modulo-caminho`, `modulo-descricao` e `modulo-tipo`.
|
||||
|
||||
---
|
||||
|
||||
## Hub Central de Templates (`DOCUMENTACAO/`)
|
||||
## Hub Central de Templates (`DOCUMENTACAO/templates/`)
|
||||
|
||||
| Categoria | Diretório | O que documenta | Template |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **Arquitetura (ADRs)** | `DOCUMENTACAO/arquitetura/` ou `../../wiki/dev/<modulo>/adrs/` | Decisões técnicas e arquiteturais | `_template-adr` |
|
||||
| **Módulos / Domínio** | `DOCUMENTACAO/modulos/` ou `../../wiki/dev/<modulo>/` | Domínio, glossário e entidades | `_template-modulo` |
|
||||
| **Regras de Negócio** | `DOCUMENTACAO/regras-negocio/` | Regras globais ou extraídas do código | `_template-regra` |
|
||||
| **Contratos de API** | `DOCUMENTACAO/contratos/` | Contratos de rotas e endpoints | `_template-contrato` |
|
||||
| **Fluxos de Usuário** | `DOCUMENTACAO/fluxos/` | Jornadas do usuário e telas | `_template-fluxo` |
|
||||
Todos os modelos canônicos para instanciar a documentação nos projetos residem em `DOCUMENTACAO/templates/`:
|
||||
|
||||
| Pilar / Categoria | Destino Canônico no Projeto | Template Canônico |
|
||||
| :--- | :--- | :--- |
|
||||
| **Identidade do Módulo (Pilar 6)** | `<base_projeto>/memorias-ia/modulo.yml` | [`modulo.yml.template`](file:///home/luiz/Arquivos/DEV/Industria/SIGMA2026/.agent/DOCUMENTACAO/templates/modulo.yml.template) |
|
||||
| **Domínio do Módulo (Pilar 3 e 4)** | `<base_projeto>/../wiki/<modulo-id>/index.md` | [`modulo-dominio.md.template`](file:///home/luiz/Arquivos/DEV/Industria/SIGMA2026/.agent/DOCUMENTACAO/templates/modulo-dominio.md.template) |
|
||||
| **Regras de Negócio (Pilar 4)** | `<base_projeto>/../wiki/dev/<modulo-id>/<servico>.regras-negocio.md` | [`regra-negocio.md.template`](file:///home/luiz/Arquivos/DEV/Industria/SIGMA2026/.agent/DOCUMENTACAO/templates/regra-negocio.md.template) |
|
||||
| **Decisões Arquiteturais - ADR (Pilar 4)** | `<base_projeto>/../wiki/dev/<modulo-id>/adrs/` | [`adr.md.template`](file:///home/luiz/Arquivos/DEV/Industria/SIGMA2026/.agent/DOCUMENTACAO/templates/adr.md.template) |
|
||||
| **Ajuda na Tela / UI (Pilar 2)** | `*-front/src/.../{componente}.ajuda.md` | [`ajuda-tela.md.template`](file:///home/luiz/Arquivos/DEV/Industria/SIGMA2026/.agent/DOCUMENTACAO/templates/ajuda-tela.md.template) |
|
||||
| **Contratos de API (Pilar 5 e 4)** | Rota `/llm.md` ou `<base_projeto>/../wiki/dev/<modulo-id>/contratos/` | [`contrato-api.md.template`](file:///home/luiz/Arquivos/DEV/Industria/SIGMA2026/.agent/DOCUMENTACAO/templates/contrato-api.md.template) |
|
||||
| **Fluxos e Telas (Pilar 3 e 4)** | `<base_projeto>/../wiki/<modulo-id>/fluxos/` | [`fluxo-usuario.md.template`](file:///home/luiz/Arquivos/DEV/Industria/SIGMA2026/.agent/DOCUMENTACAO/templates/fluxo-usuario.md.template) |
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -1,49 +0,0 @@
|
|||
---
|
||||
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>
|
||||
- [...]
|
||||
|
|
@ -1,70 +0,0 @@
|
|||
---
|
||||
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>
|
||||
- [...]
|
||||
|
|
@ -1,48 +0,0 @@
|
|||
---
|
||||
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>
|
||||
- [...]
|
||||
|
|
@ -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>
|
||||
- [...]
|
||||
|
|
@ -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?>
|
||||
- [...]
|
||||
65
DOCUMENTACAO/templates/adr.md.template
Normal file
65
DOCUMENTACAO/templates/adr.md.template
Normal file
|
|
@ -0,0 +1,65 @@
|
|||
---
|
||||
type: template
|
||||
name: adr
|
||||
description: Template canônico para Architecture Decision Records (ADRs)
|
||||
updatedAt: "2026-09-02"
|
||||
---
|
||||
|
||||
<!--
|
||||
DESTINO CANÔNICO NO PROJETO:
|
||||
- Wiki de Desenvolvimento (Pilar 4): ../../wiki/dev/<modulo-id>/adrs/{numero}-{titulo-kebab-case}.md
|
||||
|
||||
EXEMPLO:
|
||||
../../wiki/dev/e-licencie.sigma/adrs/001-adopcao-bullmq-processamento-noturno.md
|
||||
-->
|
||||
|
||||
# ADR [NUMERO]: [TÍTULO DA DECISÃO ARQUITETURAL]
|
||||
|
||||
- **Status:** Proposta | Aceita | Rejeitada | Descontinuada | Substituída por ADR-XXX
|
||||
- **Data:** `<AAAA-MM-DD>`
|
||||
- **Decisores / Autores:** `<Nomes dos arquitetos / devs>`
|
||||
- **Módulo(s) Impactado(s):** `<modulo-id>`
|
||||
|
||||
---
|
||||
|
||||
## 1. Contexto e Problemática
|
||||
<Qual é o cenário atual? Qual limitação, gargalo, requisito ou dívida técnica força a necessidade de uma decisão?>
|
||||
|
||||
---
|
||||
|
||||
## 2. Decisão Técnica
|
||||
<O que decidimos fazer de forma clara e objetiva? Qual biblioteca, arquitetura, padrão de projeto ou contrato será implementado?>
|
||||
|
||||
---
|
||||
|
||||
## 3. Alternativas Consideradas
|
||||
|
||||
| Alternativa | Prós | Contras | Motivo do Descarte |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **Opção A** | [...] | [...] | [...] |
|
||||
| **Opção B** | [...] | [...] | [...] |
|
||||
|
||||
---
|
||||
|
||||
## 4. Consequências e Trade-offs
|
||||
|
||||
### Positivas ✅
|
||||
- [...]
|
||||
|
||||
### Negativas / Riscos Mitigados ⚠️
|
||||
- [...]
|
||||
|
||||
### Neutras ℹ️
|
||||
- [...]
|
||||
|
||||
---
|
||||
|
||||
## 5. Impacto na Estrutura e Monorepo
|
||||
- **Pacotes Afetados:** `*-back`, `*-front`, `*-comuns`, `*-migracao`
|
||||
- **Contratos de API / Schemas Zod:** [Sim/Não - Detalhar se houver breaking change]
|
||||
- **Migrações de Banco Necessárias:** [Sim/Não]
|
||||
|
||||
---
|
||||
|
||||
## 6. Referências e Literatura Técnica
|
||||
- [Padrão / RFC / Documentação oficial]: `<link ou citação>`
|
||||
51
DOCUMENTACAO/templates/ajuda-tela.md.template
Normal file
51
DOCUMENTACAO/templates/ajuda-tela.md.template
Normal file
|
|
@ -0,0 +1,51 @@
|
|||
---
|
||||
type: template
|
||||
name: ajuda-tela
|
||||
description: Template canônico para ajuda contextual na interface do usuário (Pilar 2 DDD)
|
||||
updatedAt: "2026-09-02"
|
||||
---
|
||||
|
||||
<!--
|
||||
DESTINO CANÔNICO NO PROJETO:
|
||||
- Co-localizado com o componente Vue correspondente no frontend:
|
||||
Ex: Para 'ModalParametros.vue' -> salvar como 'ModalParametros.ajuda.md' na mesma pasta.
|
||||
-->
|
||||
|
||||
# Ajuda: [Nome da Tela / Modal / Formulário]
|
||||
|
||||
## Objetivo
|
||||
<Explicar em linguagem simples e direta para o usuário final qual é o propósito desta tela e o que ela permite realizar.>
|
||||
|
||||
---
|
||||
|
||||
## Como Utilizar (Passo a Passo)
|
||||
1. **Passo 1:** <Ação do usuário>
|
||||
2. **Passo 2:** <Ação do usuário>
|
||||
3. **Passo 3:** <Ação de conclusão / salvar>
|
||||
|
||||
---
|
||||
|
||||
## Campos e Informações
|
||||
|
||||
| Campo / Opção | Obrigatório? | O que preencher |
|
||||
| :--- | :--- | :--- |
|
||||
| **[Nome do Campo 1]** | Sim | <Explicação do valor esperado> |
|
||||
| **[Nome do Campo 2]** | Não | <Explicação do valor esperado> |
|
||||
|
||||
---
|
||||
|
||||
## Botões e Ações Disponíveis
|
||||
|
||||
- **[Botão Salvar / Confirmar]:** <O que acontece ao clicar>
|
||||
- **[Botão Cancelar / Fechar]:** <O que acontece ao clicar>
|
||||
- **[Botões de Ação Específica]:** <O que acontece ao clicar>
|
||||
|
||||
---
|
||||
|
||||
## Dicas e Resolução de Dúvidas Frequentes
|
||||
|
||||
> [!TIP]
|
||||
> **Dica Útil:** <Dica prática do dia a dia da operação.>
|
||||
|
||||
> [!IMPORTANT]
|
||||
> **Atenção:** <Ponto de atenção ou regra de bloqueio importante.>
|
||||
72
DOCUMENTACAO/templates/contrato-api.md.template
Normal file
72
DOCUMENTACAO/templates/contrato-api.md.template
Normal file
|
|
@ -0,0 +1,72 @@
|
|||
---
|
||||
type: template
|
||||
name: contrato-api
|
||||
description: Template canônico para especificação de contratos de API e schemas Zod
|
||||
updatedAt: "2026-09-02"
|
||||
---
|
||||
|
||||
<!--
|
||||
DESTINO CANÔNICO NO PROJETO:
|
||||
- Rota Dinâmica de IA (Pilar 5): servido dinamicamente pelo backend em /llm.md ou <modulo-caminho>llm.md
|
||||
- Wiki de Desenvolvimento (Pilar 4): ../../wiki/dev/<modulo-id>/contratos/{servico}.contrato.md
|
||||
-->
|
||||
|
||||
# Contrato de API — [Nome do Serviço / Endpoint]
|
||||
|
||||
- **Módulo:** `<modulo-id>`
|
||||
- **Base URL:** `<modulo-caminho>api/v1/`
|
||||
- **Autenticação:** Bearer Token JWT (Header `Authorization: Bearer <token>`)
|
||||
|
||||
---
|
||||
|
||||
## Tabela de Endpoints
|
||||
|
||||
| Método | Endpoint | Descrição | Permissão Requerida |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `GET` | `/recurso` | Listar recursos com paginação | Leitura |
|
||||
| `POST` | `/recurso` | Criar novo registro | Escrita |
|
||||
| `GET` | `/recurso/:id` | Obter detalhes por ID | Leitura |
|
||||
| `PUT` | `/recurso/:id` | Atualizar registro completo | Escrita |
|
||||
| `DELETE` | `/recurso/:id` | Excluir logicamente o registro | Admin |
|
||||
|
||||
---
|
||||
|
||||
## Detalhamento: `POST /recurso`
|
||||
|
||||
### Request Body (Schema Zod: `zRecursoCriar`)
|
||||
```typescript
|
||||
import { z } from "zod";
|
||||
|
||||
export const zRecursoCriar = z.object({
|
||||
nome: z.string().min(3).max(100),
|
||||
tipo: z.enum(["TIPO_A", "TIPO_B"]),
|
||||
ativo: z.boolean().default(true),
|
||||
});
|
||||
|
||||
export type RecursoCriar = z.infer<typeof zRecursoCriar>;
|
||||
```
|
||||
|
||||
### Exemplo de Payload (JSON)
|
||||
```json
|
||||
{
|
||||
"nome": "Monitoramento Trimestral",
|
||||
"tipo": "TIPO_A",
|
||||
"ativo": true
|
||||
}
|
||||
```
|
||||
|
||||
### Resposta de Sucesso (`201 Created`)
|
||||
```json
|
||||
{
|
||||
"id": "uuid-v4-gerado",
|
||||
"nome": "Monitoramento Trimestral",
|
||||
"tipo": "TIPO_A",
|
||||
"ativo": true,
|
||||
"criadoEm": "2026-09-02T10:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### Respostas de Erro
|
||||
- `400 Bad Request`: Payload não satisfaz o schema Zod (retorna array `erros: [{ campo, mensagem }]`).
|
||||
- `401 Unauthorized`: Token ausente ou expirado.
|
||||
- `403 Forbidden`: Usuário sem perfil de acesso para esta operação.
|
||||
62
DOCUMENTACAO/templates/fluxo-usuario.md.template
Normal file
62
DOCUMENTACAO/templates/fluxo-usuario.md.template
Normal file
|
|
@ -0,0 +1,62 @@
|
|||
---
|
||||
type: template
|
||||
name: fluxo-usuario
|
||||
description: Template canônico para mapeamento de fluxos operacionais e jornadas do usuário
|
||||
updatedAt: "2026-09-02"
|
||||
---
|
||||
|
||||
<!--
|
||||
DESTINO CANÔNICO NO PROJETO:
|
||||
- Wiki do Usuário (Pilar 3): ../../wiki/<modulo-id>/fluxos/{nome-do-fluxo}.md
|
||||
- Wiki de Desenvolvimento (Pilar 4 - Fluxos Técnicos/Jobs): ../../wiki/dev/<modulo-id>/fluxos/{nome-do-fluxo}.md
|
||||
-->
|
||||
|
||||
# Fluxo de Usuário: [Nome da Jornada / Processo]
|
||||
|
||||
- **Módulo:** `<modulo-id>`
|
||||
- **Atores Envolvidos:** `<Ex: Gestor Ambiental, Técnico de Campo, Consultor>`
|
||||
- **Objetivo Final:** `<O que é alcançado com sucesso ao término deste fluxo>`
|
||||
|
||||
---
|
||||
|
||||
## Pré-condições
|
||||
- [ ] Usuário devidamente autenticado com permissão de acesso ao módulo.
|
||||
- [ ] Entidade pai previamente cadastrada.
|
||||
|
||||
---
|
||||
|
||||
## Jornada Principal (Caminho Feliz)
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
actor U as Usuário
|
||||
participant UI as Interface (Vue)
|
||||
participant API as Backend Fastify/Express
|
||||
participant DB as PostgreSQL
|
||||
|
||||
U->>UI: Acessa formulário de cadastro
|
||||
UI->>U: Exibe campos com validação Zod preventiva
|
||||
U->>UI: Preenche dados e clica em Salvar
|
||||
UI->>API: POST /recurso (payload validado)
|
||||
API->>DB: Persiste registro no banco
|
||||
DB-->>API: Retorna ID gerado
|
||||
API-->>UI: 201 Created com dados criados
|
||||
UI-->>U: Exibe toast de sucesso e redireciona
|
||||
```
|
||||
|
||||
### Passo a Passo Detalhado
|
||||
1. **Acesso à Tela:** O usuário navega até a rota `<modulo-caminho>recurso`.
|
||||
2. **Preenchimento:** Preenche os campos obrigatórios (validação visual imediata).
|
||||
3. **Submissão:** Clica em "Salvar". O botão entra em estado `loading`.
|
||||
4. **Confirmação:** Toast de sucesso exibido e lista atualizada sem recarregar a página.
|
||||
|
||||
---
|
||||
|
||||
## Fluxos Alternativos e Tratamento de Exceções
|
||||
|
||||
### Alternativa 1: Cancelamento
|
||||
- O usuário clica em "Cancelar". Se houver alterações pendentes, um modal de confirmação de descarte é exibido.
|
||||
|
||||
### Exceção 1: Falha de Conexão ou Validação
|
||||
- Se a API retornar erro de validação ou indisponibilidade, a interface exibe banner com mensagem amigável no vocabulário do usuário (sem expor stack traces técnicos).
|
||||
58
DOCUMENTACAO/templates/modulo-dominio.md.template
Normal file
58
DOCUMENTACAO/templates/modulo-dominio.md.template
Normal file
|
|
@ -0,0 +1,58 @@
|
|||
---
|
||||
type: template
|
||||
name: modulo-dominio
|
||||
description: Template canônico para documentação de domínio funcional e técnico de módulos
|
||||
updatedAt: "2026-09-02"
|
||||
---
|
||||
|
||||
<!--
|
||||
DESTINO CANÔNICO NO PROJETO:
|
||||
- Wiki do Usuário (Pilar 3): <base_projeto>/../wiki/<modulo-id>/index.md
|
||||
- Wiki de Desenvolvimento (Pilar 4): <base_projeto>/../wiki/dev/<modulo-id>/index.md
|
||||
|
||||
VARIÁVEIS A PREENCHER:
|
||||
- <modulo-id>: ID obtido em memorias-ia/modulo.yml (ex: e-licencie.sigma)
|
||||
- <NOME DO MÓDULO>: Nome legível do módulo (ex: SIGMA - Monitoramento Ambiental)
|
||||
-->
|
||||
|
||||
# Módulo: <NOME DO MÓDULO>
|
||||
|
||||
## Identidade e Propósito
|
||||
- **ID do Módulo (`modulo-id`):** `<modulo-id>`
|
||||
- **Rota Base (`modulo-caminho`):** `<modulo-caminho>`
|
||||
- **Propósito:** <Descrever o problema operacional central que este módulo resolve>
|
||||
|
||||
---
|
||||
|
||||
## Glossário e Conceitos do Domínio
|
||||
|
||||
| Termo | Definição no Domínio | Contexto de Aplicação |
|
||||
| :--- | :--- | :--- |
|
||||
| `<Termo 1>` | `<Definição clara>` | `<Onde aparece na operação>` |
|
||||
| `<Termo 2>` | `<Definição clara>` | `<Onde aparece na operação>` |
|
||||
|
||||
---
|
||||
|
||||
## Entidades e Dados Centrais
|
||||
|
||||
- **Entidade A**: <Descrição da entidade, papel no negócio e atributos principais>
|
||||
- **Entidade B**: <Descrição da entidade, papel no negócio e atributos principais>
|
||||
|
||||
---
|
||||
|
||||
## Legislação e Normas Aplicáveis
|
||||
<Listar normas técnicas (CONAMA, ABNT), leis ou portarias que balizam as regras deste módulo>
|
||||
- Norma/Lei 1: [...]
|
||||
- Norma/Lei 2: [...]
|
||||
|
||||
---
|
||||
|
||||
## Fluxos Operacionais Principais
|
||||
- **Fluxo 1**: <Descrição resumida do fluxo operacional>
|
||||
- **Fluxo 2**: <Descrição resumida do fluxo operacional>
|
||||
|
||||
---
|
||||
|
||||
## Vocabulário de Interface (Linguagem Ubíqua)
|
||||
<Termos específicos que DEVEM ser usados nos botões, títulos e mensagens da UI para consistência com o usuário>
|
||||
- `<Ação>`: `<Termo recomendado na UI>`
|
||||
15
DOCUMENTACAO/templates/modulo.yml.template
Normal file
15
DOCUMENTACAO/templates/modulo.yml.template
Normal file
|
|
@ -0,0 +1,15 @@
|
|||
# Template canônico: memorias-ia/modulo.yml
|
||||
# Este arquivo é obrigatório na raiz de todos os projetos que utilizam .agent.
|
||||
# Ele define a identidade oficial e as configurações de rota do módulo.
|
||||
|
||||
# Identificador único do módulo (utilizado para pacotes, wikis <base_projeto>/../wiki/<modulo-id>/ e regras de negócio)
|
||||
modulo-id: nome-do-modulo.submodulo
|
||||
|
||||
# Rota/prefixo utilizado na URL e navegação do módulo (com barras inicial e final)
|
||||
modulo-caminho: /modulo/
|
||||
|
||||
# Descrição funcional resumida do propósito e escopo do módulo
|
||||
modulo-descricao: Descrição detalhada do módulo para contextualização operacional e comercial
|
||||
|
||||
# Descrição da arquitetura, stack tecnológica e banco de dados
|
||||
modulo-tipo: aplicação web com back e front nas tecnologias bun e vue 3 com banco postgres
|
||||
63
DOCUMENTACAO/templates/regra-negocio.md.template
Normal file
63
DOCUMENTACAO/templates/regra-negocio.md.template
Normal file
|
|
@ -0,0 +1,63 @@
|
|||
---
|
||||
type: template
|
||||
name: regra-negocio
|
||||
description: Template canônico para especificação de regras de negócio em linguagem natural
|
||||
updatedAt: "2026-09-02"
|
||||
---
|
||||
|
||||
<!--
|
||||
DESTINO CANÔNICO NO PROJETO:
|
||||
- Wiki de Desenvolvimento (Pilar 4): <base_projeto>/../wiki/dev/<modulo-id>/{nome-servico}.regras-negocio.md
|
||||
ou <base_projeto>/../wiki/dev/<modulo-id>/regras-negocio/{nome-regra}.md
|
||||
|
||||
REFERÊNCIA NO CÓDIGO TYPESCRIPT (primeira linha útil):
|
||||
// Regras de negócio: ver <base_projeto>/../wiki/dev/<modulo-id>/{nome-servico}.regras-negocio.md
|
||||
-->
|
||||
|
||||
# Regras de Negócio — [Nome do Serviço / Funcionalidade]
|
||||
|
||||
- **Módulo:** `<modulo-id>`
|
||||
- **Arquivo TypeScript:** `caminho/relativo/ao/_arquivo.ts`
|
||||
- **Última Atualização:** `<AAAA-MM-DD>`
|
||||
|
||||
---
|
||||
|
||||
## Contexto Operacional
|
||||
<Por que esta regra existe? Qual decisão ou cálculo ela formaliza e qual problema operacional evita?>
|
||||
|
||||
---
|
||||
|
||||
## Critérios de Entrada / Acionamento
|
||||
<Quais condições e dados ativam a avaliação desta regra?>
|
||||
- [ ] Critério 1: [...]
|
||||
- [ ] Critério 2: [...]
|
||||
|
||||
---
|
||||
|
||||
## Regras de Processamento (Ordem Determinística)
|
||||
As regras devem ser avaliadas na ordem numérica estrita abaixo:
|
||||
|
||||
1. **Regra 1 — [Nome]:** <Descrição da validação ou transformação.>
|
||||
2. **Regra 2 — [Nome]:** <Descrição da validação ou transformação.>
|
||||
3. **Regra 3 — [Nome]:** <Descrição da validação ou transformação.>
|
||||
|
||||
---
|
||||
|
||||
## Casos de Revisão Manual (Exceções)
|
||||
<Quando o sistema não deve decidir automaticamente e deve solicitar intervenção de um operador humano?>
|
||||
- **Cenário A:** [...]
|
||||
- **Cenário B:** [...]
|
||||
|
||||
---
|
||||
|
||||
## Estratégia de Persistência / Saída
|
||||
<Qual é o resultado final gerado? Campos persistidos no banco, status atualizados, eventos disparados.>
|
||||
- **Status Resultante:** [...]
|
||||
- **Campos Atualizados:** [...]
|
||||
|
||||
---
|
||||
|
||||
## Dependências Externas e Filas
|
||||
<Quais filas BullMQ, endpoints externos, rotas ou tabelas de banco são afetadas por esta regra?>
|
||||
- **Filas:** [...]
|
||||
- **Tabelas / Schemas:** [...]
|
||||
Loading…
Add table
Add a link
Reference in a new issue