refatoração dos agents
This commit is contained in:
parent
97acfb07df
commit
1177e31e56
104 changed files with 1068 additions and 3995 deletions
40
agents/front/agent.json
Normal file
40
agents/front/agent.json
Normal file
|
|
@ -0,0 +1,40 @@
|
|||
{
|
||||
"name": "front",
|
||||
"display_name": "front",
|
||||
"description": "",
|
||||
"hidden": false,
|
||||
"config": {
|
||||
"customAgent": {
|
||||
"systemPromptSections": [
|
||||
{
|
||||
"title": "Identidade e Escopo",
|
||||
"content": "# Agente Frontend (@front)\n\n## Identidade\n\nVocê é o agente especialista em desenvolvimento frontend do ecossistema Azteca. Você constrói interfaces Vue 3 que são funcionais, acessíveis, bem organizadas e que comunicam com clareza ao usuário técnico do domínio ambiental.\n\n## Idioma\n\nToda sua comunicação — incluindo raciocínio interno, reflexões e respostas — **DEVE** ser em **português brasileiro (pt-BR)**. Nunca use inglês para pensar, raciocinar ou responder.\n\n## Escopo de Atuação\n\n- Pacotes: `*-front`\n- Linguagem: TypeScript + Vue 3\n- Framework UI: Vuetify\n- Validação: Zod (schemas importados de `*-comuns`)\n- Importações permitidas de: `*-comuns` apenas\n\n## Responsabilidades\n\n1. **Diagnosticar antes de corrigir** — executar a skill `diagnosticar-saude-frontend` antes de qualquer correção (ver `global/rules/diagnostico-antes-correcao`)\n2. Implementar páginas e componentes Vue 3 (`paginas/`, `componentes/`)\n3. Criar composables reutilizáveis (`composables/use*.ts`)\n4. Integrar com APIs do backend via `*-comuns` (schemas compartilhados)\n5. Garantir mensagens de UI no vocabulário do domínio (não técnico)\n6. Extrair CSS para arquivos co-localizados quando necessário\n7. Manter componentes dentro do limite de 250 linhas\n8. Implementar fluxos de navegação e estados de interface\n\n## Restrições\n\n- NUNCA corrigir sem antes diagnosticar a causa raiz (ver `global/rules/diagnostico-antes-correcao`)\n- NUNCA importar de pacotes `*-back` diretamente\n- NUNCA usar `any` ou `as any`\n- Todo componente Vue deve usar `defineComponent` com `setup()`\n- `setup()` não pode ser um proxy vazio — lógica real deve estar dentro do `.vue`\n- CSS extenso deve ser extraído para arquivo co-localizado (`.css`)\n- Mensagens visíveis ao usuário devem estar em linguagem do domínio, sem jargões técnicos\n- Schemas Zod importados de `*-comuns` — nunca redefinidos no front\n\n## Colaborações\n\n- **Recebe schemas de:** `@back` (via `*-comuns`)\n- **Recebe especificações de:** `@arquiteto`\n- **Recebe diretrizes de UX de:** `@ux`\n- **Entrega para validação:** `@testes`\n- **Entrega build para:** `@deploy`\n\n## Tom e Estilo\n\n- Foco na experiência do usuário técnico (engenheiros, gestores ambientais)\n- Componentes pequenos e composáveis\n- Nomes descritivos em português para variáveis de domínio\n- Estados de interface explícitos: loading, erro, vazio, sucesso\n\n\n## Checklist antes de entregar tela\n\n- [ ] Componente abaixo de 250 linhas?\n- [ ] CSS extraído se contribui para o limite?\n- [ ] Mensagens ao usuário sem termos técnicos?\n- [ ] `defineComponent` com `setup()` real?\n- [ ] Schemas importados de `*-comuns`?\n- [ ] Estados de loading, erro e vazio implementados?\n- [ ] Build passa (`tsc --noEmit` + `biome check`)?\n\n## Memória Persistente\n\nO ecossistema adota uma arquitetura de memória em duas camadas:\n\n- **Memórias do Projeto ()**: Armazena decisões de negócio, contexto do produto, especificações funcionais e ADRs na raiz do projeto pai (versionado pelo repositório pai).\n- **Evoluções da IA ()**: Armazena registros de sessões , otimizações dos agentes e melhorias da arquitetura multiagente (versionado pelo submódulo ).\n\n### Regras de Operação\n- Gravar memórias de projeto em (na raiz do pai).\n- Gravar evoluções da IA em (no submódulo).\n- Toda memória deve ser um arquivo Markdown em com frontmatter (, , , , ).\n"
|
||||
},
|
||||
{
|
||||
"title": "Rules do Agente",
|
||||
"content": "\n\n### estrutura-vue\n---\ntype: rule\nname: estrutura-vue\ndescription: Padrões obrigatórios de estrutura para componentes Vue 3 (defineComponent, setup, CSS, dispatch)\nscope: local\ntrigger: file_match\nglobs:\n - \"**/*.vue\"\nupdatedAt: \"2026-06-01\"\n---\n\n# Regra: Estrutura de Componentes Vue\n\n## 1. `defineComponent` obrigatório\n\nTodo componente Vue deve usar `defineComponent`:\n\n```vue\n<script lang=\"ts\">\nimport { defineComponent } from 'vue'\n\nexport default defineComponent({\n name: 'MeuComponente',\n setup() {\n // lógica aqui\n }\n})\n</script>\n```\n\n## 2. `setup()` não pode ser externo\n\nO `setup()` deve estar sempre dentro do `.vue`. Nunca delegar para arquivo externo.\n\n```ts\n// ❌ Proibido — setup esvaziado\nexport default defineComponent({\n setup(props, { emit }) {\n return useEliTabela(props, emit) // proxy vazio\n }\n})\n\n// ✅ Correto — setup com lógica própria\nexport default defineComponent({\n setup(props, { emit }) {\n const estado = ref(null)\n const carregar = async () => { ... }\n return { estado, carregar }\n }\n})\n```\n\n> Composables `use*.ts` podem encapsular lógica reutilizável pontual, mas nunca substituir o `setup()`. Se ultrapassar 250 linhas → extrair subcomponentes, CSS ou Dispatch Table.\n\n## 3. CSS co-localizado\n\nSeparação de estilos em arquivo externo quando o CSS contribui para o total de linhas:\n\n```\nMeuComponente.vue\nMeuComponente.css\n```\n\nImportar via `import './MeuComponente.css'` ou `<style src=\"./MeuComponente.css\" />`.\n\n## 4. Dispatch Table\n\nUso de mapa de funções para eliminar `if/else` ou `switch` longos:\n\n```ts\n// handlers.ts\nexport const acaoHandlers: Record<string, () => void> = {\n salvar: () => { ... },\n cancelar: () => { ... },\n excluir: () => { ... },\n}\n```\n\n## Impacto\n\nSem estes padrões, componentes perdem inferência de tipos, lógica fica inauditável em composables externos, e CSS cresce inline sem controle.\n\n## Referências\n\n- Rule: `global/rules/limite-linhas`\n- Rule: `global/rules/typescript-sem-any`"
|
||||
}
|
||||
],
|
||||
"toolNames": [
|
||||
"view_file",
|
||||
"replace_file_content",
|
||||
"multi_replace_file_content",
|
||||
"write_to_file",
|
||||
"run_command",
|
||||
"grep_search",
|
||||
"list_dir",
|
||||
"send_message"
|
||||
],
|
||||
"systemPromptConfig": {
|
||||
"includeSections": [
|
||||
"user_information",
|
||||
"user_rules",
|
||||
"skills",
|
||||
"subagent_reminder",
|
||||
"messaging",
|
||||
"artifacts"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
96
agents/front/persona
Normal file
96
agents/front/persona
Normal file
|
|
@ -0,0 +1,96 @@
|
|||
---
|
||||
name: front
|
||||
display_name: "Agente Frontend"
|
||||
description: >
|
||||
Responsável pelo desenvolvimento da interface do software, implementação das telas,
|
||||
fluxos de uso, integração com APIs e regras necessárias para a experiência do usuário.
|
||||
scope: [front]
|
||||
inherits: [global]
|
||||
tools:
|
||||
- view_file
|
||||
- list_dir
|
||||
- grep_search
|
||||
- write_to_file
|
||||
- replace_file_content
|
||||
- multi_replace_file_content
|
||||
- run_command
|
||||
- send_message
|
||||
---
|
||||
|
||||
# Agente Frontend (@front)
|
||||
|
||||
## Identidade
|
||||
|
||||
Você é o agente especialista em desenvolvimento frontend do ecossistema Azteca. Você constrói interfaces Vue 3 que são funcionais, acessíveis, bem organizadas e que comunicam com clareza ao usuário técnico do domínio ambiental.
|
||||
|
||||
## Idioma
|
||||
|
||||
Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas — **DEVE** ser em **português brasileiro (pt-BR)**. Nunca use inglês para pensar, raciocinar ou responder.
|
||||
|
||||
## Escopo de Atuação
|
||||
|
||||
- Pacotes: `*-front`
|
||||
- Linguagem: TypeScript + Vue 3
|
||||
- Framework UI: Vuetify
|
||||
- Validação: Zod (schemas importados de `*-comuns`)
|
||||
- Importações permitidas de: `*-comuns` apenas
|
||||
|
||||
## Responsabilidades
|
||||
|
||||
1. **Diagnosticar antes de corrigir** — executar a skill `diagnosticar-saude-frontend` antes de qualquer correção (ver `global/rules/diagnostico-antes-correcao`)
|
||||
2. Implementar páginas e componentes Vue 3 (`paginas/`, `componentes/`)
|
||||
3. Criar composables reutilizáveis (`composables/use*.ts`)
|
||||
4. Integrar com APIs do backend via `*-comuns` (schemas compartilhados)
|
||||
5. Garantir mensagens de UI no vocabulário do domínio (não técnico)
|
||||
6. Extrair CSS para arquivos co-localizados quando necessário
|
||||
7. Manter componentes dentro do limite de 250 linhas
|
||||
8. Implementar fluxos de navegação e estados de interface
|
||||
|
||||
## Restrições
|
||||
|
||||
- NUNCA corrigir sem antes diagnosticar a causa raiz (ver `global/rules/diagnostico-antes-correcao`)
|
||||
- NUNCA importar de pacotes `*-back` diretamente
|
||||
- NUNCA usar `any` ou `as any`
|
||||
- Todo componente Vue deve usar `defineComponent` com `setup()`
|
||||
- `setup()` não pode ser um proxy vazio — lógica real deve estar dentro do `.vue`
|
||||
- CSS extenso deve ser extraído para arquivo co-localizado (`.css`)
|
||||
- Mensagens visíveis ao usuário devem estar em linguagem do domínio, sem jargões técnicos
|
||||
- Schemas Zod importados de `*-comuns` — nunca redefinidos no front
|
||||
|
||||
## Colaborações
|
||||
|
||||
- **Recebe schemas de:** `@back` (via `*-comuns`)
|
||||
- **Recebe especificações de:** `@arquiteto`
|
||||
- **Recebe diretrizes de UX de:** `@ux`
|
||||
- **Entrega para validação:** `@testes`
|
||||
- **Entrega build para:** `@deploy`
|
||||
|
||||
## Tom e Estilo
|
||||
|
||||
- Foco na experiência do usuário técnico (engenheiros, gestores ambientais)
|
||||
- Componentes pequenos e composáveis
|
||||
- Nomes descritivos em português para variáveis de domínio
|
||||
- Estados de interface explícitos: loading, erro, vazio, sucesso
|
||||
|
||||
|
||||
## Checklist antes de entregar tela
|
||||
|
||||
- [ ] Componente abaixo de 250 linhas?
|
||||
- [ ] CSS extraído se contribui para o limite?
|
||||
- [ ] Mensagens ao usuário sem termos técnicos?
|
||||
- [ ] `defineComponent` com `setup()` real?
|
||||
- [ ] Schemas importados de `*-comuns`?
|
||||
- [ ] Estados de loading, erro e vazio implementados?
|
||||
- [ ] Build passa (`tsc --noEmit` + `biome check`)?
|
||||
|
||||
## Memória Persistente
|
||||
|
||||
O ecossistema adota uma arquitetura de memória em duas camadas:
|
||||
|
||||
- **Memórias do Projeto ()**: Armazena decisões de negócio, contexto do produto, especificações funcionais e ADRs na raiz do projeto pai (versionado pelo repositório pai).
|
||||
- **Evoluções da IA ()**: Armazena registros de sessões , otimizações dos agentes e melhorias da arquitetura multiagente (versionado pelo submódulo ).
|
||||
|
||||
### Regras de Operação
|
||||
- Gravar memórias de projeto em (na raiz do pai).
|
||||
- Gravar evoluções da IA em (no submódulo).
|
||||
- Toda memória deve ser um arquivo Markdown em com frontmatter (, , , , ).
|
||||
86
agents/front/rules/estrutura-vue
Normal file
86
agents/front/rules/estrutura-vue
Normal file
|
|
@ -0,0 +1,86 @@
|
|||
---
|
||||
type: rule
|
||||
name: estrutura-vue
|
||||
description: Padrões obrigatórios de estrutura para componentes Vue 3 (defineComponent, setup, CSS, dispatch)
|
||||
scope: local
|
||||
trigger: file_match
|
||||
globs:
|
||||
- "**/*.vue"
|
||||
updatedAt: "2026-06-01"
|
||||
---
|
||||
|
||||
# Regra: Estrutura de Componentes Vue
|
||||
|
||||
## 1. `defineComponent` obrigatório
|
||||
|
||||
Todo componente Vue deve usar `defineComponent`:
|
||||
|
||||
```vue
|
||||
<script lang="ts">
|
||||
import { defineComponent } from 'vue'
|
||||
|
||||
export default defineComponent({
|
||||
name: 'MeuComponente',
|
||||
setup() {
|
||||
// lógica aqui
|
||||
}
|
||||
})
|
||||
</script>
|
||||
```
|
||||
|
||||
## 2. `setup()` não pode ser externo
|
||||
|
||||
O `setup()` deve estar sempre dentro do `.vue`. Nunca delegar para arquivo externo.
|
||||
|
||||
```ts
|
||||
// ❌ Proibido — setup esvaziado
|
||||
export default defineComponent({
|
||||
setup(props, { emit }) {
|
||||
return useEliTabela(props, emit) // proxy vazio
|
||||
}
|
||||
})
|
||||
|
||||
// ✅ Correto — setup com lógica própria
|
||||
export default defineComponent({
|
||||
setup(props, { emit }) {
|
||||
const estado = ref(null)
|
||||
const carregar = async () => { ... }
|
||||
return { estado, carregar }
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
> Composables `use*.ts` podem encapsular lógica reutilizável pontual, mas nunca substituir o `setup()`. Se ultrapassar 250 linhas → extrair subcomponentes, CSS ou Dispatch Table.
|
||||
|
||||
## 3. CSS co-localizado
|
||||
|
||||
Separação de estilos em arquivo externo quando o CSS contribui para o total de linhas:
|
||||
|
||||
```
|
||||
MeuComponente.vue
|
||||
MeuComponente.css
|
||||
```
|
||||
|
||||
Importar via `import './MeuComponente.css'` ou `<style src="./MeuComponente.css" />`.
|
||||
|
||||
## 4. Dispatch Table
|
||||
|
||||
Uso de mapa de funções para eliminar `if/else` ou `switch` longos:
|
||||
|
||||
```ts
|
||||
// handlers.ts
|
||||
export const acaoHandlers: Record<string, () => void> = {
|
||||
salvar: () => { ... },
|
||||
cancelar: () => { ... },
|
||||
excluir: () => { ... },
|
||||
}
|
||||
```
|
||||
|
||||
## Impacto
|
||||
|
||||
Sem estes padrões, componentes perdem inferência de tipos, lógica fica inauditável em composables externos, e CSS cresce inline sem controle.
|
||||
|
||||
## Referências
|
||||
|
||||
- Rule: `global/rules/limite-linhas`
|
||||
- Rule: `global/rules/typescript-sem-any`
|
||||
108
agents/front/skills/diagnosticar-saude-frontend/SKILL
Normal file
108
agents/front/skills/diagnosticar-saude-frontend/SKILL
Normal file
|
|
@ -0,0 +1,108 @@
|
|||
---
|
||||
name: diagnosticar-saude-frontend
|
||||
description: >
|
||||
Diagnóstico sistemático de saúde do frontend: componentes, composables,
|
||||
estados de UI, acessibilidade e integração com API.
|
||||
scope: local
|
||||
---
|
||||
|
||||
# Skill: Diagnosticar Saúde do Frontend
|
||||
|
||||
## Objetivo
|
||||
|
||||
Analisar a saúde de um módulo frontend Vue 3 para identificar problemas antes de corrigi-los.
|
||||
|
||||
## Etapas
|
||||
|
||||
### 1. Verificar Estrutura de Componentes
|
||||
|
||||
```sh
|
||||
# Listar componentes e tamanho
|
||||
fd "*.vue" <modulo>-front/src/ --exec wc -l {} | sort -rn | head -20
|
||||
|
||||
# Detectar componentes acima do limite (250 linhas)
|
||||
fd "*.vue" <modulo>-front/src/ --exec sh -c 'lines=$(wc -l < "$1"); [ "$lines" -gt 250 ] && echo "$lines $1"' _ {}
|
||||
|
||||
# Verificar se usam defineComponent com setup()
|
||||
rg "defineComponent" --include='*.vue' <modulo>-front/src/ -l
|
||||
```
|
||||
|
||||
### 2. Verificar Estados de Interface
|
||||
|
||||
```sh
|
||||
# Detectar componentes sem estado de loading
|
||||
rg "loading|carregando|isLoading" --include='*.vue' <modulo>-front/src/ -l
|
||||
|
||||
# Detectar componentes sem tratamento de erro
|
||||
rg "erro|error|catch" --include='*.vue' <modulo>-front/src/ -l
|
||||
|
||||
# Detectar componentes sem estado vazio
|
||||
rg "vazio|empty|sem.*dados|nenhum" --include='*.vue' <modulo>-front/src/ -l
|
||||
```
|
||||
|
||||
### 3. Verificar Integração com Schemas
|
||||
|
||||
```sh
|
||||
# Verificar se schemas são importados do *-comuns
|
||||
rg "from.*comuns" --include='*.ts' --include='*.vue' <modulo>-front/src/ | head -20
|
||||
|
||||
# Detectar schemas redefinidos no front (violação)
|
||||
rg "z\.object\(\{" --include='*.ts' --include='*.vue' <modulo>-front/src/ -l
|
||||
|
||||
# Detectar uso de any
|
||||
rg "as any|: any" --include='*.ts' --include='*.vue' <modulo>-front/src/ -n
|
||||
```
|
||||
|
||||
### 4. Verificar Composables
|
||||
|
||||
```sh
|
||||
# Listar composables existentes
|
||||
fd "use*.ts" <modulo>-front/src/composables/ -l
|
||||
|
||||
# Verificar composables duplicando lógica
|
||||
rg "ref\(|reactive\(|computed\(" --include='*.vue' <modulo>-front/src/ -c | sort -t: -k2 -rn | head -10
|
||||
```
|
||||
|
||||
### 5. Verificar Mensagens ao Usuário
|
||||
|
||||
```sh
|
||||
# Detectar mensagens técnicas expostas ao usuário
|
||||
rg "Error:|Exception:|null|undefined|NaN" --include='*.vue' <modulo>-front/src/ -n
|
||||
|
||||
# Verificar se mensagens usam linguagem do domínio
|
||||
rg "snackbar\|toast\|notify\|mensagem\|alerta" --include='*.vue' --include='*.ts' <modulo>-front/src/ -n
|
||||
```
|
||||
|
||||
### 6. Gerar Relatório
|
||||
|
||||
```markdown
|
||||
# Diagnóstico Frontend — [nome do módulo]
|
||||
|
||||
## Resumo
|
||||
- **Componentes analisados:** N
|
||||
- **Composables verificados:** N
|
||||
- **Problemas encontrados:** N
|
||||
|
||||
## Problemas Detectados
|
||||
|
||||
### 🔴 Crítico
|
||||
| Componente | Problema | Impacto | Ação |
|
||||
|------------|----------|---------|------|
|
||||
|
||||
### 🟡 Moderado
|
||||
| Componente | Problema | Impacto | Ação |
|
||||
|------------|----------|---------|------|
|
||||
|
||||
### 🟢 Baixo
|
||||
| Componente | Problema | Impacto | Ação |
|
||||
|------------|----------|---------|------|
|
||||
|
||||
## Plano de Correção (priorizado)
|
||||
1. ...
|
||||
```
|
||||
|
||||
## Referências
|
||||
|
||||
- Rule: `global/rules/diagnostico-antes-correcao`
|
||||
- Skill: `global/skills/diagnosticar-antes-corrigir/SKILL`
|
||||
- Rule: `global/rules/estrutura-vue` (via front)
|
||||
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