| name | integration-sequence-diagram |
| description | Criar diagramas de sequência PlantUML em nível integração (apps + HTTP endpoints). Classifica pedido genérico (OAuth, SAML) vs projeto; resolve mapping via product-definition ou workspace-links.yaml. Usar quando pedir diagrama de sequência, documentação de fluxo, integração entre sistemas ou sequencia.puml. |
Diagramas de sequência — integração
Níveis de detalhe
| Nível | Default | Conteúdo | Omitir |
|---|
| integração | Sim | Apps, backends externos, METHOD /path, gatilhos, alt/opt de negócio | Subflows, flow-ref, APIKit, DWL, c-get-access-token, setas App -> App internas |
| implementação | Só se pedir | Tudo acima + subflows, transforms | — |
Palavras-chave para implementação: "nível implementação", "com subflows", "detalhe Mule".
Passo 0 — Classificar pedido
Modo genérico (sem mapping)
Pedidos educacionais ou padrões conhecidos sem apps/endpoints do projeto:
- Ex.: "diagrama OAuth 2.0 authorization code", "fluxo SAML", "login JWT"
→ Gerar PlantUML direto. Não procurar mapping.
Modo projeto
Acionar quando houver: nomes de apps Mule (*-s-api, *-p-api), endpoints /v1/..., referência a product-definition, domínio/regra BR-*, PBI PRODESP, ou @product-definition.
→ Seguir resolução de mapping (passo 1).
Passo 1 — Resolver mapping (modo projeto)
Ordem de resolução:
workspace-links.yaml em qualquer root do workspace:
.ia/workspace-links.yaml- Campos:
productDefinition.path, productDefinition.mappings
- Pasta
product-definition/ no workspace:
- Ler
.ia/project.md
- Mapping:
mappings/mulesoft-integrations.yaml (ou path em project.md)
- Path explícito do usuário
- Não encontrado → mensagem:
Não encontrei mapping de integração.
Opções:
a) Informar caminho do YAML de mapping
b) Adicionar repo product-definition ao workspace (recomendado)
c) Gerar bootstrap do mapping (scan único no código) — confirmar?
d) Criar repo product-definition para regras, telas e integrações versionadas
Se product-definition existir mas mapping ausente → ler .ia/project.md para path canônico e oferecer bootstrap.
Passo 2 — Usar mapping
- Localizar integração por
id, endpoint, app alvo ou entryPoint.id
- Exibir tabela Relacionamento (primeira app → backend) antes de gerar arquivos
- Múltiplos
entryPoints → avisar N origens; sugerir um .puml por origem; aguardar confirmação
- Validar no código somente se: mapping incompleto, refresh solicitado, ou nível implementação
Passo 3 — PlantUML (nível integração)
Participantes
Apps Mule, schedulers/gateways na borda, backends (Salesforce, Wallet Dados, etc.).
Setas
- Entre apps:
GET /v1/empresas, POST /v1/pedidos/compra — incluir prefixo de versão do contrato
- Para backend externo: path real (ex.
POST /pedidos-compra no Wallet — ler properties da s-api se necessário)
- Proibido no nível integração:
Mgmt -> Mgmt : subflow, tags plugin Exchange
Gatilhos de entrada
| type | Label exemplo |
|---|
| rest | POST /v1/pagamentos/callback |
| scheduler | job credenciais (2 min) |
Respostas
response ou JSON pedido — sem HTTP response.
Passo 4 — Onde salvar (modo projeto)
Default: app de entrada, no repo Git da app:
{repo-app}/docs/fluxos/{caso}/{origem}/
├── README.md
└── sequencia.puml
Rascunhos de dev: tarefas/ no workspace de dev — não em product-definition.
README: cadeia por endpoints HTTP; links Git relativos ou Azure DevOps (git remote get-url). Nunca workspace-prodesp-app/ em docs commitados.
Exportar PNG para Markdown / Azure DevOps
Repositórios Git (ex.: product-definition) não renderizam .puml no browser. Gerar PNG (ou SVG) e referenciar no README com .
Instalação PlantUML (máquina do dev)
Não baixar plantuml.jar do GitHub em /tmp nem procurar jar no projeto. Usar, nesta ordem:
- Comando
plantuml no PATH (wrapper em ~/bin/plantuml no Windows do Lucas)
- Variável
PLANTUML_JAR apontando para o jar
- JAR canônico fixo:
C:\workspace\plantuml\plantuml.jar (versão atual do time: 1.2026.2)
Outras cópias na máquina (não usar para export/commit pelo agente):
| Local | Notas |
|---|
C:\workspace\plantuml\plantuml-1.2026.2.jar | Duplicata do mesmo arquivo; pode remover ou manter só plantuml.jar |
~/.cursor/extensions/jebbs.plantuml-*/plantuml.jar | Jar embutido na extensão VS Code/Cursor — versão diferente da canônica |
/tmp/plantuml.jar | Download temporário de sessões anteriores — ignorar |
Pré-requisitos: JDK no PATH (java) e Graphviz (dot no PATH) para PNG/SVG.
Wrapper global (Git Bash): ~/bin/plantuml executa:
java -Dfile.encoding=UTF-8 -jar "$PLANTUML_JAR" -charset UTF-8 "$@"
com PLANTUML_JAR default C:/workspace/plantuml/plantuml.jar.
Atualizar o jar: substituir C:\workspace\plantuml\plantuml.jar pelo download em plantuml.com/download; validar com plantuml -version.
Cursor / VS Code (User settings, opcional mas recomendado):
"plantuml.jar": "C:\\workspace\\plantuml\\plantuml.jar",
"plantuml.render": "Local",
"plantuml.jarArgs": ["-charset", "UTF-8"],
"markdown-preview-enhanced.plantumlJarPath": "C:\\workspace\\plantuml\\plantuml.jar"
Variável de ambiente (opcional): PLANTUML_JAR=C:\workspace\plantuml\plantuml.jar no Windows (User ou System).
Acentuação PT-BR (obrigatório)
- Salvar
.puml em UTF-8 (sem alterar para ANSI/Windows-1252).
- PlantUML usa
windows-1252 por default (-charset); sem override, integração vira integração no PNG.
- Preferir o wrapper (já inclui charset):
plantuml -tpng caminho/diagrama.puml
Equivalente explícito:
java -Dfile.encoding=UTF-8 -jar "C:/workspace/plantuml/plantuml.jar" -charset UTF-8 -tpng caminho/diagrama.puml
Nome do PNG: com @startuml sequencia no arquivo sequencia.puml, a saída é sequencia.png na mesma pasta. Rodar o comando no diretório do .puml ou passar caminho completo.
Fonte (Graphviz / PNG no Windows)
Se acentos ainda falharem no PNG (quadrados ou caracteres omitidos), definir fonte Unicode no diagrama ou include compartilhado:
skinparam defaultFontName "Segoe UI"
Em product-definition, C4 inclui dominios/_shared/c4-styles.puml após C4-PlantUML (já com Segoe UI).
Validar antes de commitar
- Abrir o PNG gerado e conferir títulos/legendas com
ç, ã, õ, é.
- Ou gerar SVG temporário (
-tsvg) e buscar entidades corretas (ç = ç, ã = ã).
- Após alterar
.puml, apagar PNG antigo ou usar -nometadata se trocou charset — metadados em PNG antigo podem induzir skip incorreto.
Onde commitar imagens
| Contexto | Pasta |
|---|
| Sequência por app | {repo-app}/docs/fluxos/.../ |
| C4 por domínio | product-definition/dominios/{dominio}/diagramas/ |
Commitar .puml + PNG juntos; README com embed markdown.
Perfil MuleSoft (modo projeto + apps Mule)
Camadas: -e-api, -p-api, -s-api.
Documentação commitada: só HTTP entre apps, não operação plugin (cadastrar-um-novo-pedido).
Para implementação Mule: skills do projeto (mulesoft-app-implementation, mulesoft-api-spec).
Backend Wallet: paths em config-{env}.yaml (wallet.*Path); GET v2 vs POST legacy conforme properties.
Bootstrap de mapping (sob confirmação)
Scan único quando mapping ausente:
pom.xml → grafo mule-plugin-*- Flows APIKit → endpoints expostos
- Listeners/schedulers → entry points
http:request / plugin tags → arestas entre apps
Gravar em product-definition/mappings/mulesoft-integrations.yaml — nível integração (sem subflows).
Atualizar .ia/project.md se path diferente.
Manutenção
Drift detectado (rg encontra caller novo) → atualizar mapping no product-definition, não no monorepo de dev.
Regras de negócio: product-definition/dominios/ — ler frontmatter integrations para contexto.
Referências por repo
| Repo | Arquivo |
|---|
| product-definition | .ia/project.md, mappings/mulesoft-integrations.yaml |
| workspace de dev | .ia/workspace-links.yaml, AGENTS.md |
