669 lines
22 KiB
Markdown
669 lines
22 KiB
Markdown
# 审核集成功能 — 整体方案计划
|
||
|
||
> **版本：** 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<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 规范
|
||
|
||
```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 推进更新版本号与交付状态。*
|