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>
This commit is contained in:
134
docs/plans/2026-06-26-在线流程Modeler-design.md
Normal file
134
docs/plans/2026-06-26-在线流程Modeler-design.md
Normal file
@@ -0,0 +1,134 @@
|
||||
# 在线流程定义 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)。
|
||||
- 模板库(新建流程的起步模板:单人审批/多级审批/会签)放哪、几个。
|
||||
- 草稿权限模型(谁能看/改别人的草稿)。
|
||||
Reference in New Issue
Block a user