vue-componentes/.agent/workflows/criar-fluxograma.global.md

description
Criar ou atualizar uma página de fluxograma interativo em qualquer sistema

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:

# 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

import mermaid from 'mermaid';

Inicialização com tema institucional

Adaptar as cores para a identidade visual do projeto:

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

// 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: .agent/workflows/documentar-codigo.global.md
• Skill: .agent/skills/documentar-decisao-tecnica/SKILL.md (para decisões que geram fluxogramas)