Files
eip4-platform/docs/plans/2026-06-16-WfTemplate驱动审批界面-完整实现方案.md
zhengwr 624ffe8a15 docs: 06-21 进度文档对齐 + P0/P1 实施记录
- 新建 项目进度与路线-总览-2026-06-21(取代06-17版),刷新A/B矩阵+增量交付+下一步+§9实施记录
- README 索引刷新到06-21;旧总览+14份过时/已完成文档加状态横幅;落地路线图回写里程碑

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-21 13:56:14 +08:00

123 lines
10 KiB
Markdown
Raw 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-21)**:Phase 0-4 全部实现 + live 验收。仍可作 WfTemplate 驱动审批机制参考;可后续 `git mv` 入 `docs/归档/`。
# WfTemplate 驱动审批界面 — 完整实现方案
日期:2026-06-16
状态:**已实现 + live 验收(2026-06-16)**。Phase 0/1/2/3/4 全做完,8093/8089 已跑新 jar。
- Phase0 实测修正:运行任务 form_key 仅 0.6%,靠 (procDefId,taskDefKey) 历史回补 99.98%(新增 `FormKeyResolver`);
实际用到的 286 模板均无内联 `<fields>`,业务表单走 pageid/businessTable→sys_page_schema(无需 fields→amis 转换)。
- 增量未做:load 脚本/action servicename 执行未接、assist/circulated 返 400、业务表单 ~79% 降级摘要(详见 memory `eip4-wftemplate-driven-approval`)。
触发:用户指出"审批按钮应由流程模板定义、动态加载,不该写死;流程模板还定义了脚本是否可用",以及更早"待办审批看不到业务表达就审批不合理"。三点同源。
---
## 一、根因(一句话)
新系统的待办/审批界面**把按钮、脚本、业务表单全写死/丢弃了,完全没用迁移过来的 1016 个 `WfTemplate`(审批流转模板)**。老系统的整个审批界面是由 WfTemplate 数据驱动的。三个问题(看不到业务表单 / 按钮写死 / 脚本丢失)是**同一个根**。
---
## 二、已查证的数据事实(实现依据,勿重复推翻)
### WfTemplate 存储与结构
- 表 **`view_wftemplate`**(库 eip4dev,schema eip3),**1016 行**已迁移。列:`view_wftemplate_id, xml, isactive, version, create*/update*`。
- 服务 `WfTemplateServiceImpl.saveOrUpdate → pojoCRUDService.update("VIEW_WFTEMPLATE")`。
- xml 结构(实测样例):
```xml
<form>
<load><method/></load> <!-- 页面加载脚本(脚本是否可用) -->
<toolbar showsend="false">
<action id="…" label="同意" type="approve"><method servicename=""/></action>
<action id="…" label="拒绝" type="reject"><method servicename=""/></action>
<action id="…" label="退回" type="reback"><method servicename=""/></action>
</toolbar> <!-- 审批按钮:按节点配置 -->
<fields>…</fields> <!-- 审批视图:单据业务表单字段 -->
</form>
```
### action(按钮)词表 — 实测全量分布
- **type**:approve(1016) / reback(972 退回) / reject(971 拒绝) / agent(2) / circulated(2 转阅) / assist(2 协办)
- **label**(高度定制,证明不能写死):退回(971)/拒绝(970)/同意(966) + 确认登记/整改完成/确认/接收/申请封闭/同意2/确认施工方案/转阅/确认封闭/转办/确认交底/意见填写完成/协办/提交审批/登记续签/保存合同及岗位信息/提交方案论证 …
- **375/1016** 的 action 带 `servicename`(自定义服务);**369/1016** 有 `<load>` 脚本;**1008/1016** 的 `<fields>` 非空(业务表单视图)。
### 任务 → WfTemplate 映射(关键,已坐实)
- **flowable 任务 `form_key_` = `view_wftemplate_id`**。eip4flow.`act_hi_taskinst` 56905 任务,**56900 有 form_key**;样例 form_key 在 eip4dev.view_wftemplate 命中=1。
- 老系统取法(`HisTaskDetailPage`/`TaskDetailPage`):
```java
formKey = FormService.getTaskFormKey(procDefId, taskDefinitionKey); // 任务级
if (empty) formKey = FormService.getStartFormKey(procDefId); // 流程级回退
pojo = wfTemplateService.getWfTemplate(formKey); // 取 WfTemplate
```
- 业务记录:任务 `businessKey`(=记录PK) + `businessTable` → `/api/entity/{table}/{businessKey}`。
---
## 三、现状代码位置(改动起点)
| 层 | 文件 | 现状 |
|---|---|---|
| 前端按钮(写死) | `eip4-web/src/components/ApprovalBar.tsx` | 同意/驳回/转办 写死,`handleComplete('agree'\|'reject')`+delegateTask |
| 前端待办页 | `eip4-web/src/pages/TodoPage.tsx` | 待办/已办 tab + 列表 + 内联 ApprovalBar;缺业务表单区 |
| 前端 api | `eip4-web/src/api/approval.ts`(completeTask/delegateTask/fetchTrace)、`todo.ts`(TodoItem 带 businessKey/businessTable) | — |
| 后端网关 | `platform-flow-gateway/.../web/TodoController.java`(`/api/todo`,`/api/task/{id}/complete`,`/delegate`,trace) + `FlowableClient.java` | complete/delegate 有;缺 approval-meta、reback、reject 终止 |
| 后端引擎 | `flowable-service/.../api/FlowController.java`、`TaskDto.java`(无 formKey 字段→要加) | — |
| 表→表单解析 | `platform-converter/.../TemplateToAmisConverter.java:resolveEditFormTemplateId`(911-975,实体级回退) | 逻辑可参考,需抽成运行时端点 |
| 老语义参考 | `framework/com.dsasp.client.viewframework.template.wf.WfTemplateComponent`(getActions/getActionMethod/拒绝终止流程)、`framework/com.dsasp.server.wf/.../ProcessCoreServiceImpl`(action 语义) | 还原依据 |
---
## 四、分阶段实现
### Phase 0 — 补充勘查(新会话先做,~0.5d)
1. dump 几个 `<fields>` 非空的 WfTemplate,看字段定义格式(和 view_page/view_template 的 `<field>` 是否同构 → 能否复用现有 amis field 渲染,还是要单独解析)。
2. 老 `WfTemplateComponent.getActionMethod(id)` + `ProcessCoreServiceImpl` 里 approve/reject/reback/agent/circulated/assist 各 type 的真实语义(尤其 reback 退回到哪、reject 是否终止+状态码)。
3. `<load><method>` 脚本格式 + 在新系统执行路径(保真层服务流 `/api/flow/{svc}`?JUEL?)。
4. eip4flow.`act_ru_task`(运行中任务,非历史)的 form_key 覆盖率——决定"新提交走 EIP4_DEFAULT_APPROVAL 通用流、无 form_key"时的降级策略。
### Phase 1 — 后端:审批元数据端点(WfTemplate 驱动)
- `TaskDto` 加 `formKey` 字段(flowable `task.getFormKey()`)。
- 新端点 **8093 `GET /api/task/{taskId}/approval-meta`**(TodoController + FlowableClient):
1. 取 task.form_key_(= wftemplate id);空 → `FormService.getTaskFormKey(procDef, taskDefKey)` → `getStartFormKey(procDef)` 回退。
2. 查 `view_wftemplate` by id,解析 `<toolbar showsend><action id label type><method servicename>`、`<load><method>`。
3. 返回 `{buttons:[{id,label,type,servicename}], loadScript, showsend, businessKey, businessTable, formTemplateId}`。
4. 无 form_key/无 wftemplate → 兜底默认按钮(同意 approve / 驳回 reject)。
- 表→编辑表单模板:把 `resolveEditFormTemplateId` 实体级逻辑抽成运行时 `GET /api/form/by-table/{table}`(表名→SYS_ENTITY→type=7/view_page editform),或把 `formTemplateId` 直接 enrich 进 approval-meta。
### Phase 2 — 后端:action type → flowable 操作
统一收口新端点 **`POST /api/task/{id}/action`**(body: `{actionType, comment, targetUserId?}`),内部按 type 分派:
- **approve(同意)** → `complete(approveResult=approve)` + StatusWriteback(已有;结束→3,未结束→2)。
- **reject(拒绝)** → 终止流程 `runtimeService.deleteProcessInstance` + 回写 SYS_DATASTATUS(老语义"拒绝终止",状态码 Phase0 确认 4驳回/6作废)。
- **reback(退回)** → 退回上一节点/发起人:flowable `runtimeService.createChangeActivityStateBuilder().moveExecutionsToSingleActivityId(...)`;`ProcessCoreServiceBridge` 补 `backProcess`(MVP 缺口)。
- **agent/assist/circulated(转办/协办/转阅)** → delegate / 加签(addCandidateUser) / 抄送。
- **带 servicename 的 action** → 调保真层 `/api/flow/{servicename}`。
### Phase 3 — 前端:数据驱动审批详情
- `ApprovalBar` 改:挂载时 `fetch /api/task/{taskId}/approval-meta` → **按 buttons 动态渲染**(label/type/颜色由 type 映射),点击调 `/api/task/{id}/action`。
- 审批详情布局(建议**抽屉**,用户上一轮倾向待定:抽屉/全页/行内三选一):
- 上半 = **业务单据表单(只读)**:amis `service`(`schemaApi:/api/page/schema/{formTemplateId}` + `api:/api/entity/{table}/{businessKey}` + `static:true`)。
- 下半 = 动态按钮条 + 审批意见 + 流程轨迹(复用现 ApprovalBar 的意见/轨迹)。
- `<fields>` 非空时优先用 WfTemplate 定义的字段视图(Phase0 定格式后决定复用 view_page 还是直接 amis form)。
- 执行 `loadScript`(若有)。
- eip4-web 是 vite 热更,前端改即时生效(无需重启)。
### Phase 4 — 部署 + 验收
- 后端重建重启:`JAVA_HOME=…@21 mvn -o package -pl platform-app,flowable-service -am -DskipTests` → `scripts/run-dev.sh both`。
- 验收(live):不同节点任务办理 → 按钮随 WfTemplate 变(同意/拒绝/退回 + 定制按钮如"确认施工方案");业务单据表单可见可读;退回/拒绝语义正确(退回回上一步、拒绝终止);轨迹正常。
---
## 五、风险 / 边界
- **新提交走通用流(EIP4_DEFAULT_APPROVAL)的任务可能无 form_key** → 数据驱动降级为默认按钮。完整数据驱动需客户 BPMN 部署(userTask formKey 指向 WfTemplate),属切流前置(见 153/审批桥接线)。
- **reback/reject 的 flowable 实现**(changeActivityState/deleteProcessInstance)与老 activiti API 有差异,要实测;ProcessCoreServiceBridge 当前是 MVP(仅 startWorkflow)。
- `<fields>` 字段格式 Phase0 必须确认能否复用现有渲染,否则要写 WfTemplate fields → amis 的小转换。
- **不碰 view_template.xml(冻结)、不动 153 bespoke**。本特性是审批框架级通用能力(覆盖所有审批流),非逐页 bespoke,价值高。
- 与已完成的审批A(提交按钮状态)/审批B(查看审批 trace)/全量部署 不冲突;本特性替换的是待办"办理"的写死按钮 + 补业务表单。
---
## 六、本会话已完成的审批相关(上下文)
- 审批A:提交审批按钮 STATUS-aware disabledOn(处理中禁用)✅ 上线。
- 审批B:列表「查看审批」按钮 + `/api/flow/business/{bk}/trace`(businessKey→flowable 历史轨迹)✅ 上线(日期 valueFormat:x 已修)。老新闻"通过"记录因老 activiti 历史未迁进 flowable 而空,属数据缺口(用户认可不纠结)。
- 待办工作台(TodoPage/ApprovalBar)实测**可用**:列表+办理+同意(推进流程)+驳回/转办+轨迹——但按钮写死、无业务表单、无 WfTemplate 驱动(= 本方案要解决的)。
- 详见 memory `eip4-generic-vs-custom-templates-plan`、`eip4-wftemplate-driven-approval`。