在已有 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>
9.5 KiB
在线流程定义 Modeler — 设计(2026-06-26)
在 EIP4 已有 bpmn-js 流程图查看器之上,扩成可编辑的 BPMN 流程设计器:老审批流程能在线编辑修改、新审批流程能在线创建,flowable 流程相关特性全支持,叠加 EIP4 专有语义(办理人/会签/表单绑定)。
经 brainstorming 逐项拍定(本文末「决策记录」)。承接审批闭环:2026-06-25-审批闭环-实施计划、流程图查看(main
0ee919b)。
0. 目标与成功标准(用户拍定)
- 老流程能正常编辑修改(改造 eip4flow 里 1512 个真实迁移流程)。
- 新功能流程能正常创建(从空白/模板新建并部署)。
- 功能不缺失:全 BPMN/flowable 元素可编可配(各类任务/网关/事件/子流程/边界事件/定时器/信号/错误/补偿…)。
- 支持 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. 数据流
- 新建:空白/模板 → 编辑 → 存草稿(act_re_model)。
- 改存量:打开 procDef →
/source灌成草稿 → 编辑 → 存草稿。 - 发布:草稿 XML → 同人确认弹窗(影响摘要)→ 校验门 →
/deploy→ 新版本。
4. 属性面板:标准全套 + EIP4 定制叠加
标准面板(bpmn-js-properties-panel):出全部 flowable 流程属性——节点名/文档、网关条件、多实例、监听器、超时、异步、事件定义等 → 满足「功能不缺失 / flowable 特性」。
EIP4 定制控件(叠加的自定义分组):
- 办理人:读节点
activiti:candidateUsers="${candidateUsersHandler.getCandidateUsers(execution,'<JSON>')}"→ 解析内嵌 JSON → 友好编辑(角色/部门/前序处理人/scriptUser 多项,对齐已移植的UserProperty结构)→ 回写表达式。前后端同源复用 CandidateUsersHandler 配置格式。 - 会签:开关 →
multiInstanceLoopCharacteristics(并行/顺序)+ collection=${multiInstanceUsersHandler.getUsers(execution,'<JSON>')}+ 完成规则(全票nrOfCompletedInstances/nrOfInstances==1/ 过半 / 指定数)。人员来源复用办理人控件。 - 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}/deployJWT role 校验(控制器层拦),非超管 403。 - 同人确认:前端发布弹窗显影响摘要(流程 key、当前版本号、运行中实例数、改了哪些节点的办理人/会签)→ 确认才部署。
- 校验门:部署前服务端跑 flowable 部署校验 + EIP4 校验(办理人表达式可解析 / formKey 命中 view_wftemplate / 会签完成条件合法)→ 不过不部署。
- 审计:每次部署记一条(谁 / 何时 / model→deploymentId / 新版本号)。
- 不分离作者/审批(v1 取舍;作者-审批分离属 v2 增强)。
错误处理:草稿损坏/解析失败 → 422 不部署;校验失败 → 返回具体节点错误;权限不足 → 403。
8. 测试策略
- moddle 保真:载真实流程 → 不改 → 导出 → XML 语义 diff 零丢失(activiti 扩展/会签/办理人表达式)。
- 控件双向:办理人 JSON ↔ 表达式、会签完成条件生成、formKey picker。
- id 可逆净化:净化→还原回原 key、新节点 ASCII id 保留、映射稳定。
- 后端:model CRUD + deploy(校验门/权限门/审计)单测。
- 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)。
- 模板库(新建流程的起步模板:单人审批/多级审批/会签)放哪、几个。
- 草稿权限模型(谁能看/改别人的草稿)。