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

10 KiB
Raw Blame History

✅ 已完成·归档候选(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 结构(实测样例):
    <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):
    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。