aprimoração de ia

skills/criar-fluxograma/SKILL.md

@@ -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)