承接 WfTemplate 数据驱动审批主链路(approve/reject/reback/agent 已 live),补齐缺口:
P0 协办(assist)/转阅(circulated):
- flowable-service 新增 POST /tasks/{id}/assist、/circulate(对齐老 ProcessCoreServiceImpl
createSubTask/createNewTask:每人建独立任务,父任务记意见,不阻断主流程)
- gateway FlowableClient.assist/circulate + ApprovalController 把 assist/circulated 从 400 改真实分派
- 前端 ApprovalDrawer 多选人弹窗 MultiUserForm
- 对抗审查修复:独立任务沿 parentTaskId 回溯父任务取 businessKey/formKey(否则协办/转阅人
看不到业务单据,且 processInstanceId(null) 崩 500);assist 父任务 404 守卫;MAX_FANOUT=50;
@Transactional;转阅改 setFormKey 而非 description
P1 BPMN 流程图查看:
- flowable-service 新 ProcessDiagramController GET /process/{pi}/diagram
(bpmnXml + 当前/历史活动节点,运行/历史双路取 procDefId,只读)
- gateway FlowableClient.diagram + TodoController 转发
- 前端 bpmn-js 渲染(中文走浏览器字体,当前节点绿/已走过灰),ApprovalDrawer 按需展开
P3 会签(BPMN 多实例):移植 CandidateUsersHandler 的 scriptUser(JUEL)候选人解析分支
(原"精简边界"WARN 降级,致招投标/总包合同/施工技术交底等用 ${APPLYUSERS} 的会签节点被跳过):
单变量直读流程变量 + 复杂表达式回退 flowable 表达式管理器 + 结果归一为去重 userId 列表
测试:flowable-service 56 + gateway 全模块 全绿;前端 tsc 干净 + vitest 83/83 + build。
live e2e(真 eip4flow):协办/转阅各 count:1 且子任务回溯出 businessKey/进目标用户待办;
流程图真 DI 实例渲染;会签起 3 并行任务/全票聚合推进。
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
19 KiB
审批闭环 — 完整实施计划(2026-06-25)
目标:把 EIP4 审批从「单人串行主链路已 live」推进到「动作类型齐全 + 流程可视化 + 流程监控 + 端到端真实流转」的生产可用闭环。
现状权威依据:
ApprovalController.java(gateway)/FlowController.java、CandidateController.java(flowable-service)/FlowableClient.java(gateway client)/ApprovalDrawer.tsx、TodoPage.tsx(web)实读核实;进度矩阵见docs/项目进度与路线-总览-2026-06-21.md§A2/B3/B4。
0. 现状基线(核实于 2026-06-25)
✅ 已实现并 live(WfTemplate 数据驱动审批主链路)
- 动作:
approve(complete + 回写 SYS_DATASTATUS 3/2)、reject(终止 + 回写 4)、reback(退回发起 + 回写 5)、agent(委托)。 - 界面:
ApprovalDrawer(只读业务表单 + 流程轨迹时间线 + 动态按钮 + 审批意见);业务表单走统一 sys_page_schema editform 解析;load 脚本保真层执行(4s 超时守护);action servicename 服务器侧按 buttonId 重解析后执行。 - 入口:228 个 sys_page_schema 含
openApprovalDrawer按钮接线(mock e2e 1/1)。 - 提交审批桥:
ProcessCoreServiceBridge(startWorkflow)已实证起真实 flowable 实例。
🟡 引擎/Client 层已具备、仅缺 gateway 动作接线 + UI 按钮(关键发现:比想象中近)
这些不需要动引擎,引擎与
FlowableClient方法都已存在并测过:
FlowableClient.withdraw(pi, comment)← flowable-servicePOST /api/flow/process/{pi}/withdraw(发起人撤回)FlowableClient.terminateProcessInstance(pi, comment)←POST /process/{pi}/terminate(强制结束)- flowable-service
POST /process/{pi}/suspend//activate(挂起/激活,client 侧尚无封装方法) FlowableClient.started(...)←GET /process/started(我发起的流程列表)FlowableClient.deleteHistoricProcessInstance(pi)←POST /process/{pi}/delete-historytrace/traceByBusiness(轨迹)已用于 ApprovalDrawer。
❌ 完全缺失
- 动作类型:协办/加签
assist、转阅/抄送circulated——ApprovalController.java:227直接badRequest。会签(多实例并行 + 结果聚合)无任何处理。 - BPMN 流程图查看 —— 现仅文本轨迹,无图形化高亮当前节点。
- 流程定义 Modeler(B3) —— 完全未起步。
- 「我发起的流程」页 / 流程监控页 —— web 无对应 page(仅
TodoPage);撤回/结束按钮无 UI。 - 审批待办组件 B4 —— UI/UE 组件骨架未补完。
🔒 外部阻塞(非代码能力问题)
- 客户真实 BPMN 部署:新提交走通用流
EIP4_DEFAULT_APPROVAL,无form_key→ 降级默认按钮。全数据驱动 + 候选人计算需客户部署真实 BPMN(form_key指 WfTemplate)。dev act 流程库不可达。 reject/reback/action-servicename 写流:仅 wired + 单测,未对真实迁移数据跑 mutation(数据安全自限)。
1. 范围分层与优先级
| 层 | 内容 | 外部依赖 | 工作量 | 价值 |
|---|---|---|---|---|
| P0(立即可做) | 协办/加签 assist、转阅/抄送 circulated 动作落地 |
无 | 中 | 高(补齐审批语义完整性) |
| P1(接线打磨) | 流程监控按钮(撤回/结束/挂起)接线 + 「我发起的流程」页 | 无 | 小-中 | 高(引擎已就绪,最后一公里) |
| P1(可视化) | BPMN 流程图查看(bpmn-js 高亮当前节点) | 无(用已部署 bpmn) | 中 | 高(审批可视化刚需) |
| P2(验证闭环) | 真实流转 / 候选人计算 / 写流对真实记录的端到端验收 | 客户 BPMN | 中 | 高(但卡外部) |
| P3(大工程) | 会签(多实例聚合)+ 流程定义 Modeler(B3) | 部分卡 S1 | 大 | 中(按客户诉求排期) |
建议交付顺序:P0 → P1 监控接线 → P1 BPMN 图 → P2(客户 BPMN 到位后)→ P3。P0/P1 共约 4 个可独立交付的增量,互不阻塞,均不依赖外部。
2. 分阶段任务
阶段 A — 协办/加签 assist(P0)
语义对账(先做,不可跳过):核对老系统 TaskProcessServiceImpl 中 assist 的真实行为。预期两种之一:
- (a) 加签:当前任务保留,给目标人新增一个并行/串行待办(
addCandidateUser或动态加 task),目标人办完回到原审批人; - (b) 协办:把当前任务的 candidate 增加目标人,任一人可办。
WfTemplate 数据里 assist 仅 2 例 —— 务必先 SQL 取这 2 例的 xml + servicename,确认是 (a) 还是 (b),不要凭猜实现。
改动:
- flowable-service
FlowController:新增POST /api/flow/tasks/{taskId}/assist(入参 targetUserId、comment)。用TaskService.addCandidateUser或runtimeService动态加签,按语义对账结果实现。CHAR(36) 补白对齐既有TrimmingCandidateUsersHandler口径。 FlowableClient:加assist(taskId, targetUserId, comment)。ApprovalController.action:case "assist"→ 新assist(taskId, req)方法(替换当前 400)。- 单测:FlowController assist 1 + ApprovalController dispatch 1。
验收:真实/构造任务加签后,目标人 todo 出现该任务;办理后流程状态正确。 风险:加签的「办完回到谁」依赖 BPMN 结构;若客户 BPMN 不可达,先用 dev 构造流程验证机制,标注真实流待客户库。
阶段 B — 转阅/抄送 circulated(P0)
语义对账:circulated 仅 2 例。老系统转阅通常是只读知会(不阻塞流程):给目标人发一条「抄送待阅」记录,目标人可见单据但无审批动作。核实是否落 act_ru_identitylink(type=participant)或独立抄送表。
改动:
- flowable-service
FlowController:POST /api/flow/tasks/{taskId}/circulate(targetUserIds[]、comment)。实现 = 加 participant identityLink + 写抄送记录(若老系统有抄送表,迁移对齐;否则用 identityLink + 历史评论)。 FlowableClient:circulate(taskId, targetUserIds, comment)。ApprovalController.action:case "circulated"→circulate(...)。- 「抄送给我的」列表:复用
TodoController加GET /api/tasks/circulated?user=(查 participant identityLink)。前端可暂缓,先保证动作不报 400。 - 单测:circulate 1 + dispatch 1。
验收:转阅后目标人能在「抄送给我」看到只读单据;原审批流不受影响继续。 风险:抄送列表入口是新页面,P0 只交付动作 + 后端列表端点,前端页面归 B4。
阶段 C — 流程监控按钮接线(P1)✅ 实施时核实:已完成(无需重做)
2026-06-25 实施勘探更正:本阶段在 06-21 矩阵里被标为「缺监控按钮」,实测后端 + amis 页全部已存在(进度文档 framework P2 那批
57c3412…d218c2b已交付,当时计划按旧矩阵误判):
GET /api/workflow/process/started-amis(我的发起)+monitor-amis(流程监控)列表端点 —— 各被 1 个sys_page_schema页引用。- 我的发起页(
0db4af06…)含撤回按钮 →POST /api/workflow/process/{pi}/withdraw(回写 SYS_DATASTATUS=5)。- 流程监控页(
9f3b5a8b…)含强制结束按钮 →/terminate(回写=6 作废)+ 高级处理脚本/advanced-script(带 RCE 守卫,仅非生产 profile)+/delete-history。- 语义正确:发起人撤回自己的、管理员监控结束别人的。
结论:阶段 C 无需实现。残留仅 suspend/activate(挂起/激活)未在 gateway 暴露——价值低,暂不做;监控页缺「流程图/轨迹」按钮归入阶段 D。
原计划(引擎 + client 已全有,只缺 gateway 动作端点 + UI)—— 实际 gateway 端点也已就绪。
改动:
FlowableClient:补suspend(pi)/activate(pi)(其余 withdraw/terminate/started 已有)。- gateway 新
ProcessMonitorController(或并入 ApprovalController):POST /api/process/{pi}/withdraw(发起人撤回,回写 SYS_DATASTATUS)POST /api/process/{pi}/terminate(强制结束,超管/管理员权限校验,回写状态)POST /api/process/{pi}/suspend//activate- 权限:撤回限发起人本人;结束/挂起限管理员角色(复用 JWT 角色)。
- web 新
StartedProcessPage.tsx(「我发起的流程」):列表走started,行内「撤回」按钮 + 流程轨迹抽屉(复用 ApprovalDrawer 只读模式 + historyMeta 端点,已存在)。 - 单测:ProcessMonitorController 4(每动作 1)+ 权限拒绝 1;前端 vitest 列表渲染 1。
验收:发起人撤回未审任务 → 状态回写 + todo 消失;管理员强制结束运行流程 → 实例 ended。 风险:撤回/结束对真实客户数据是破坏性操作,只对 dev 构造流程跑实际 mutation,真实库标注待客户授权。
阶段 D — BPMN 流程图查看(P1)
方案:bpmn-js 前端渲染 + 后端给 XML & 当前活动节点(业界标准,比服务端出图灵活,可高亮 + 缩放)。
改动:
- flowable-service:
GET /api/flow/process/{pi}/bpmn-xml→ 用RepositoryService.getProcessModel(procDefId)返 BPMN XML 字符串;GET /api/flow/process/{pi}/active-activities→runtimeService.getActiveActivityIds(pi)(高亮用,已有 RuntimeService)。历史流程取HistoricActivityInstance标记走过的节点。 FlowableClient:bpmnXml(pi)/activeActivities(pi)。- gateway:
GET /api/process/{pi}/diagram(聚合 xml + active + history 节点)。 - web:引入
bpmn-js(NavigatedViewer),新ProcessDiagram.tsx,在 ApprovalDrawer 加「流程图」Tab;高亮当前节点(绿)、走过节点(灰)。 - 单测:diagram 端点 2;前端组件渲染 smoke 1。
验收:打开任一运行中流程,流程图正确渲染并高亮当前停留节点。
风险:迁移的是 activiti5 流程定义,bpmn-js 需 BPMN 2.0 XML;若部分老流程是 activiti5 私有格式,需确认 getProcessModel 返的是标准 BPMN 2.0(flowable 部署后通常是)。先用一条已部署流程验证格式兼容性。
阶段 E — 端到端真实流转验收(P2,卡客户 BPMN)
前置①(外部):客户提供并部署真实 BPMN(form_key 指 WfTemplate)。到位后:
- 真实流转:提交 → 候选人计算(
CandidateController+OrgDirectory已就绪)→ 多级审批 → approve/reject/reback 实际推进。 - 写流:对测试租户/沙箱记录(非生产迁移数据)跑 reject/reback/action-servicename 实际 mutation,验证回写与服务流副作用。
- 候选人对账:用
CandidateController对真实组织库批量核对解析结果(P3 报告口径)。
验收:一条客户真实审批流从提交到归档全程在 EIP4 走通,状态/候选人/表单全部正确。 阻塞:无客户 BPMN 则只能 dev 构造流程验机制,标注「机制已验,真实流待客户库」。
阶段 F — 会签 + 流程定义 Modeler(P3,大工程,按客户诉求排期)
- 会签:BPMN 多实例(multi-instance)任务,多人并行/串行审批,按比例/全票聚合结果。需引擎多实例支持 + 聚合变量 + UI 显示「3/5 已审批」。先确认客户是否真有会签节点(WfTemplate action type 分布里无独立会签 type,可能藏在 BPMN 结构,需核实)。
- 流程定义 Modeler(B3):bpmn-js + bpmn-js-properties-panel 在线编辑 BPMN,存 flowable 部署。卡 S1 拍板(是否自研 vs 用 flowable-modeler 嵌入)。工作量最大,建议独立 design。
3. 红线与约束(贯穿全程)
- 不碰 view_template.xml / 153 bespoke;审批是框架级通用能力。
- 破坏性引擎动作(撤回/结束/加签/写流)只对 dev 构造数据跑实际 mutation,真实迁移数据需用户显式授权。
- servicename 服务器侧按 buttonId 重解析,不信前端直传(沿用
ApprovalController.runActionServiceIfAny既有口径,防注入)。 - CHAR(36) 补白 / 候选人补白对齐既有 handler(
TrimmingCandidateUsersHandler、EngineContextBinder归一化),避免身份不匹配。 - 不自我批准:实现后走
code-reviewer+ 真库/dev e2e 验证,作者与评审分离。 - e2e 端口坑:五环 jar = 8094(
playwright.fivering.config.ts),标准 dev = 8093;psql 查业务表设PGOPTIONS='-c search_path=eip3'。
4. 外部依赖与待拍板
- 【外部】客户真实 BPMN 部署 → 阻塞阶段 E 全部、阶段 A/B 的真实流验证。
- 【S1 拍板】流程定义 Modeler 自研 vs 嵌入 flowable-modeler(阶段 F)。
- 【待核实】会签是否为客户真实诉求(数据里无独立 type,先核实再排期)。
5. 执行进度(2026-06-25/26 本会话,按 P0→P3 顺序)
波1 ✅ 已实现 + 对抗审查收口 + 单测绿 + live 验证通过:阶段 A(assist 协办)+ 阶段 B(circulated 转阅)
- 语义对账(红线)已做:SQL 取 view_wftemplate 那 2+2 例(全空 servicename)+ 读老
ProcessCoreServiceImpl.createSubTask/createNewTask坐实语义(协办=建独立子任务、转阅=建只读知会任务)。 - 后端 flowable-service
POST /tasks/{id}/assist+/circulate;gatewayFlowableClient.assist/circulate+ApprovalController分派把 400 改真实;前端ApprovalDrawer多选人弹窗MultiUserForm。 - 对抗代码审查(code-reviewer)揪出 1 HIGH + 3 MEDIUM,已修:
- 【HIGH 已修+live证】协办/转阅是独立任务(无 processInstanceId/formKey),审批渲染原取不到 businessKey/formKey → 协办人/转阅人看不到业务单据。修法=
approvalContext对独立任务沿 parentTaskId 回溯父任务取 businessKey+formKey(兼防processInstanceId(null)崩 500);circulate/assist 子任务setFormKey(父formKey)。 - 【MEDIUM 已修】assist 补父任务 404 守卫(与 circulate 对称);派发
MAX_FANOUT=50上限;assist/circulate 加@Transactional整批原子。 - 【LOW】转阅改
setFormKey而非 description(FormKeyResolver 直接命中);javadoc 与实现对齐。
- 【HIGH 已修+live证】协办/转阅是独立任务(无 processInstanceId/formKey),审批渲染原取不到 businessKey/formKey → 协办人/转阅人看不到业务单据。修法=
- 单测:flowable-service FlowControllerTest 21 + ProcessDiagramControllerTest 3 全绿;gateway ApprovalControllerActionTest 5 全绿;前端 tsc 干净 + vitest 83/83。
- live e2e(8089+8093 新 jar,真引擎):① POST assist/circulated 各返
count:1(不再 400);② 子任务 approval-context 回溯出父流程 businessKey=probe-bk-1 + processInstanceId(HIGH 修复实证);③ 子任务进目标用户待办(assignee 匹配无补白问题,reviewer Open Question 实证排除);④ 测试产物已清理。
波2 ✅ 核实即完成:阶段 C(流程监控)
后端 + amis 页早已存在(见上文阶段 C 更正),无需重做。
波3 ✅ 已实现 + 单测绿 + live 验证通过:阶段 D(BPMN 流程图)
- 后端 flowable-service 新
ProcessDiagramControllerGET /process/{pi}/diagram(返 bpmnXml + activeActivityIds + finishedActivityIds,只读,运行/历史双路取 procDefId);gatewayFlowableClient.diagram+TodoController GET /api/workflow/process/{pi}/diagram转发。 - 前端新
src/api/diagram.ts+src/components/ProcessDiagram.tsx(bpmn-js NavigatedViewer,中文节点走浏览器字体,当前节点绿/已走过灰高亮);ApprovalDrawer加「查看流程图」按需展开段。bpmn-js 依赖已装,build ✓(5104 模块)。 - 单测 ProcessDiagramControllerTest 3 绿。live e2e:真实带 DI 的迁移实例(PI=511732)返
bpmnXml=7586 chars / 含 BPMNDiagram 布局 / 当前节点 sid-… / 已走过 4 节点→ bpmn-js 可渲染。
阶段 E(P2)⏸ 外部阻塞
真实流转/候选人/写流端到端 —— 需客户 BPMN(dev EIP4_DEFAULT_APPROVAL 通用流无 form_key)。注:eip4flow 库有 1512 流程定义/9441 实例可读,故只读类(流程图/轨迹)已能 live;写类真实流转仍待客户 BPMN。
阶段 F(P3)— 会签 ✅ 已实现+live;Modeler ⏸ 待 S1
会签更正(2026-06-26,用户确认是客户真实诉求):先前「阻塞/待核实」判断错误——会签不是 WfTemplate 的按钮 type,而是 BPMN 多实例(multiInstance)节点结构,故按钮 type 分布看不出。核实结果:
- 迁移库 28/1512 流程定义含
multiInstanceLoopCharacteristics;其中 4 个真实业务流程:安全技术交底(集合 type=user)、总包合同交底/招投标工程评审流程/施工技术交底(集合 type=scriptUser)。 - 引擎机制本就全在:flowable 原生多实例(并行任务+
completionCondition聚合) +multiInstanceUsersHandlerbean 已移植并在FlowableEngineConfig注册 + 每个会签人走现有approve。故user类型会签早已能跑。会签从不是外部阻塞。 - 真正缺口:
CandidateUsersHandler的scriptUser(JUEL 脚本)候选人解析分支当初故意没移植("精简边界" WARN 降级,26 处)。3/4 真实会签流程用 scriptUser(${APPLYUSERS}) → 办理人解析返空 → 会签节点被跳过(日志实锤 WARN)。 - 已修复:
CandidateUsersHandler实现 scriptUser 分支 = 单变量${VAR}直读流程变量、复杂表达式回退 flowable 表达式管理器对 execution 求值、结果按 List/数组/逗号分号串/单值归一为去重 userId 列表。单测 8(CandidateUsersScriptUserTest);flowable-service 全量 56 绿无回归。 - live e2e:起「招投标工程评审流程」(APPLYUSERS=3人) → 会签节点生成 3 条并行任务(修复前 0 条被跳过);完成 1/3 不推进(剩 2)、完成 3/3 聚合推进到下一节点(完成条件
nrOfCompletedInstances/nrOfInstances==1全票);测试实例已清理。
剩 Modeler ⏸:流程定义 BPMN 在线 Modeler(B3,自研 vs 嵌入 flowable-modeler)仍卡 S1 拍板。
会签残留(跟踪项,非阻断):① 会签进度显示("已会签 N/M 人")未做,可从多实例执行的 nrOfInstances/nrOfCompletedInstances 取,属 UX 增强;② scriptUser 复杂表达式回退依赖命令上下文,已 try/catch 安全降级;③ 真实 APPLYUSERS 由业务表单/前序步骤设置,本次用 start 变量模拟。
残留(非阻断,跟踪项)
- 协办/转阅目标用户用文本输入(与现有「转办」DelegateForm 同款),无真实用户存在性校验 → 错填 userId 会建不可见任务。与现有转办行为一致,建议后续统一接用户 picker(同时惠及转办)。
- 协办/转阅按钮在 WfTemplate 均无 servicename(已核实),故
runActionServiceIfAny对其为 no-op,安全。
改动文件(全部在 flowable-service + platform-flow-gateway + eip4-web,未触及其他模块;platform-report/legacy-core 的失败测试是它处 WIP/JDK 环境问题,与本次无关):
- 后端:
FlowController.java、Requests.java、ProcessDiagramController.java(新)、FlowableClient.java、ApprovalController.java、GatewayRequests.java、TodoController.java+ 3 测试 - 前端:
approval.ts、ApprovalDrawer.tsx、diagram.ts(新)、ProcessDiagram.tsx(新)、package.json(bpmn-js)