Files
eip4-platform/docs/plans/2026-06-26-在线流程Modeler-design.md
zhengwr e0e92a88b4 docs: 在线流程 Modeler 设计(brainstorming 拍定 D1-D9)
在已有 bpmn-js 流程图查看器 + 现成 /api/flow/deploy 之上扩成可编辑 BPMN 流程设计器:
老流程可编辑改、新流程可创建、全 BPMN/flowable 流程属性 + EIP4 办理人/会签/formKey 定制叠加。
决策:改存量+新建 / 草稿+同人确认部署(超管+校验+审计) / 草稿存 act_re_model /
标准全属性面板+EIP4控件 / 完整 activiti moddle 保真零丢失 / id 可逆净化保流程key /
flowable 原生版本隔离 / v1 不含 DMN/CMMN/表单设计器。4 阶段交付。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-26 09:42:06 +08:00

135 lines
9.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 在线流程定义 Modeler — 设计(2026-06-26)
> 在 EIP4 已有 bpmn-js 流程图查看器之上,扩成**可编辑的 BPMN 流程设计器**:老审批流程能在线编辑修改、新审批流程能在线创建,flowable 流程相关特性全支持,叠加 EIP4 专有语义(办理人/会签/表单绑定)。
>
> 经 brainstorming 逐项拍定(本文末「决策记录」)。承接审批闭环:[[2026-06-25-审批闭环-实施计划]]、流程图查看(main `0ee919b`)。
---
## 0. 目标与成功标准(用户拍定)
1. **老流程能正常编辑修改**(改造 eip4flow 里 1512 个真实迁移流程)。
2. **新功能流程能正常创建**(从空白/模板新建并部署)。
3. **功能不缺失**:全 BPMN/flowable 元素可编可配(各类任务/网关/事件/子流程/边界事件/定时器/信号/错误/补偿…)。
4. **支持 flowable 流程特性**:监听器/超时/异步/网关条件/多实例/事件定义等 flowable 扩展属性可编辑。
**v1 边界(不含)**:DMN(决策表)、CMMN(案例管理)、flowable 自带表单设计器(EIP4 表单走 WfTemplate/amis,不需要)。这三者是 flowable 里平级但独立的编辑器,若客户需要 DMN(复杂规则表)属未来另立评估。
---
## 1. 现状基线(已具备,~70% 基础设施)
| 件 | 状态 |
|----|------|
| 部署端点 `POST /api/flow/deploy`(bpmnXml → `createDeployment().addString().deploy()`) | ✅ 已有 |
| 读流程 BPMN `GET /api/flow/process/{pi}/diagram`(含中文 id 净化) | ✅ 已有 |
| `bpmn-js/lib/Modeler`(可编辑版) | ✅ 已在 eip4-web 依赖 |
| 引擎模型表 `act_re_model`(草稿存储) | ✅ 已有 143 行 |
| `bpmn-js-properties-panel` + `@bpmn-io/properties-panel` | ❌ 需 npm 加 |
| activiti/flowable moddle 描述符 | ❌ 需加(保真地基) |
| 无 `ACT_DE_*`(flowable-modeler 设计态表) | — 不依赖;不嵌 flowable-modeler(Angular 栈,off-stack;其底层本就是 bpmn-js) |
---
## 2. 架构与组件
**前端**(eip4-web,新 `ProcessModelerPage` + 路由 `/process-modeler/:modelId?`):
- 用 `bpmn-js/lib/Modeler`(替查看用的 `NavigatedViewer`)+ 完整元素 palette + `bpmn-js-properties-panel`。
- 布局:左画布 / 右属性面板 / 顶栏(保存草稿·发布上线·校验·返回)。
**后端**(flowable-service,新 `ProcessModelController`,复用既有 `RepositoryService`):
- `GET /api/flow/models` 列草稿
- `GET /api/flow/models/{id}` 取草稿 XML(`getModelEditorSource`)
- `POST /api/flow/models` 建草稿(`newModel`+`saveModel`+`addModelEditorSource`)
- `PUT /api/flow/models/{id}` 存草稿
- `POST /api/flow/models/{id}/deploy` 发布(草稿 XML → 复用既有 /deploy 逻辑)
- `GET /api/flow/process/{procDefId}/source` 载入存量流程为新草稿(复用 /diagram 的中文 id 净化)
- gateway(platform-flow-gateway)转发对应 `/api/workflow/models/**`,套 JWT 权限。
**存储**:草稿 = `act_re_model`(flowable 原生);发布 = `act_re_deployment`/`act_re_procdef`(引擎原生版本机制)。
**版本与运行实例**:发布 = 引擎出**新版本**;**运行中实例留在旧版本不受影响**(flowable 原生版本隔离)。v1 **不做实例迁移**(YAGNI;迁移属高级特性,另案)。
---
## 3. 数据流
1. **新建**:空白/模板 → 编辑 → 存草稿(act_re_model)。
2. **改存量**:打开 procDef → `/source` 灌成草稿 → 编辑 → 存草稿。
3. **发布**:草稿 XML → 同人确认弹窗(影响摘要)→ 校验门 → `/deploy` → 新版本。
---
## 4. 属性面板:标准全套 + EIP4 定制叠加
**标准面板**(bpmn-js-properties-panel):出全部 flowable 流程属性——节点名/文档、网关条件、多实例、监听器、超时、异步、事件定义等 → 满足「功能不缺失 / flowable 特性」。
**EIP4 定制控件**(叠加的自定义分组):
1. **办理人**:读节点 `activiti:candidateUsers="${candidateUsersHandler.getCandidateUsers(execution,'<JSON>')}"` → 解析内嵌 JSON → 友好编辑(角色/部门/前序处理人/scriptUser 多项,对齐已移植的 `UserProperty` 结构)→ 回写表达式。**前后端同源复用 CandidateUsersHandler 配置格式**。
2. **会签**:开关 → `multiInstanceLoopCharacteristics`(并行/顺序)+ collection=`${multiInstanceUsersHandler.getUsers(execution,'<JSON>')}` + 完成规则(全票 `nrOfCompletedInstances/nrOfInstances==1` / 过半 / 指定数)。人员来源复用办理人控件。
3. **formKey**:选择器列 `view_wftemplate` → 设 `formKey=view_wftemplate_id`,绑 EIP4 业务表单。
**原生 assignee/candidateUsers 字段不压**(用户拍定):保留显示供调试/高级,加灰字提示「EIP4 引擎以下方办理人控件为准」缓解误填。
---
## 5. moddle 扩展(保真地基)
迁移 BPMN 用 `xmlns:activiti="http://activiti.org/bpmn"` 存扩展。bpmn-js 默认不认 → 重新导出**会丢扩展**(致命)。**提供完整 activiti moddle 描述符**(JSON,声明整个 activiti 命名空间的元素/属性,非最小集),让编辑器读写原样保留 → 既保真零丢失,又使「flowable 扩展全属性可编辑」。activiti 命名空间予以保留(不归一为 flowable,避免引擎侧读取依赖断裂)。
**铁律测试**:载入真实流程 BPMN → 不改 → 导出 → XML 语义 diff **零丢失**(覆盖 activiti 扩展 / 会签 / 办理人表达式)。
---
## 6. 🔴 关键保真细节:id 可逆净化(保流程 key)
`/diagram` 把中文 process id(如「招投标工程评审流程」)净化为 `nXXX` 是给 bpmn-js 渲染用的。若拿净化版去部署,**流程 key 会变成 nXXX,断了与存量实例/引用的连续性**。
**对策**:载入改存量时**记下 id 映射**(原中文 ↔ 安全 ASCII),编辑器用净化版;**发布时逆向还原原始中文 key**(新加节点的 ASCII id 保留)。这样存量流程 key 不变、版本连续。映射随草稿一并存。
---
## 7. 红线 / 权限 / 审计(套「草稿 + 同人确认部署」)
- **部署门限超管**:`POST /models/{id}/deploy` JWT role 校验(控制器层拦),非超管 403。
- **同人确认**:前端发布弹窗显**影响摘要**(流程 key、当前版本号、运行中实例数、改了哪些节点的办理人/会签)→ 确认才部署。
- **校验门**:部署前服务端跑 flowable 部署校验 + EIP4 校验(办理人表达式可解析 / formKey 命中 view_wftemplate / 会签完成条件合法)→ 不过不部署。
- **审计**:每次部署记一条(谁 / 何时 / model→deploymentId / 新版本号)。
- 不分离作者/审批(v1 取舍;作者-审批分离属 v2 增强)。
**错误处理**:草稿损坏/解析失败 → 422 不部署;校验失败 → 返回具体节点错误;权限不足 → 403。
---
## 8. 测试策略
1. **moddle 保真**:载真实流程 → 不改 → 导出 → XML 语义 diff 零丢失(activiti 扩展/会签/办理人表达式)。
2. **控件双向**:办理人 JSON ↔ 表达式、会签完成条件生成、formKey picker。
3. **id 可逆净化**:净化→还原回原 key、新节点 ASCII id 保留、映射稳定。
4. **后端**:model CRUD + deploy(校验门/权限门/审计)单测。
5. **live e2e**:载存量会签流 → 改办理人 → 存草稿 → 发布 → 起实例验新办理人生效;Playwright 走查编辑器渲染(含中文节点名、palette、属性面板)。
---
## 9. 分阶段交付
- **阶段 1**:完整 activiti moddle 保真 + 只读载入存量(编辑器能开真实流程、palette/标准属性可见、不丢扩展)+ 保真零丢失测试。
- **阶段 2**:三 EIP4 定制控件(办理人/会签/formKey)+ 存草稿(act_re_model)+ 控件双向测试。
- **阶段 3**:发布门(校验+超管权限+同人确认+审计)+ id 可逆净化 + 后端 deploy 门测试。
- **阶段 4**:新建流程(空白/模板)+ live e2e(载存量改办理人→发布→起实例验生效)+ Playwright 走查。
每阶段独立可验、可合 main。
---
## 决策记录(brainstorming 2026-06-26)
| # | 决策 | 取定 |
|---|------|------|
| D1 | v1 范围 | **改存量 + 新建**(两者都要) |
| D2 | 部署门 | **草稿 + 同人确认部署**(限超管 + 校验 + 审计;不分离作者/审批) |
| D3 | 草稿存储 | **复用 flowable `act_re_model`**(model→deployment 一条龙) |
| D4 | 属性面板 | **标准全套 + EIP4 定制控件(办理人/会签/formKey)**;原生字段不压(加提示) |
| D5 | 编辑器能力 | **全功能 bpmn-js Modeler + flowable 流程全属性**(功能不缺失、新特性支持) |
| D6 | moddle | **完整 activiti 描述符**(保真零丢失 + 全属性可编辑),保留 activiti 命名空间 |
| D7 | id 处理 | **可逆净化**,发布还原原始中文流程 key |
| D8 | 版本/运行实例 | flowable 原生版本隔离,发新版本,运行中实例留旧版,v1 不做实例迁移 |
| D9 | v1 边界 | **BPMN 流程编辑器**,不含 DMN/CMMN/flowable 表单设计器 |
## 待 plan 阶段细化
- moddle 描述符来源:社区 flowable/activiti moddle vs 自建最小完整描述符(需核 activiti 命名空间实际用到的元素/属性全集)。
- 影响摘要里「改了哪些节点」的 diff 算法(节点级语义 diff)。
- 模板库(新建流程的起步模板:单人审批/多级审批/会签)放哪、几个。
- 草稿权限模型(谁能看/改别人的草稿)。