189 lines
5.5 KiB
Text
189 lines
5.5 KiB
Text
---
|
|
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)
|