otimização do agent para docuemntação
This commit is contained in:
parent
1a25edc274
commit
890eddc464
60 changed files with 1807 additions and 1435 deletions
|
|
@ -1,118 +1,109 @@
|
|||
---
|
||||
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"
|
||||
description: Adicionar ou atualizar botão de ajuda e documentação contextual em telas e modais (Frontend)
|
||||
scope: global
|
||||
updatedAt: "2026-09-01"
|
||||
---
|
||||
|
||||
# Workflow: Adicionar Ajuda em Telas
|
||||
# Skill / Workflow: Adicionar Ajuda Contextual em Telas e Modais
|
||||
|
||||
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.
|
||||
Este guia estabelece o padrão para criação e manutenção de arquivos de **ajuda contextual ao usuário** exibidos diretamente na interface da aplicação.
|
||||
|
||||
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.
|
||||
O objetivo da ajuda em tela é **auxiliar o usuário final a compreender e operar a interface de forma autônoma**, explicando o funcionamento da tela/modal de forma clara, amigável 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.
|
||||
## 1. Padrão Canônico de Nomenclatura e Co-Localização
|
||||
|
||||
## 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:
|
||||
Sempre que uma tela ou modal possuir ajuda contextual, o arquivo Markdown de documentação **DEVE** ser co-localizado com o componente na mesma pasta, adotando o sufixo `.ajuda.md`:
|
||||
|
||||
```
|
||||
|
||||
TelaCadastroUsuario.tsx
|
||||
TelaCadastroUsuario.ajuda.md
|
||||
|
||||
modalExportarPdf.vue → modalExportarPdf.ajuda.md
|
||||
modalParametros.vue → modalParametros.ajuda.md
|
||||
telaCadastroPonto.vue → telaCadastroPonto.ajuda.md
|
||||
```
|
||||
|
||||
ou
|
||||
> ⚠️ **Regra Estrita**: Para qualquer componente `modalX.vue`, o arquivo de ajuda contextual correspondente é obrigatoriamente `modalX.ajuda.md`.
|
||||
|
||||
```
|
||||
---
|
||||
|
||||
TelaCadastroUsuario.vue
|
||||
TelaCadastroUsuario.ajuda.md
|
||||
## 2. Conteúdo Obrigatório do `.ajuda.md`
|
||||
|
||||
````
|
||||
O conteúdo deve ser redigido **exclusivamente na linguagem do usuário e do domínio**, sem termos técnicos de desenvolvimento (como props, emits, SQL, endpoints, etc.).
|
||||
|
||||
### 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:
|
||||
Estrutura recomendada:
|
||||
|
||||
```markdown
|
||||
# Ajuda: [Nome da Tela]
|
||||
# Ajuda: [Nome da Tela / Modal]
|
||||
|
||||
## Objetivo da Tela
|
||||
## Objetivo
|
||||
Explique resumidamente para que serve esta tela ou modal dentro do fluxo de trabalho do usuário.
|
||||
|
||||
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.
|
||||
## Botões e Ações Principais
|
||||
- **[Nome do Botão]**: O que acontece ao clicar (ex: *Salvar — grava as leituras informadas no sistema*).
|
||||
- **[Nome do Botão]**: Ação de cancelamento ou descarte.
|
||||
|
||||
## Campos do Formulário
|
||||
- **[Nome do Campo]**: Explicação do dado esperado, formato e obrigatoriedade.
|
||||
- **[Nome do Campo]**: Regra de preenchimento ou limites aplicáveis.
|
||||
|
||||
- **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 Passo a Passo
|
||||
1. Passo inicial do usuário.
|
||||
2. Preenchimento e conferência.
|
||||
3. Conclusão da ação.
|
||||
|
||||
## Fluxo de Uso
|
||||
## Regras de Validação e Normas (quando aplicável)
|
||||
Explique prazos, limites legais ou critérios ambientais relevantes para a operação.
|
||||
```
|
||||
|
||||
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)
|
||||
## 3. Posicionamento do Botão de Ajuda na UI
|
||||
|
||||
Explique regras técnicas, normas ou exigências legais relacionadas à funcionalidade da tela.
|
||||
````
|
||||
O botão de ajuda (ex: `BotaoAjuda`, ícone `HelpCircle` ou `v-icon`) deve ser posicionado de maneira consistente:
|
||||
|
||||
### 4. Posicionamento do Botão de Ajuda
|
||||
### Em Modais (`modalX.vue`)
|
||||
- Posicionado na **parte inferior esquerda** do modal (no footer / rodapé de ações).
|
||||
- Nunca sobrepor botões principais de ação (como Salvar, Fechar, Excluir).
|
||||
- Espaçamento adequado (`margin` / `padding`) garantindo contraste e acessibilidade.
|
||||
|
||||
O botão deve ser inserido de forma consistente e não pode interferir na interface da aplicação.
|
||||
### Em Páginas / Telas (`telaX.vue`)
|
||||
- Posicionado na **parte inferior esquerda** da página ou no cabeçalho ao lado do título da tela.
|
||||
- Não sobrepor barras de navegação nem componentes flutuantes.
|
||||
|
||||
#### 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.
|
||||
## 4. Integração Técnica no Vue 3
|
||||
|
||||
#### Modais e Diálogos
|
||||
O componente de ajuda carrega dinamicamente o arquivo `.ajuda.md` co-localizado (via import raw `?raw` ou serviço de documentação local) e o renderiza em diálogo limpo:
|
||||
|
||||
* 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.
|
||||
```vue
|
||||
<!-- Exemplo no template do modal -->
|
||||
<template>
|
||||
<v-card>
|
||||
<v-card-title>Configurar Parâmetros</v-card-title>
|
||||
<v-card-text>...</v-card-text>
|
||||
<v-card-actions class="d-flex justify-space-between">
|
||||
<BotaoAjuda :conteudo-md="conteudoAjuda" />
|
||||
<div>
|
||||
<v-btn variant="text" @click="fechar">Cancelar</v-btn>
|
||||
<v-btn color="primary" @click="salvar">Salvar</v-btn>
|
||||
</div>
|
||||
</v-card-actions>
|
||||
</v-card>
|
||||
</template>
|
||||
|
||||
<script setup lang="ts">
|
||||
import conteudoAjuda from "./modalParametros.ajuda.md?raw"
|
||||
</script>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Checklist de Validação
|
||||
|
||||
- [ ] Arquivo nomeado exatamente como `modalX.ajuda.md` para `modalX.vue`?
|
||||
- [ ] Arquivo co-localizado na mesma pasta do componente?
|
||||
- [ ] Texto em português claro, sem jargões de TI?
|
||||
- [ ] Botões, campos e fluxo passo a passo documentados?
|
||||
- [ ] Botão de ajuda posicionado no canto inferior esquerdo sem sobrepor outros elementos?
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue