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

210 lines
19 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 审批闭环 — 完整实施计划(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)