# 审核集成功能 — 整体方案计划 > **版本:** V1.0 > **日期:** 2026-06-05 > **定位:** 在现有 MES 审批引擎之上,新增**审批后业务编排层**,实现「哪些单要审、审完自动生成/更新下游单」的可配置化集成。 > **原则:** 审批归审批、编排归编排、复杂逻辑归代码;与 Online 增强模型对齐、与现有 `@ApprovalBizAction` / Gate 台账兼容。 --- ## 目录 - [一、背景与目标](#一背景与目标) - [二、总体架构](#二总体架构) - [三、功能模块设计](#三功能模块设计) - [四、数据模型设计](#四数据模型设计) - [五、核心引擎设计](#五核心引擎设计) - [六、业务流程](#六业务流程) - [七、前端设计](#七前端设计) - [八、Online 表单集成策略](#八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 编排引擎(审后动作必须服务端执行) --- ## 二、总体架构 ```mermaid 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) ``` **执行顺序(同一事务内):** 1. 现有 `IApprovalBizCallback`(兼容老逻辑) 2. 现有节点 `callbackActions`(HTTP 调用) 3. **新增**集成编排(按 `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` 基础上扩展: ```java IntegrationContext { ApprovalCallbackContext approvalCtx; // 审批上下文 MesXslApprovalRecord record; // 台账 Map sourceRecord; // 源单主表数据 Map> sourceChildren; // 源单子表 Map vars; // 运行时变量池 Map 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 规范 ```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 动作执行器接口 ```java 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 发起审批 ```mermaid 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 审批通过 → 编排执行 ```mermaid 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 可视化 + 模板库(常用方案复制) | --- ## 十三、验收标准 1. **配置化**:至少 3 条不同业务链路通过界面配置完成,无新增 Java Callback 2. **双通道**:MES 审批、钉钉审批各至少 1 条链路编排正常 3. **幂等**:同一审批终态重复回调,下游单不重复生成 4. **可观测**:台账 + 集成日志可定位每次执行 input/output/error 5. **兼容**:现有 `RubberQuickTestStdApprovalCallback` 等老逻辑不受影响 6. **回滚**:编排失败时审批状态与业务数据一致(不回滚一半) --- ## 十四、资源与依赖 | 角色 | 职责 | |-----|------| | 后端 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 + 主子映射,且与现有审批流已打通,最适合验证整体方案。 --- ## 十六、下一步行动 1. **确认试点业务**(配合示方 or 其他)及需求号/bug 号(用于 update-begin 注释) 2. **评审本方案** — 确认 Phase 划分、表结构、是否与 Online BPM 边界 3. **启动 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 推进更新版本号与交付状态。*