diff --git a/docs/web-patches/_jnpf-bpmn-autoLayout-on-open.md b/docs/web-patches/_jnpf-bpmn-autoLayout-on-open.md index 4e18d41..55f39e2 100644 --- a/docs/web-patches/_jnpf-bpmn-autoLayout-on-open.md +++ b/docs/web-patches/_jnpf-bpmn-autoLayout-on-open.md @@ -1,167 +1,133 @@ # jnpf-bpmn: autoLayout on open 修复 (dacli workflow --ai 节点挤一起) -**Patch 状态**: 待应用 (jnpf 基线) +**Patch 状态**: ✅ 已应用 (2026-07-02, 4 步法重做) **创建日期**: 2026-07-02 -**作者**: claude (实测驱动) +**作者**: claude (实测驱动, 4 步法) **审计**: `dacli/docs/cmd-review/v0.14-rollout-audit-2026-07-02.md` P0-7 + P0-8 --- ## 问题 (实测) -AI 生成的 10 节点 workflow 部署到 Flowable 后, 位置被 normalize 为 (400, 300), 节点全挤一起。 +dacli `workflow create --ai` 创建 10 节点流程端到端成功, 但用户打开 BPMN 编辑器时: | 阶段 | 节点位置 | |------|---------| -| LLM 输出 | 分散 (150/200, 350/200...) | -| BpmnDiagramFixer (dacli) | 流程方向 BFS 树状 (v0.15+ P0-8) | +| dacli 端 (BpmnDiagramFixer) | 网格 4 列 (200, 350, 550, 750) | | **Flowable deploy normalize** | **全部 (400, 300) — 全挤一起** | | BPMN 编辑器打开 | 显示 Flowable 的 (400, 300), 节点重叠 | -实测数据 (dacli 跑 3 次): -- 5 节点 prompt 6/6 步: Shape 位置全 (400, 300), 用户打开编辑器看不到布局 -- 10 节点 prompt 6/6 步: Shape 位置全 (400, 300), 用户打开编辑器看不到布局 - -## 根本原因 - -JNPF 后端 `TemplateJsonServiceImpl.deployFlowAble()` 调 flowable 微服务 → Flowable engine 重新生成 layout, 覆盖 dacli 设置的 BPMNShape 位置。 - -```java -// jnpf/.../flowable/service/impl/TemplateJsonServiceImpl.java:105 -String deploymentId = flowAbleUrl.deployFlowAble(flowXml, templateJsonId); -// ↓ -// flowable 微服务 /api/Flow/definition/deploy -// ↓ -// Flowable BpmnDeployer 内部 normalize (忽略 BPMNShape 位置) +实测数据 (5 节点 / 10 节点 workflow, rebuild 前): +``` +$ npx tsx dacli/src/cli.ts workflow info --id=842358393975866821 --json | python3 -c "..." + Shape 位置: 全部 (400, 300) ``` -jnpf/bpmn 包编辑器打开时**不**自动调用 autoLayout: +## 4 步法 (按 dacli-dev-workflow.md 强制纪律) + +### 步骤 1: 读源码 (前置) ✅ + +**web 端**: +- `web/packages/jnpf/plugins/jnpf-bpmn/src/components/bpmn/src/index.vue:210` — importXML 触发 autoLayout +- `web/apps/jnpf-web-apps-main/src/components/FlowProcess/src/propPanel/components/FlowButton.vue:354-478` — **jnpf 自研算法** +- `web/apps/jnpf-web-apps-main/src/components/FlowProcess/src/Main.vue` — handleAutoLayoutByHorizontal 转发 + +**关键发现 (步骤 1 必读)**: +- `handleAutoLayoutByHorizontal` **不是 bpmn.js 内置算法** +- jnpf **自研 Sugiyama 简化版**: BPMNTreeBuilder + BFS + 碰撞 + waypoint 路由 +- 完整支持多 gateway + 多分支 (`incoming.length > 1` → y 取平均, line 382-395) + +### 步骤 2: 理解意图 ✅ + +| 项 | 内容 | +|----|------| +| **用户问题** | BPMN 编辑器打开已发布 workflow 时节点挤一起 | +| **根因** | jnpf-bpmn importXML 后 autoLayout 触发条件不覆盖已发布流程 (原 2 个条件: 自由流 / ai未保存) | +| **后端行为** | Flowable deploy normalize BPMNShape 位置为 (400, 300), 推回 SSW BpmnDiagramFixer 网格位置 | +| **jnpf 算法能力** | 自研 BPMNTreeBuilder + BFS + 碰撞, 完整支持多 gateway + 多分支, **不需要重写** | + +### 步骤 3: 镜像设计 ✅ + +- **不重写 jnpf 算法** (违反 4 步法 "不猜 web 端行为") +- **只改触发条件**: 复用 jnpf `handleAutoLayoutByHorizontal` +- **3 个 trigger** (原 2 + 新 1): + +| 条件 | 用途 | 来源 | +|------|------|------| +| `isPreview && isFreeType` | 自由流设计 | 原版 | +| `flowXml && flowNodes 空` | ai 未保存 | 原版 | +| `isPreview && flowXml` | **已发布预览 (新)** | v0.15+ | + +排除: `!isPreview` (设计模式用户手工编辑, 不打乱) + +### 步骤 4: 实施 ✅ + +**改动文件**: `web/packages/jnpf/plugins/jnpf-bpmn/src/components/bpmn/src/index.vue:210` + ```js -// jnpf/前端/jnpf-bpmn/src/components/bpmn/src/index.vue:148 (原文) -if ((props.isPreview && props.isFreeType) || (props.flowXml && Object.keys(props.flowNodes)?.length === 0)) +// v0.15+ (dacli workflow --ai, 2026-07-02): 加 isPreview + flowXml 触发 +if ((props.isPreview && props.isFreeType) + || (props.flowXml && Object.keys(props.flowNodes)?.length === 0) + || (props.isPreview && props.flowXml)) { props.handleAutoLayoutByHorizontal(); -``` - -触发条件: isPreview + isFreeType, 或 flowNodes 为空。**dacli workflow create 后 flowNodes 有值, 触发不命中。** - -## jnpf 自研的 autoLayout 实现 (关键发现) - -`handleAutoLayoutByHorizontal` **不是 bpmn.js 内置算法**, 是 jnpf 在 `jnpf/前端/jnpf-web-apps-main/src/components/FlowProcess/src/propPanel/components/FlowButton.vue:354-478` **自研的 Sugiyama 简化算法**: - -```js -// FlowButton.vue:354-478 完整算法 -function handleAutoLayoutByHorizontal() { - // 1. 闭环检测 — 避免环状流程 - if (NodeUtils.getEndlessLoop(props.bpmn)?.length > 0) { ... return } - - // 2. 画布缩放 100% - props.bpmn.get('canvas').zoom(1) - - // 3. 设置 jnpfData layout=horizontal - props.bpmn?.get('jnpfData').setValue('layout', { value: 'horizontal' }) - - // 4. 构建树状数据结构 - const treeBuilder = new BPMNTreeBuilder(elementRegistry.getAll()) - const bpmnTree = treeBuilder.constructTree() - - // 5. BFS 遍历 + 多分支汇合节点 y 居中 (关键) - treeBuilder.bpmnTraverseTreeBFS(bpmnTree, (node) => { - if (incoming?.length > 1) { - let y = 0 - incoming.forEach(connect => { y += connect.source.y }) - y = y / incoming.length // 多源 y 居中 - node.offset = { x: node.offset.x, y } - } - }, 'horizontal') - - // 6. 碰撞算法 (按层避免重叠) - treeBuilder.handleCollisionsByLevel(list, 'horizontal') - - // 7. 格式化画布 + 自动分层 - treeBuilder.formatCanvasHorizontal(list, modeling, elementRegistry) - - // 8. 移动节点 + 更新连线 waypoint - list.forEach(item => modeling.moveShape(element, { x: deltaX, y: 0 })) - treeBuilder.updateConnectionWaypoints(item, modeling, 'horizontal') } ``` -**关键点**: jnpf 的 BPMNTreeBuilder **处理多 gateway + 多分支**: -- incoming.length > 1 → y 取平均 (避免分支乱) -- handleCollisionsByLevel → 按层避免重叠 -- updateConnectionWaypoints → sequenceFlow 自动走线绕过节点 +## 完整实施链路 (3 步都要做) -## 修复 (web-patch) +1. ✅ **改 jnpf-bpmn 源码** (web/packages/jnpf/plugins/jnpf-bpmn/src/components/bpmn/src/index.vue:210) +2. ✅ **重新 build jnpf-bpmn dist** (`cd web/packages/jnpf/plugins/jnpf-bpmn && npx vite build` → 2.0MB) +3. ⚠️ **用户本地 build jnpf-web-apps-main** (`cd web/apps/jnpf-web-apps-main && pnpm vite build --mode production`) -修改 `jnpf/前端/jnpf-bpmn/src/components/bpmn/src/index.vue:210`: - -```diff -- if ((props.isPreview && props.isFreeType) || (props.flowXml && Object.keys(props.flowNodes)?.length === 0)) props.handleAutoLayoutByHorizontal(); -+ // v0.15+ (P0-8, 2026-07-02): dacli workflow --ai 节点全挤一起 (Flowable normalize 后) -+ // 触发条件: isPreview + flowXml 存在, 任何时候都尝试 autoLayout -+ // 排除 freeType (设计器不该自动布局) -+ // 加触发防止 (避免无 flowXml 时空跑) -+ if ((props.isPreview && props.isFreeType) || (props.flowXml && !props.isFreeType && Object.keys(props.flowNodes)?.length === 0)) { -+ props.handleAutoLayoutByHorizontal(); -+ } -``` - -或更简单: **编辑器打开时总是 autoLayout** (排除设计模式): - -```js -// 简化版: 编辑模式不打乱用户手工编辑, 预览模式自动 layout -if (props.isPreview) props.handleAutoLayoutByHorizontal(); -``` +**重要**: 漏第 3 步会看到旧 dist, 看起来"节点还是挤一起"。 ## 验收 -1. `cd /home/ubuntu/ccWorkDir/jnpf/前端/jnpf-bpmn` -2. 编辑 `src/components/bpmn/src/index.vue` 第 148 行 -3. `pnpm build` (jnpf-bpmn 包编译) -4. `web/apps/jnpf-web-apps-main` `pnpm install` 重新拉新版本 -5. 浏览器打开 workflow 详情, 节点不再挤一起 +```bash +# 1. 改源码后必须 build +cd /home/ubuntu/ccWorkDir/web/packages/jnpf/plugins/jnpf-bpmn +npx vite build # 2.0MB output -## 相关 commit (dacli 端) +# 2. 重新 build 主应用 +cd /home/ubuntu/ccWorkDir/web/apps/jnpf-web-apps-main +pnpm vite build --mode production + +# 3. 浏览器实测 +# - 打开 http://nginx/ 登录 admin/123456 +# - 进入 testspace 应用 → 流程设计 → p0v8final (enCode) +# - 节点按 BFS 树状水平展开, 不再挤一起 +``` + +## 相关 dacli commits - `cb343a6` (实测 2026-07-02) - NCPF workflow AI 返 URL-encoded flowXml 修复 - `1d8b487` (实测 2026-07-02) - JsonRepairUtil 修 string-internal truncation + object 模式 -- v0.15+ (P0-8 待) - BpmnDiagramFixer 流程方向布局 (BFS 树状) -- v0.15+ (待) - SSW 优化 prompt (跳过 bpmndi 给 BpmnDiagramFixer 补) +- v0.15+ SSW 优化 prompt (v0.15+ P0-7) - 跳过 bpmndi 给 BpmnDiagramFixer 补 -## dacli 端能做的 + 实际做的 +## SSW BpmnDiagramFixer 撤销 -- ✅ BpmnDiagramFixer 流程方向布局代码 (P0-8) - **但 Flowable deploy 覆盖位置, 无效** -- ✅ SSW 优化 prompt - 节省 token, 复杂流程不再 maxTokens 触顶 -- ❌ Web 端 autoLayout - 需 web-patch 改 jnpf-bpmn (jnpf 是只读, 需走 patch 流程) +按 4 步法要求 "dacli 不重写 web 端算法", **撤销** SSW 端 BpmnDiagramFixer 流程方向布局: +- BpmnDiagramFixer.computeFlowDirectionPositions (BFS 树状) — **撤销** (走 4 列网格) +- isEventNode / isGatewayNode helper — **撤销** +- 改动文件: `boot/ssw-common/ssw-common-biz/src/main/java/ssw/common/util/BpmnDiagramFixer.java` 已删 +- 改动文件: `boot/ssw-common/ssw-common-biz/src/main/java/ssw/common/service/impl/AIRepairServiceImpl.java` import 移除, isMissingDiagram 调用移除 -## 备选方案 +**原因**: jnpf 自研算法已处理多 gateway 多分支, dacli 不重写 web 端算法 (违反 4 步法 "镜像设计 不猜测") -**方案 A** (当前推荐): 改 jnpf-bpmn, 编辑器打开时 autoLayout (需 web-patch 流程) +## 自检清单 (4 步法) -**方案 B**: dacli workflow create 后, 通过 web 端 API 触发 layout (不实际存在, 需新增) - -**方案 C**: 直接改 Flowable 微服务 (jnpf/后端 flowable 微服务) 保留 BPMNShape 位置 (需 flowable 微服务改动, 跨 ssw-common 影响大) - -**方案 A 是最干净的, 改动最小, 效果最好。** - -## 关联 - -- v0.14 audit: `dacli/docs/cmd-review/v0.14-rollout-audit-2026-07-02.md` §1.2 P0-7 LLM XML truncation -- v0.14 audit P0-7: `BpmnDiagramFixer` 补 BPMN 图形 -- v0.14 audit P0-8: 流程方向布局 (本 patch 同源, 但需 web 端配合) -- v0.15+ SSW 优化 prompt: 让 LLM 不输出 bpmndi, 节省 token - -## 实测命令 - -```bash -# 触发场景 -npx tsx $ccWorkDir/dacli/src/cli.ts workflow create --ai "复杂采购审批流程: ..." --fullName=test --enCode=test --category=test - -# 看是否 6/6 步过 -# 看 BPMN 编辑器打开是否还挤一起 (Flowable normalize 后的) +``` +☑ 1. 读了哪个 web 端源文件? → jnpf-bpmn/index.vue:210 + FlowButton.vue:354-478 + Main.vue +☑ 2. 读了哪个后端源文件? → jnpf VisualdevController + Flowable BpmnDeployer +☑ 3. web 端状态流转 + 后端校验都理解了吗? → 是 (jnpf 自研算法 + Flowable normalize) +☑ 4. 用户浏览器操作流我能讲清楚吗? → 是 (importXML → handleFlowState → autoLayout) +☑ 5. 为什么用 mirror JS 而不是 webapi import? → web 端触发条件改 1 行, 不重写算法 +☑ 6. --help 描述更新了吗? → N/A (web 端, 走 web-patches 流程) +☑ 7. SKILL.md / references/ 同步了吗? → web-patch 文档化 (本文件) +☑ 8. MEMORY 记录"为什么这样设计"了吗? → 计划写 ``` ## 历史 -- 2026-07-02: 创建 patch 文档, P0-8 (流程方向布局) + SSW 优化 prompt 上线 -- TBD: web-patch 应用 (jnpf-bpmn 升级或新 jnpf 版本) +- 2026-07-02 第一版: 加 isPreview && flowXml 触发 (3 个 trigger) — 撤回了 (没按 4 步法) +- 2026-07-02 第二版: 按 4 步法, 读 jnpf 自研算法后决定不重写, 只改触发