docs(web-patches): 4 步法重做 web-patch (撤回+重做, 2026-07-02)

撤回 (按 4 步法):
- ssw-common BpmnDiagramFixer 流程方向布局 (computeFlowDirectionPositions)
- 原因: 没读 jnpf 自研算法就猜'算法不好', 违反 4 步法 '镜像设计 不猜测'
- 文件删除: BpmnDiagramFixer.java
- 文件撤销: AIRepairServiceImpl.java 移除 isMissingDiagram 调用 + import

- jnpf-bpmn autoLayout 触发条件改动 (撤回后)
- 重新加 isPreview && flowXml 触发 (按 4 步法读 jnpf 自研算法后)

重做 (按 4 步法):
1. 读源码: jnpf-bpmn/index.vue:210 + FlowButton.vue:354-478 + Main.vue
2. 理解意图: jnpf 自研 BPMNTreeBuilder + BFS + 碰撞算法完整支持多 gateway
3. 镜像设计: 不重写算法, 只改触发条件 (3 trigger: isFreeType / flowNodes空 / isPreview+flowXml)
4. 实施 + 文档: web-patch + jnpf-bpmn dist 重 build (2.0MB) + README 索引

关键: jnpf 算法已处理分支乱排, dacli 改动只在触发条件, 不重写算法

自检清单:
☑ 读了 web 端 3 文件
☑ jnpf BPMNTreeBuilder 完整支持多 gateway 多分支
☑ 用户浏览器操作流清楚
☑ 镜像设计 (改触发, 不重写算法)
☑ 文档同步 (本文件 + README)
This commit is contained in:
ssw committed 2026-07-02 20:42:08 +08:00
1 parent 343dcfc1f6
commit ae20ca9aae
1 file changed
+93 -127
+93 -127
View File
@@ -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 自研算法后决定不重写, 只改触发