Files
eip4-platform/docs/plans/2026-06-25-审批闭环-实施计划.md
zhengwr 4f9e4abfc2 feat(approval): 审批闭环 P0/流程图/会签 — 协办转阅+BPMN图+scriptUser会签
承接 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>
2026-06-26 08:09:12 +08:00

19 KiB
Raw Blame History

审批闭环 — 完整实施计划(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-service POST /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-history
  • trace / traceByBusiness(轨迹)已用于 ApprovalDrawer。

❌ 完全缺失

  1. 动作类型:协办/加签 assist、转阅/抄送 circulated —— ApprovalController.java:227 直接 badRequest。会签(多实例并行 + 结果聚合)无任何处理。
  2. BPMN 流程图查看 —— 现仅文本轨迹,无图形化高亮当前节点。
  3. 流程定义 Modeler(B3) —— 完全未起步。
  4. 「我发起的流程」页 / 流程监控页 —— web 无对应 page(仅 TodoPage);撤回/结束按钮无 UI。
  5. 审批待办组件 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. 红线与约束(贯穿全程)

  1. 不碰 view_template.xml / 153 bespoke;审批是框架级通用能力。
  2. 破坏性引擎动作(撤回/结束/加签/写流)只对 dev 构造数据跑实际 mutation,真实迁移数据需用户显式授权。
  3. servicename 服务器侧按 buttonId 重解析,不信前端直传(沿用 ApprovalController.runActionServiceIfAny 既有口径,防注入)。
  4. CHAR(36) 补白 / 候选人补白对齐既有 handler(TrimmingCandidateUsersHandler、EngineContextBinder 归一化),避免身份不匹配。
  5. 不自我批准:实现后走 code-reviewer + 真库/dev e2e 验证,作者与评审分离。
  6. 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;gateway FlowableClient.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 与实现对齐。
  • 单测: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 新 ProcessDiagramController GET /process/{pi}/diagram(返 bpmnXml + activeActivityIds + finishedActivityIds,只读,运行/历史双路取 procDefId);gateway FlowableClient.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 聚合) + multiInstanceUsersHandler bean 已移植并在 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)