| name | prodesp-flow-visual-csv-first |
| description | Fluxo visual de negócio PRODESP — CSV de layout (colunas Nível 0–6) como fonte da verdade antes do HTML swimlane. Regras de choice, spine col 0, merge encadeado, muleApp/cores, omitir proxy HTTP entre apps. Use com comando /fluxo-visual, ao criar diagrama swimlane vertical, pagamentos-job-recente-visual, credenciais-job-recente_flow, ou quando o usuário pedir "faça fluxo", "diagrama do scheduler" ou CSV antes do HTML. |
Flow visual — CSV primeiro, HTML depois
Comando Cursor: /fluxo-visual (.cursor/commands/fluxo-visual.md) — atalho que dispara esta skill.
Workflow obrigatório (novos fluxos)
0. (novo) node .cursor/skills/prodesp-flow-visual-csv-first/scripts/scaffold-flow-visual.js --slug {slug} --flow {flow}
1. Mapear negócio + integrações (XML, README, sequencia.puml)
2. Montar CSV de layout ← fonte da verdade (usuário valida no Excel)
3. Usuário aprova CSV
4. node scripts/apply-layout-from-csv.js → positions JSON
5. Abrir index.html — swimlane carrega posições + displayLabel do CSV
6. Ajustar flow.json (nós, links, muleApp) e Mule doc:name quando título for aprovado
Não publicar layout swimlane definitivo sem CSV validado, salvo protótipo descartável.
Onde ficam os artefatos
| Artefato | Caminho |
|---|
| Regras de colunas | regras-layout-colunas-choice.md |
| Template CSV | flow-layout-colunas-template.csv |
| CSV do fluxo | tarefas/{slug}-visual/data/{flow}_flow-layout-comma.csv |
| Posições geradas | tarefas/{slug}-visual/data/{flow}_flow-layout-positions.json |
| Grafo | tarefas/{slug}-visual/data/{flow}_flow.json |
| Aliases CSV→id | tarefas/{slug}-visual/scripts/layout-node-aliases.json |
| Renderer | tarefas/{slug}-visual/js/swimlane-app.js |
| Encoding Excel | .cursor/rules/csv-utf8-excel.mdc |
Referência: tarefas/pagamentos-job-recente-visual/
Formato CSV
Colunas: tipo, Nível, Nível 0 … Nível 6
- Vírgula, UTF-8 com BOM, CRLF
tipo: vazio · choice · choice-end · end · *… (rascunho)Nível: profundidade do choice (0 = tronco)- Mesma linha = ramos que saem juntos (Sim col 0 + alternativa col 1+)
Regras de layout (resumo)
Documento completo: regras-layout-colunas-choice.md.
| Regra | Detalhe |
|---|
| Choice | Texto sempre em Nível 0 |
| Caminho feliz | Desce em Nível 0 |
| Alternativas | Coluna à direita conforme profundidade do bloco (não col+1 fixo) |
| Dois filhos visíveis | Sim e alternativa na mesma linha (ou linha abaixo). Sim só “continua” → nó explícito (Reutilizar pedido existente, etc.). Se ambíguo, perguntar |
| choice-end | tipo=choice-end, texto END choice <pergunta>? — sempre Nível 0 (spine) |
| Rótulo merge | CSV: END choice … → tela: Fim do choice · <pergunta> |
| Batch END | Vários choice-end consecutivos no spine encadeiam merges antes do próximo passo (ex.: Pedido → Payment → Pagamento efetivado → Estados SF) |
| Negócio em outra app | Manter no CSV (ex. Pedido existe? no p-api) mesmo sem <choice> na mgmt-s-api |
| Proxy HTTP omitido | Request mgmt→outra Mule app não entra no diagrama; desenhar lógica dentro da app destino |
| muleApp | Campo muleApp em flow.json; cor do card = swatch da legenda no topo |
| Títulos | CSV/displayLabel = linguagem de negócio (não copiar doc:name vago do Studio). Alinhar doc:name no XML quando usuário aprovar título |
Cores por Mule app (swimlane)
Definidas em swimlane-app.js → MULE_APPS. Legenda só de apps (#mule-app-legend no HTML) — sem legenda de ícone externo.
| App | Uso típico |
|---|
management-payments-receipts-s-api | Job / spine principal (azul) |
data-integrator-p-api | Lógica expandida (verde suave) — pedido, empresa, etc. |
Novas apps: adicionar entrada em MULE_APPS, CSS [data-mule-app="…"] e legenda dinâmica.
Passos do agente após CSV aprovado
flow.json: nós, links, muleApp, nós display (*-sim-display, cota-nao-display) quando necessário.layout-node-aliases.json:
labels: rótulo CSV → idbyRowCol: "row:col" → id (mesmo texto em linhas diferentes)
- Rodar:
cd tarefas/{slug}-visual
node scripts/apply-layout-from-csv.js
- Validar
unresolved no stdout — corrigir aliases ou CSV.
- Abrir
index.html (Live Server).
- Se título aprovado pelo usuário: atualizar
doc:name no XML Mule correspondente.
Renderer (swimlane-app.js) — comportamento
injectMergeNodes: bolinhas de merge; choices aninhados processados antes dos externos (evita roubar links).wireSpineMergeChain: merges consecutivos no spine encadeiam antes do próximo choice/end (não pular bolinhas).choice-end no script: apply-layout-from-csv.js força col 0 para merges.- Não ocultar merges intermediários no spine (
hiddenMergeIds vazio).
- Fallback sem CSV:
computeLayout() (não usar para entrega final).
Diagrama horizontal vs swimlane vertical
| Tipo | Skill |
|---|
Board horizontal (mapeamento-visual-flows/) | mulesoft-flow-visual-diagram |
| Swimlane vertical + CSV colunas | esta skill |
| Swimlane + logs CH2 por pedido/nó | prodesp-flow-visual-hub |
Logs no diagrama swimlane (Flow Visual Hub)
Quando o swimlane tiver overlay de logs (ex. pagamentos):
flow.json: cada nó com log precisa de id estável (= nodeId nos log-points).{flow}_flow-log-points-overrides.json: tokens da mensagem runtime (matchBefore/matchAfter/matchInfo).- Gerar JSON:
cd tarefas/flow-visual-hub && npm run extract-log-points.
index.html do diagrama: /js/log-view.js + /js/flow-log-bridge.js (servidos pelo hub na 8790).- Títulos do painel usam
businessLabel / docName do flow.json.
Skill completa: .cursor/skills/prodesp-flow-visual-hub/SKILL.md.
