Files

geht 1d0b4c9fbb 增强审批流管理能力，新增审批环节的 stageKey 区分关键环节与过路审批节点，完善钉钉回调日志记录，停用部分 HTTP 回调接口，改由集成方案驱动审批流，优化审批注册中心的查询逻辑。

2026-06-05 19:05:48 +08:00

22 KiB

Raw Blame History

审核集成功能 — 整体方案计划

版本： V1.0
日期： 2026-06-05
定位： 在现有 MES 审批引擎之上，新增审批后业务编排层，实现「哪些单要审、审完自动生成/更新下游单」的可配置化集成。
原则： 审批归审批、编排归编排、复杂逻辑归代码；与 Online 增强模型对齐、与现有 @ApprovalBizAction / Gate 台账兼容。

一、背景与目标
二、总体架构
三、功能模块设计
四、数据模型设计
五、核心引擎设计
六、业务流程
七、前端设计
八、Online 表单集成策略
九、与现有机制的关系
十、分期实施计划
十一、技术规范
十二、风险与应对
十三、验收标准
十四、资源与依赖
十五、首个试点场景
十六、下一步行动

一、背景与目标

1.1 现状

项目已具备较完整的审批底座：

能力	现有实现
审批流设计	`MesXslApprovalFlow` + 前端 `ApprovalDesign`
审批办理	`MesXslApprovalHandleServiceImpl`
业务回调	`IApprovalBizCallback` / `@ApprovalBizAction`
跨通道门禁	`MesXslApprovalGateService` + `MesXslApprovalRecord`
钉钉/OA	Stream 回调 + 流程模板

缺口： 下游单据生成、跨单字段回写仍依赖各模块硬编码 Callback，无法由实施/用户在界面配置。

1.2 建设目标

目标	说明
G1 可配置	配置源单 → 审批策略 → 审后动作，减少重复 Java 开发
G2 可编排	支持 CREATE / UPDATE / CALL_API / CALL_HANDLER 多动作顺序执行
G3 可观测	每次编排有日志、幂等、失败可重试、台账可追踪
G4 可兼容	不破坏现有 Callback；Online 表与 Codegen 表统一接入
G5 可扩展	复杂业务（配方计算、BOM 展开）仍走 Java Handler

1.3 不在本期范围（明确边界）

不替换现有审批流设计器（人怎么审仍用 Flow）
不重做 Online BPM / Flowable 流程引擎
不做通用 ETL / 消息中间件级集成平台
不做前端 JS 编排引擎（审后动作必须服务端执行）

二、总体架构

flowchart TB
    subgraph L1["L1 配置层"]
        R[单据注册中心]
        P[审核策略 Policy]
        I[集成方案 Plan]
        A[集成动作 Action]
    end

    subgraph L2["L2 审批层（已有）"]
        G[ApprovalGate 门禁]
        F[ApprovalFlow 审批流]
        REC[ApprovalRecord 台账]
        H[HandleService 办理引擎]
    end

    subgraph L3["L3 编排层（新建）"]
        O[IntegrationOrchestrator]
        M[FieldMappingEngine]
        E[ActionExecutor 策略池]
        L[IntegrationLog 执行日志]
    end

    subgraph L4["L4 执行通道"]
        SQL[SQL_UPDATE]
        API[CALL_API]
        HD[CALL_HANDLER]
        CR[CREATE/UPDATE Doc]
        ONL[Online Form API]
    end

    R --> P --> G
    P --> I --> A
    G --> F --> H --> REC
    H -->|终态事件| O
    A --> O --> M --> E
    E --> SQL & API & HD & CR
    CR --> ONL
    O --> L

三层职责划分

层	职责	配置主体
L1 配置层	定义单据元数据、审核策略、审后编排	实施/管理员
L2 审批层	谁审、几级审、MES/钉钉通道	已有 Flow 设计器
L3 编排层	审完自动生成/改数/调接口	集成方案设计器

三、功能模块设计

3.1 模块清单

模块	包路径建议	说明
单据注册	`approval.integration.registry`	管理可参与集成的单据元数据
审核策略	`approval.integration.policy`	哪些单、何时必须审、绑哪条流
集成方案	`approval.integration.plan`	审后编排方案（含动作明细）
编排引擎	`approval.integration.orchestrator`	统一调度入口
字段映射	`approval.integration.mapping`	变量解析、映射计算
动作执行器	`approval.integration.executor.*`	各 action_type 实现
执行日志	`approval.integration.log`	审计、重试、幂等
管理 API	`approval.integration.controller`	CRUD + 测试预览 + 手动重试
前端页面	`views/xslmes/approval/integration/`	4 个管理页 + 1 个设计器

3.2 与现有代码的挂接点（最小侵入）

在以下位置增加编排调用（不替换现有逻辑）：

MesXslApprovalHandleServiceImpl
  ├─ 节点通过 → callbackDispatcher.fireNodeApproved()
  │              └─ + integrationOrchestrator.execute(ctx, NODE_APPROVED)
  ├─ 最终通过 → callbackDispatcher.fireApproved()
  │              └─ + integrationOrchestrator.execute(ctx, APPROVED)
  └─ 驳回     → callbackDispatcher.fireRejected()
                 └─ + integrationOrchestrator.execute(ctx, REJECTED)

DingBpmsEventProcessor（钉钉终态）
  └─ finishByExternalInstance 成功后
       └─ + integrationOrchestrator.executeByRecord(record, APPROVED/REJECTED)

执行顺序（同一事务内）：

现有 IApprovalBizCallback（兼容老逻辑）
现有节点 callbackActions（HTTP 调用）
新增集成编排（按 exec_order 顺序）

任一环节抛异常 → 整笔审批动作回滚（与现有 Callback 事务策略一致）。

四、数据模型设计

4.1 表结构（6 张）

① `mes_xsl_biz_doc_registry` — 单据注册

字段	类型	说明
doc_code	varchar(64)	业务编码，如 `formula_spec`
table_name	varchar(128)	物理表名
display_name	varchar(128)	中文名
doc_source	varchar(16)	`online` / `codegen` / `manual`
online_head_id	varchar(32)	Online 表 headId（可空）
title_field	varchar(64)	标题字段
status_field	varchar(64)	状态字段
route_path	varchar(256)	前端路由
is_master	tinyint	是否主表
child_config	json	子表 `[{table,fkField,docCode}]`
field_schema	json	字段缓存（可从 Online/实体同步）
enabled	tinyint	启用

② `mes_xsl_approval_policy` — 审核策略

字段	说明
policy_code / policy_name	策略编码/名称
source_doc_code	源单据
enabled	启用
trigger_event	`manual` / `on_submit` / `on_status_change`
match_condition	条件表达式（Online exp 语法）
approval_channel	`mes` / `dingtalk` / `auto`
flow_id	MES 审批流 ID
ding_tpl_id	钉钉模板 ID
integration_plan_id	绑定的集成方案
priority	同单据多策略优先级
tenant_id	租户

③ `mes_xsl_approval_integration_plan` — 集成方案

字段	说明
plan_code / plan_name	方案编码/名称
source_doc_code	源单据
match_condition	方案级条件（可空=默认）
trigger_phase	`onApprove` / `onReject` / `onNodeApprove`
version	版本号
status	`0草稿 1已发布 2已停用`
remark	备注

④ `mes_xsl_approval_integration_action` — 集成动作

字段	说明
plan_id	所属方案
action_code / action_name	动作编码/名称
action_type	见下表
trigger_phase	可覆盖方案级 phase
target_doc_code	目标单据
target_lookup	定位已有单的 JSON 规则
field_mappings	字段映射 JSON
exec_config	动作扩展配置 JSON
exec_order	执行顺序
on_fail	`stop` / `continue`
idempotent_key	幂等键表达式
enabled	启用

action_type 枚举：

类型	说明	对标 Online
`SQL_UPDATE`	执行 UPDATE SQL	SQL 增强
`UPDATE_DOC`	结构化更新单据	—
`CREATE_DOC`	生成主+子表	Online form add
`CALL_API`	HTTP 调业务接口	Java http 增强
`CALL_HANDLER`	Spring Bean / Class	Java spring/class
`DELEGATE_ONLINE`	委托 Online 增强	复用已有增强

⑤ `mes_xsl_approval_integration_log` — 执行日志

字段	说明
record_id	审批台账 ID
instance_id	MES 实例 ID（可空）
plan_id / action_id	方案/动作
idempotent_key	幂等键
status	`success` / `failed` / `skipped`
source_biz_id	源单 ID
target_biz_id	目标单 ID
request_snapshot	映射后 payload
response_snapshot	执行结果
error_message	错误信息
retry_count	重试次数
exec_time_ms	耗时

⑥ `mes_xsl_approval_record` 扩展字段

新增字段	说明
integration_status	`0未执行 1成功 2部分失败 3失败`
integration_remark	编排摘要/错误

五、核心引擎设计

5.1 编排上下文 `IntegrationContext`

在现有 ApprovalCallbackContext 基础上扩展：

IntegrationContext {
    ApprovalCallbackContext approvalCtx;     // 审批上下文
    MesXslApprovalRecord record;             // 台账
    Map<String,Object> sourceRecord;         // 源单主表数据
    Map<String,List<Map>> sourceChildren;    // 源单子表
    Map<String,Object> vars;                 // 运行时变量池
    Map<String,String> actionResults;        // 前序动作产出（如 targetId）
}

5.2 变量体系（对齐 Online SQL 增强）

变量	含义
`#{source.id}` / `#{id}`	源单 ID
`#{source.字段名}`	源单字段
`#{sys_user_code}`	当前操作人
`#{sys_date}` / `#{sys_time}`	系统日期时间
`#{approval.instance_id}`	审批实例
`#{approval.apply_user}`	发起人
`#{action.xxx.target_id}`	前序动作生成的目标单 ID

5.3 字段映射 JSON 规范

{
  "masterMappings": [
    { "target": "spec_no", "type": "direct", "source": "formula_no" },
    { "target": "status", "type": "constant", "value": "1" },
    { "target": "approved_by", "type": "var", "value": "#{sys_user_code}" }
  ],
  "childMappings": [
    {
      "targetChildTable": "mes_xsl_mixing_spec_line",
      "sourceChildTable": "mes_xsl_formula_spec_line",
      "fkField": "main_id",
      "rowFilter": "stage_no <= 3",
      "mappings": [
        { "target": "material_code", "type": "direct", "source": "material_code" }
      ]
    }
  ]
}

映射类型： direct / constant / var / expression / lookup / ref_action

5.4 动作执行器接口

public interface IIntegrationActionExecutor {
    String supportActionType();
    IntegrationActionResult execute(IntegrationContext ctx, IntegrationAction action);
}

// Handler 扩展（复杂场景）
public interface IIntegrationActionHandler {
    String supportDocCode();  // "*" 通用
    IntegrationActionResult execute(IntegrationContext ctx, JSONObject config);
}

5.5 幂等与重试

幂等键：默认 record_id + action_id；CREATE 可配 source_id + target_doc_code
已 success：跳过（status=skipped）
failed：管理端可「手动重试」，retry_count+1
钉钉/MES 双通道：以 record_id 为统一键，避免重复生成

六、业务流程

6.1 发起审批

sequenceDiagram
    participant U as 用户
    participant FE as 前端/Online JS
    participant G as ApprovalGate
    participant P as PolicyService
    participant L as LaunchController
    participant R as ApprovalRecord

    U->>FE: 点击「提交审核」
    FE->>G: checkCanLaunch(bizTable, bizDataId)
    G->>R: 查最新台账
    G-->>FE: allowed / reason
    FE->>P: 匹配审核策略（可选）
    FE->>L: 发起审批（flowId / dingTpl）
    L->>R: createRunningRecord
    L->>H: enterFirstNode

6.2 审批通过 → 编排执行

sequenceDiagram
    participant H as HandleService
    participant CB as CallbackDispatcher
    participant O as Orchestrator
    participant E as ActionExecutor
    participant L as IntegrationLog

    H->>CB: fireApproved(ctx)
    H->>O: execute(ctx, APPROVED)
    O->>O: 匹配 Plan + Actions
    loop 按 exec_order
        O->>O: 检查幂等
        O->>E: execute(action)
        E-->>O: result / exception
        O->>L: 写日志
    end
    O-->>H: 全部成功 / 抛异常回滚

6.3 配置发布流程

草稿方案 → 测试预览（选源单ID，dry-run 不落库）→ 发布 → 生效
         ↑                                    ↓
         └──────── 版本回滚 ← 停用旧版本 ←────┘

七、前端设计

7.1 菜单结构

MES 审批管理
├── 审批流设计（已有）
├── 审批台账（已有）
├── 审核集成（新建）
│   ├── 单据注册中心
│   ├── 审核策略配置
│   ├── 集成方案管理
│   └── 集成执行日志

7.2 页面说明

页面	核心功能
单据注册中心	列表 CRUD；从 Online 同步；从实体扫描；字段预览
审核策略配置	选源单 → 条件 → 绑 Flow/钉钉模板 → 绑集成方案
集成方案设计器	基本信息 → 动作列表 → 字段映射（主/子 Tab）→ 测试预览 → 发布
集成执行日志	按台账/源单查；看 snapshot；失败重试

7.3 集成方案设计器（核心 UI）

Step 1 — 基本信息
源单据、触发时机、匹配条件（可视化 exp 构建器）

Step 2 — 动作列表
拖拽排序；增删动作；选 action_type

Step 3 — 字段映射
左：源单字段树（来自 registry / Online API）
右：目标单字段树
中间：映射连线 + 类型选择

Step 4 — 测试预览
输入源单 ID → 返回映射后的 JSON + SQL 预览 → 不执行

Step 5 — 发布
版本号递增；旧版自动停用（同 source + phase 仅一个 published）

八、Online 表单集成策略

场景	做法
源单是 Online 表	注册时 `doc_source=online`，字段从 `listByHeadId` 同步
目标单是 Online 表	`CREATE_DOC` 调 `POST /online/cgform/api/form/{code}`
已有 SQL/Java 增强	`DELEGATE_ONLINE` 动作，填 buttonCode + event
发起端	Online JS `beforeSubmit` 调 Gate API；自定义「提交审核」按钮
与 Online BPM	不混用；Online 表统一走 MES Gate + Policy

Online 增强机制借鉴对照

Online 增强	审核集成模块	现有审批
`buttonCode`	`action_code`	`@ApprovalBizAction.name`
`event: start/end`	`trigger_phase`	`phase: onApprove/onReject`
SQL 增强	`UPDATE_DOC` / `SQL_UPDATE`	节点 callbackActions
Java spring/class/http	`CALL_HANDLER` / `CALL_API`	Callback / HttpExecutor
自定义按钮 `exp`	`match_condition`	流程条件分支
JS `beforeSubmit`	发起审批前门禁	ApprovalGate
`onl_cgform_field`	字段映射数据源	Flow.titleField

九、与现有机制的关系

优先级（同一 trigger_phase）：
  1. IApprovalBizCallback（代码 SPI，长期保留）
  2. Flow 节点 callbackActions（精细节点控制）
  3. IntegrationOrchestrator（配置化编排，新增）

迁移策略：
  - 新单据：优先配置集成方案
  - 老 Callback：逐步迁移，不强制一次性改
  - @ApprovalBizAction：作为 CALL_API 动作的数据源（复用 Registry）

十、分期实施计划

Phase 0 — 基础骨架（约 2 周）

目标： 跑通「审通过后 SQL 改字段」最小闭环

交付物	内容
Flyway	6 张表 DDL + 字典项
后端	registry / policy / plan / action CRUD
引擎	`IntegrationOrchestrator` + `SQL_UPDATE` 执行器
挂接	`HandleService` 终态调用编排
日志	幂等 + integration_log
前端	策略列表 + 方案列表（JSON 编辑，暂无可视化映射）
试点	选 1 个简单单据：审批通过 UPDATE status

验收： 配置一条方案 → 审批通过 → 源单字段被更新 → 日志可查 → 重复回调不重复执行

Phase 1 — 单据编排（约 3 周）

目标： 支持 CREATE / UPDATE 主表 + 子表

交付物	内容
引擎	`FieldMappingEngine` + `CREATE_DOC` + `UPDATE_DOC`
注册	Online 同步 + Codegen 手工注册
执行	Codegen 走 Service；Online 走 form API
前端	单据注册页 + 方案动作配置（表单式）
试点	1 条「源单 → 生成下游单」业务链

验收： 审批通过自动生成主子表下游单；源单回写下游 ID

Phase 2 — 扩展与对接（约 2 周）

目标： 对接现有 @ApprovalBizAction、钉钉通道、Handler

交付物	内容
执行器	`CALL_API`（复用 ApprovalActionHttpExecutor）
执行器	`CALL_HANDLER`（spring/class）
执行器	`DELEGATE_ONLINE`
挂接	DingBpmsEventProcessor 终态触发编排
台账	record.integration_status 展示
前端	执行日志页 + 手动重试

验收： MES/钉钉双通道审通过后编排一致；失败可重试

Phase 3 — 可视化设计器（约 3 周）

目标： 实施人员可自助配置，无需写 JSON

交付物	内容
前端	字段映射可视化（双树连线）
前端	条件表达式构建器（Online exp 语法）
后端	dry-run 测试预览 API
后端	方案版本管理 + 发布/回滚
文档	实施配置手册

验收： 实施独立完成一条新集成链路，无需改 Java 代码

Phase 4 — 增强与治理（持续）

内容
监控告警（编排失败 IM/钉钉通知）
批量迁移老 Callback 到配置
expression / lookup 增强
性能优化（大子表批量 insert）
权限：集成方案按角色授权

十一、技术规范

11.1 代码规范

包路径：org.jeecg.modules.xslmes.approval.integration.*
遵循 JeecgBoot 实体/Controller/Service 模式
所有改动加 update-begin/end 注释（需 bug 号/需求号）
表名/字段名白名单校验（复用现有 IDENTIFIER Pattern）

11.2 字典项（新增）

字典	值
mes_xsl_integration_action_type	SQL_UPDATE / CREATE_DOC / UPDATE_DOC / CALL_API / CALL_HANDLER / DELEGATE_ONLINE
mes_xsl_integration_trigger_phase	onApprove / onReject / onNodeApprove
mes_xsl_integration_plan_status	0草稿 / 1已发布 / 2已停用
mes_xsl_integration_log_status	success / failed / skipped
mes_xsl_biz_doc_source	online / codegen / manual

11.3 安全

SQL_UPDATE 仅允许 UPDATE/INSERT（禁止 DROP/DELETE 全表）
变量替换后 SQL 预编译或严格转义
CALL_API 仅允许内部白名单路径（复用 BizActionRegistry）
编排执行默认用「系统机器人」账号，可配置为「最后审批人」

十二、风险与应对

风险	影响	应对
编排失败导致审批回滚	用户困惑	默认同事务；可选 afterCommit 异步 + 补偿（Phase 4）
主子表映射配置错误	脏数据	dry-run 预览 + 发布前校验 + 日志 snapshot
与现有 Callback 重复执行	双写	迁移期文档明确；方案级开关 `skip_legacy_callback`
Online 与 Codegen 执行路径不一致	行为差异	统一 DocExecutor 抽象，按 doc_source 路由
大子表性能	超时	批量 insert + 异步（Phase 4）
实施配置门槛高	推广慢	Phase 3 可视化 + 模板库（常用方案复制）

十三、验收标准

配置化：至少 3 条不同业务链路通过界面配置完成，无新增 Java Callback
双通道：MES 审批、钉钉审批各至少 1 条链路编排正常
幂等：同一审批终态重复回调，下游单不重复生成
可观测：台账 + 集成日志可定位每次执行 input/output/error
兼容：现有 RubberQuickTestStdApprovalCallback 等老逻辑不受影响
回滚：编排失败时审批状态与业务数据一致（不回滚一半）

十四、资源与依赖

角色	职责
后端 1	引擎 + 执行器 + 挂接
后端 0.5	CRUD + Online 对接
前端 1	4 管理页 + 设计器
实施/业务	试点场景定义 + 验收
DBA	Flyway 评审

外部依赖： MySQL、Redis（可选缓存 registry）、Online 模块 API、现有审批模块稳定运行。

十五、首个试点场景

选一条链路清晰、主子表、价值明显的业务做 Phase 0~1 试点：

配合示方（mes_xsl_formula_spec）审批通过 →
① UPDATE 源单 audit_status=已批准
② CREATE 下游密炼示方（主表 + 明细映射）
③ UPDATE 源单 approved_mixing_id=下游ID

该场景覆盖 CREATE + UPDATE + 主子映射，且与现有审批流已打通，最适合验证整体方案。

十六、下一步行动

确认试点业务（配合示方 or 其他）及需求号/bug 号（用于 update-begin 注释）
评审本方案 — 确认 Phase 划分、表结构、是否与 Online BPM 边界
启动 Phase 0 — 先出 Flyway DDL + IntegrationOrchestrator 骨架 + 1 条 SQL_UPDATE 试点

附录：相关现有代码索引

文件	说明
`approval/entity/MesXslApprovalFlow.java`	审批流定义
`approval/entity/MesXslApprovalRecord.java`	审批台账
`approval/callback/ApprovalCallbackContext.java`	回调上下文
`approval/callback/IApprovalBizCallback.java`	业务回调 SPI
`approval/action/ApprovalBizAction.java`	可发现业务动作注解
`approval/service/impl/MesXslApprovalHandleServiceImpl.java`	审批办理引擎
`approval/service/impl/MesXslApprovalGateServiceImpl.java`	跨通道门禁
`approval/callback/ApprovalActionHttpExecutor.java`	节点回调 HTTP 执行器
`views/approval/flow/`	前端审批流设计器

文档维护：随 Phase 推进更新版本号与交付状态。

22 KiB Raw Blame History Unescape Escape