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

9.5 KiB
Raw Blame History

在线流程定义 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)。
  • 模板库(新建流程的起步模板:单人审批/多级审批/会签)放哪、几个。
  • 草稿权限模型(谁能看/改别人的草稿)。