refatoração dos agents
This commit is contained in:
parent
97acfb07df
commit
1177e31e56
104 changed files with 1068 additions and 3995 deletions
118
agents/front/workflows/adicionar-ajuda
Normal file
118
agents/front/workflows/adicionar-ajuda
Normal file
|
|
@ -0,0 +1,118 @@
|
|||
---
|
||||
type: workflow
|
||||
name: adicionar-ajuda
|
||||
description: Adicionar ou atualizar botão de ajuda e documentação em telas (Frontend)
|
||||
scope: local
|
||||
updatedAt: "2026-06-01"
|
||||
---
|
||||
|
||||
# Workflow: Adicionar Ajuda em Telas
|
||||
|
||||
Este workflow automatiza a inserção do botão de ajuda e a criação do arquivo de documentação correspondente sempre que uma tela é criada ou modificada de forma significativa.
|
||||
|
||||
O objetivo da ajuda é **auxiliar o usuário final a compreender e utilizar corretamente a aplicação**, explicando o funcionamento da tela de forma clara e objetiva.
|
||||
|
||||
## Pré-requisitos
|
||||
|
||||
- O arquivo alvo deve ser um componente de interface (`.tsx` para React ou `.vue` para Vue).
|
||||
- O projeto deve possuir um componente de ajuda (ex: `BotaoAjuda`, `HelpButton` ou equivalente) disponível para uso na interface.
|
||||
- Caso não exista, criar um componente reutilizável que exiba o conteúdo do `.ajuda.md` em modal ou drawer.
|
||||
|
||||
## Passos
|
||||
|
||||
### 1. Identificar o Componente Alvo
|
||||
|
||||
Determine qual arquivo representa a tela principal ou modal que está sendo criado ou editado.
|
||||
|
||||
- React → `.tsx`
|
||||
- Vue → `.vue`
|
||||
|
||||
### 2. Verificar Existência de Ajuda
|
||||
|
||||
Procure por um arquivo de ajuda com o mesmo nome do componente e sufixo indicativo de ajuda (ex.: `.ajuda.md`) localizado na mesma pasta.
|
||||
|
||||
Exemplo:
|
||||
|
||||
```
|
||||
|
||||
TelaCadastroUsuario.tsx
|
||||
TelaCadastroUsuario.ajuda.md
|
||||
|
||||
```
|
||||
|
||||
ou
|
||||
|
||||
```
|
||||
|
||||
TelaCadastroUsuario.vue
|
||||
TelaCadastroUsuario.ajuda.md
|
||||
|
||||
````
|
||||
|
||||
### 3. Criar ou Atualizar o Arquivo Markdown
|
||||
|
||||
Se o arquivo `.ajuda.md` não existir, crie-o utilizando o template básico abaixo.
|
||||
|
||||
O conteúdo deve ser escrito **pensando no usuário final**, explicando de forma simples como utilizar a tela.
|
||||
|
||||
A documentação deve incluir, quando aplicável:
|
||||
|
||||
- **Objetivo da tela**
|
||||
- **Descrição dos botões**
|
||||
- **Descrição dos campos de formulário**
|
||||
- **Regras de preenchimento e validações**
|
||||
- **Fluxo esperado de uso**
|
||||
- **Contexto técnico ou legal**, quando relevante para o entendimento da funcionalidade
|
||||
|
||||
Template inicial:
|
||||
|
||||
```markdown
|
||||
# Ajuda: [Nome da Tela]
|
||||
|
||||
## Objetivo da Tela
|
||||
|
||||
Explique de forma simples para que serve esta tela dentro do sistema.
|
||||
|
||||
## Botões
|
||||
|
||||
- **Salvar**: grava as informações preenchidas.
|
||||
- **Cancelar**: descarta as alterações realizadas.
|
||||
- **Excluir**: remove o registro atual do sistema.
|
||||
|
||||
## Campos do Formulário
|
||||
|
||||
- **Nome**: informe o nome completo do responsável.
|
||||
- **Data de Vistoria**: data em que a vistoria foi realizada.
|
||||
- **Observações**: campo livre para registrar informações adicionais.
|
||||
|
||||
## Fluxo de Uso
|
||||
|
||||
1. Preencha os campos obrigatórios.
|
||||
2. Revise as informações inseridas.
|
||||
3. Clique em **Salvar** para registrar os dados no sistema.
|
||||
|
||||
## Informações Técnicas ou Legais (quando aplicável)
|
||||
|
||||
Explique regras técnicas, normas ou exigências legais relacionadas à funcionalidade da tela.
|
||||
````
|
||||
|
||||
### 4. Posicionamento do Botão de Ajuda
|
||||
|
||||
O botão deve ser inserido de forma consistente e não pode interferir na interface da aplicação.
|
||||
|
||||
#### Telas / Páginas
|
||||
|
||||
* O botão deve ficar na **parte inferior esquerda da página**.
|
||||
* Deve respeitar espaçamento suficiente das bordas da interface.
|
||||
* **Não pode sobrepor nenhum componente da tela.**
|
||||
* **Não pode ficar oculto ou sobreposto pela barra de módulos da aplicação.**
|
||||
* Ajustar `margin`, `padding` ou `z-index` quando necessário para garantir visibilidade adequada.
|
||||
|
||||
#### Modais e Diálogos
|
||||
|
||||
* O botão deve ficar na **parte inferior esquerda do modal**.
|
||||
* Preferencialmente no rodapé do modal ou em um container equivalente.
|
||||
* **Não pode sobrepor botões ou ações do modal.**
|
||||
* Garantir espaçamento adequado para não interferir na usabilidade.
|
||||
|
||||
|
||||
189
agents/front/workflows/criar-fluxograma
Normal file
189
agents/front/workflows/criar-fluxograma
Normal file
|
|
@ -0,0 +1,189 @@
|
|||
---
|
||||
type: workflow
|
||||
name: criar-fluxograma
|
||||
description: Criar ou atualizar uma página de fluxograma interativo em qualquer sistema
|
||||
scope: local
|
||||
updatedAt: "2026-06-01"
|
||||
---
|
||||
|
||||
# Workflow: Criar Fluxograma de Decisões
|
||||
|
||||
Este workflow cria uma **página interativa de fluxograma** em qualquer aplicação web, usando Mermaid.js instalado como dependência do projeto.
|
||||
|
||||
## Princípio
|
||||
|
||||
O fluxograma é um artefato vivo. Ele documenta visualmente:
|
||||
- Os **pontos de entrada** do processo
|
||||
- As **decisões** tomadas em cada etapa
|
||||
- Os **registros gerados** (banco, fila, log, e-mail, etc.)
|
||||
- As **proteções e regras** que governam os estados
|
||||
|
||||
Deve ser mantido sempre sincronizado com o código real.
|
||||
|
||||
---
|
||||
|
||||
## Passos
|
||||
|
||||
### 1. Levantar o processo a ser documentado
|
||||
|
||||
Ler os arquivos de código relevantes para entender:
|
||||
|
||||
- Quais são os **pontos de entrada**? (funções de API, eventos, webhooks, ações do usuário)
|
||||
- Quais são as **decisões**? (condições `if/else`, guards, validações)
|
||||
- Quais são os **efeitos colaterais**? (gravações em banco, envios de e-mail, filas, logs)
|
||||
- Quais são os **estados possíveis**? (status, notas, flags, etapas)
|
||||
- Existe **hierarquia ou prioridade** entre estados?
|
||||
|
||||
### 2. Organizar os diagramas
|
||||
|
||||
Dividir o processo em **um diagrama por ponto de entrada**.
|
||||
|
||||
Cada diagrama deve mostrar:
|
||||
- Todos os caminhos possíveis, inclusive early returns e casos de erro
|
||||
- Registros gerados com ícone indicativo (ex: 🗄️ banco, 📧 e-mail, 🚫 bloqueio)
|
||||
- Decisões claramente separadas por ramificações
|
||||
|
||||
Definir a orientação de cada diagrama:
|
||||
- `flowchart TD` → vertical (melhor para fluxos sequenciais com poucas ramificações)
|
||||
- `flowchart LR` → horizontal (melhor para pipelines e fluxos com muitas etapas em linha)
|
||||
|
||||
### 3. Instalar o Mermaid
|
||||
|
||||
Instalar como dependência do projeto antes de qualquer implementação:
|
||||
|
||||
```bash
|
||||
# npm
|
||||
npm install mermaid
|
||||
|
||||
# pnpm
|
||||
pnpm add mermaid
|
||||
```
|
||||
|
||||
### 4. Criar a página com Mermaid
|
||||
|
||||
Adaptar à plataforma do projeto (Vue, React, HTML puro, etc.), mas garantir:
|
||||
|
||||
#### Importação
|
||||
|
||||
```js
|
||||
import mermaid from 'mermaid';
|
||||
```
|
||||
|
||||
#### Inicialização com tema institucional
|
||||
|
||||
Adaptar as cores para a identidade visual do projeto:
|
||||
|
||||
```js
|
||||
mermaid.initialize({
|
||||
startOnLoad: false,
|
||||
theme: 'base',
|
||||
themeVariables: {
|
||||
primaryColor: '#4F46E5', // cor primária do projeto
|
||||
primaryTextColor: '#1F2933',
|
||||
primaryBorderColor: '#3730A3', // variação mais escura da primária
|
||||
lineColor: '#6B7280',
|
||||
secondaryColor: '#E0E7FF', // variação clara da primária
|
||||
tertiaryColor: '#F3F4F6',
|
||||
fontFamily: "'Inter', 'Segoe UI', sans-serif",
|
||||
fontSize: '13px',
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
#### Renderização de cada diagrama
|
||||
|
||||
```js
|
||||
// Para cada diagrama:
|
||||
const { svg } = await mermaid.render(`id-unico-${idx}`, codigoMermaid);
|
||||
container.innerHTML = svg;
|
||||
|
||||
// Tornar o SVG responsivo:
|
||||
const svgEl = container.querySelector('svg');
|
||||
if (svgEl) {
|
||||
svgEl.style.width = '100%';
|
||||
svgEl.style.height = 'auto';
|
||||
svgEl.removeAttribute('width');
|
||||
}
|
||||
```
|
||||
|
||||
### 5. Registrar a rota e adicionar acesso
|
||||
|
||||
- Registrar a rota `/fluxograma` (ou equivalente) no sistema de rotas do projeto
|
||||
- Adicionar botão de navegação na tela de administração ou dashboard
|
||||
|
||||
---
|
||||
|
||||
## Padrão de sintaxe Mermaid
|
||||
|
||||
### Tipos de nó por semântica
|
||||
|
||||
| Situação | Sintaxe | Exemplo |
|
||||
|---|---|---|
|
||||
| Início / Fim | `A(["Texto"])` | `A(["Início"])` |
|
||||
| Decisão | `B{"Condição?"}` | `B{"Nota é ativa?"}` |
|
||||
| Ação / Processo | `C["Texto"]` | `C["Consulta banco"]` |
|
||||
| Registro em banco | `D[("🗄️ Grava dado")]` | `D[("🗄️ Grava 203_neutro")]` |
|
||||
| E-mail / notificação | `E["📧 Envia e-mail"]` | `E["📧 Agenda na fila"]` |
|
||||
| Bloqueio / guard | `F["🚫 Retorna sem ação"]` | `F["🚫 Nota ativa, ignora"]` |
|
||||
| Proteção / regra | `G["🛡️ Regra aplicada"]` | `G["🛡️ SQL CASE protege"]` |
|
||||
|
||||
### Regras para evitar erros de parsing
|
||||
|
||||
```
|
||||
✅ Nós com parênteses → usar aspas:
|
||||
A["Texto (com parênteses)"]
|
||||
|
||||
✅ Labels de arestas com texto especial → usar aspas:
|
||||
A -- "Label aqui" --> B
|
||||
|
||||
✅ Emojis → sempre dentro de aspas:
|
||||
A["🗄️ Grava registro"]
|
||||
|
||||
❌ Não usar < > dentro de labels sem aspas
|
||||
❌ Não usar & diretamente — usar texto alternativo
|
||||
```
|
||||
|
||||
### Cores de destaque para nós
|
||||
|
||||
```
|
||||
style NomeNo fill:#22C55E,color:#fff → verde sucesso
|
||||
style NomeNo fill:#DC2626,color:#fff → vermelho erro
|
||||
style NomeNo fill:#F59E0B,color:#000 → amarelo alerta
|
||||
style NomeNo fill:#4F46E5,color:#fff → cor institucional (adaptar ao projeto)
|
||||
style NomeNo fill:#6B7280,color:#fff → cinza neutro
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Validação antes de finalizar
|
||||
|
||||
- [ ] Cada ponto de entrada tem seu próprio diagrama?
|
||||
- [ ] Todos os registros gerados estão mapeados?
|
||||
- [ ] Os caminhos de bloqueio e early return estão visíveis?
|
||||
- [ ] A hierarquia de estados (se existir) está documentada?
|
||||
- [ ] A data de atualização está registrada na página?
|
||||
- [ ] A sintaxe Mermaid está correta (sem erros de parsing)?
|
||||
- [ ] O SVG está responsivo (largura 100%, sem width fixo)?
|
||||
|
||||
---
|
||||
|
||||
## Manutenção
|
||||
|
||||
Sempre que o processo mudar:
|
||||
|
||||
1. Identificar qual diagrama é afetado
|
||||
2. Atualizar o código Mermaid correspondente
|
||||
3. Atualizar a data de atualização na página
|
||||
4. Se houver novo estado ou proteção, documentar na legenda
|
||||
|
||||
---
|
||||
|
||||
## Referência de implementação
|
||||
|
||||
Se o projeto já possuir um fluxograma implementado, usar como referência.
|
||||
Caso contrário, seguir os passos acima para criar a primeira implementação.
|
||||
|
||||
## Referências
|
||||
|
||||
- Workflow: `global/workflows/otimizar-codigos`
|
||||
- Skill: `global/skills/documentar-decisao-tecnica/SKILL` (para decisões que geram fluxogramas)
|
||||
Loading…
Add table
Add a link
Reference in a new issue