docs: 统一项目文档进 eip4-platform/docs + 新增进度路线总览
Some checks failed
ci / build-test-parity (push) Has been cancelled
Some checks failed
ci / build-test-parity (push) Has been cancelled
- 从工作区根 docs/(非 git,未版本化)合并全部文档进版本控制,消除文档两头分裂
- 新增 README(状态总览+模块完成度+全文档索引)、项目进度与路线-总览-2026-06-17(A兼容/B新功能+关键路径+待拍板决策)
- 被取代的冲突状态/审计快照归入 归档/;对最易误导的两份("16视图已交付"实现交付报告、06-13架构快照)加"已归档"横幅
- 现行权威:engineclass移植backlog(46视图) + 用户管理Delta移植(方法论/交接) + 组件设计体系 + 通用模板收口 + 客户沟通
- 诚实口径:纵向模块仅用户管理 parity,横向引擎地基较全,余 153 定制视图(47 framework+106 业务)多为通用页已产·delta 未移植
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
120
docs/plans/2026-06-16-WfTemplate驱动审批界面-完整实现方案.md
Normal file
120
docs/plans/2026-06-16-WfTemplate驱动审批界面-完整实现方案.md
Normal file
@@ -0,0 +1,120 @@
|
||||
# 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`。
|
||||
Reference in New Issue
Block a user