.agent/skills/criar-fluxograma/SKILL.md

---
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/codigo-limpo` (ou `global/workflows/otimizar-codigos`)
- Skill: `global/skills/documentar-decisao-tecnica/SKILL` (para decisões que geram fluxogramas)