# 审批闭环 — 完整实施计划(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)