aplimoramento de agent
This commit is contained in:
parent
b361f25955
commit
f597436be3
83 changed files with 1312 additions and 574 deletions
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