# MDM 与 MES 物料双向同步 - 前端联调方案

## 涉及页面

- MDM 模块：物料主数据列表页、物料新增/编辑页
- MES 模块：物料产品列表页、物料产品新增/编辑页

## 业务流程说明

### 双向同步关系

```
MDM 物料 ←――――――→ MES 物料
    ↑                  ↑
    | syncMes=true     | syncMdm=true
    └──────────────────┘
```

| 操作端 | 同步触发条件 | 同步目标 |
|--------|-------------|---------|
| MDM 新增/编辑物料 | `syncMes = true` | MES `mes_md_item` + `mes_md_item_batch_config` |
| MES 新增/编辑物料 | `syncMdm = true` | MDM `mdm_item` + `mdm_item_batch_config` |

### 批次属性字段（7个必填项）

| 字段 | 中文名 | 说明 |
|------|--------|------|
| produceDateFlag | 生产日期必填 | 入库时是否必填生产日期 |
| expireDateFlag | 有效期必填 | 入库时是否必填有效期 |
| receiptDateFlag | 入库日期必填 | 入库时是否必填入库日期 |
| vendorFlag | 供应商必填 | 入库时是否必填供应商 |
| purchaseOrderCodeFlag | 采购订单号必填 | 入库时是否必填采购订单号 |
| lotNumberFlag | 生产批号必填 | 入库时是否必填生产批号 |
| qualityStatusFlag | 质量状态必填 | 入库时是否必填质量状态 |

---

## API

### 1. MDM 物料新增/编辑

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/admin-api/mdm/item/create` | 新增 MDM 物料 |
| PUT | `/admin-api/mdm/item/update` | 编辑 MDM 物料 |

**请求参数（MdmItemSaveReqVO）：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | Long | 否 | 物料编号（编辑时必填） |
| code | String | 是 | 物料编码 |
| name | String | 是 | 物料名称 |
| specification | String | 否 | 规格型号 |
| categoryId | Long | 否 | 分类ID（关联 MES 物料分类） |
| unitMeasureId | Long | 否 | 计量单位ID |
| itemType | Integer | 是 | 物料类型：1原料, 2半成品, 3成品, 4辅料 |
| status | Integer | 是 | 状态：0启用, 1禁用 |
| minStock | BigDecimal | 否 | 最低库存 |
| maxStock | BigDecimal | 否 | 最高库存 |
| isBatchManaged | Boolean | 否 | 是否批次管理 |
| isHighValue | Boolean | 否 | 是否高值物料 |
| remark | String | 否 | 备注 |
| **syncMes** | **Boolean** | **否** | **是否同步到 MES** |
| **produceDateFlag** | **Boolean** | **否** | **生产日期必填** |
| **expireDateFlag** | **Boolean** | **否** | **有效期必填** |
| **receiptDateFlag** | **Boolean** | **否** | **入库日期必填** |
| **vendorFlag** | **Boolean** | **否** | **供应商必填** |
| **purchaseOrderCodeFlag** | **Boolean** | **否** | **采购订单号必填** |
| **lotNumberFlag** | **Boolean** | **否** | **生产批号必填** |
| **qualityStatusFlag** | **Boolean** | **否** | **质量状态必填** |

**响应：**

```json
{
  "code": 0,
  "msg": "操作成功",
  "data": 123  // 物料ID
}
```

### 2. MES 物料新增/编辑

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/admin-api/mes/md-item/create` | 新增 MES 物料 |
| PUT | `/admin-api/mes/md-item/update` | 编辑 MES 物料 |

**请求参数（MesMdItemSaveReqVO）：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | Long | 否 | 物料编号（编辑时必填） |
| code | String | 是 | 物料编码 |
| name | String | 是 | 物料名称 |
| specification | String | 否 | 规格型号 |
| unitMeasureId | Long | 是 | 计量单位ID |
| itemTypeId | Long | 是 | 物料分类ID |
| safeStockFlag | Boolean | 否 | 是否启用安全库存 |
| minStock | BigDecimal | 否 | 最低库存 |
| maxStock | BigDecimal | 否 | 最高库存 |
| highValue | Boolean | 否 | 是否高值物料 |
| batchFlag | Boolean | 否 | 是否批次管理 |
| remark | String | 否 | 备注 |
| **syncMdm** | **Boolean** | **否** | **是否同步到 MDM** |

**响应：**

```json
{
  "code": 0,
  "msg": "操作成功",
  "data": 456  // 物料ID
}
```

### 3. MES 批次属性配置保存

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/admin-api/mes/md-item-batch-config/create` | 新增批次配置 |
| PUT | `/admin-api/mes/md-item-batch-config/update` | 编辑批次配置 |

**请求参数（MesMdItemBatchConfigSaveReqVO）：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | Long | 否 | 配置ID（编辑时必填） |
| itemId | Long | 是 | 物料ID |
| produceDateFlag | Boolean | 否 | 生产日期必填 |
| expireDateFlag | Boolean | 否 | 有效期必填 |
| receiptDateFlag | Boolean | 否 | 入库日期必填 |
| vendorFlag | Boolean | 否 | 供应商必填 |
| purchaseOrderCodeFlag | Boolean | 否 | 采购订单号必填 |
| lotNumberFlag | Boolean | 否 | 生产批号必填 |
| qualityStatusFlag | Boolean | 否 | 质量状态必填 |

**响应：**

```json
{
  "code": 0,
  "msg": "操作成功",
  "data": 789  // 配置ID
}
```

---

## 前端修改点

### 1. MDM 物料新增/编辑页面

#### 1.1 表单字段新增

在物料表单中新增以下字段：

| 字段 | 控件类型 | 展示条件 | 说明 |
|------|----------|----------|------|
| syncMes | Switch 开关 | 始终显示 | 是否同步到 MES |
| 批次属性配置 | 分组标题 | `isBatchManaged = true` 时显示 | 批次属性必填配置 |
| produceDateFlag | Switch 开关 | `isBatchManaged = true` 时显示 | 生产日期必填 |
| expireDateFlag | Switch 开关 | `isBatchManaged = true` 时显示 | 有效期必填 |
| receiptDateFlag | Switch 开关 | `isBatchManaged = true` 时显示 | 入库日期必填 |
| vendorFlag | Switch 开关 | `isBatchManaged = true` 时显示 | 供应商必填 |
| purchaseOrderCodeFlag | Switch 开关 | `isBatchManaged = true` 时显示 | 采购订单号必填 |
| lotNumberFlag | Switch 开关 | `isBatchManaged = true` 时显示 | 生产批号必填 |
| qualityStatusFlag | Switch 开关 | `isBatchManaged = true` 时显示 | 质量状态必填 |

#### 1.2 数据结构

```javascript
data() {
  return {
    form: {
      // 原有字段...
      syncMes: false,
      // 批次属性配置
      produceDateFlag: false,
      expireDateFlag: false,
      receiptDateFlag: false,
      vendorFlag: false,
      purchaseOrderCodeFlag: false,
      lotNumberFlag: false,
      qualityStatusFlag: false
    }
  }
}
```

#### 1.3 提交逻辑

提交时将所有字段一起提交到 `/admin-api/mdm/item/create` 或 `/admin-api/mdm/item/update`。

**注意事项：**
- 当 `isBatchManaged = true` 时，显示批次属性配置区域
- 后端会自动将批次配置保存到 `mdm_item_batch_config` 表
- 当 `syncMes = true` 时，后端会同步物料和批次配置到 MES

---

### 2. MES 物料新增/编辑页面

#### 2.1 表单字段新增

在物料表单中新增以下字段：

| 字段 | 控件类型 | 展示条件 | 说明 |
|------|----------|----------|------|
| syncMdm | Switch 开关 | 始终显示 | 是否同步到 MDM |

#### 2.2 数据结构

```javascript
data() {
  return {
    form: {
      // 原有字段...
      syncMdm: false
    }
  }
}
```

#### 2.3 提交逻辑

提交时将 `syncMdm` 字段一起提交。

**注意事项：**
- 当 `syncMdm = true` 时，后端会同步物料和批次配置到 MDM
- MES 的批次配置通过单独的批次配置页面维护（已有功能）

---

### 3. MES 批次属性配置页面（已有功能，无需修改）

该页面已有，用于配置 MES 物料的批次属性必填项。当 MES 物料同步到 MDM 时，会自动带上这些配置。

---

## 字段展示规则

### MDM 物料列表页

| 字段 | 展示位置 | 说明 |
|------|----------|------|
| code | 列表、详情 | 物料编码 |
| name | 列表、详情 | 物料名称 |
| specification | 列表、详情 | 规格型号 |
| itemType | 列表、详情 | 物料类型（需转换显示：1原料, 2半成品, 3成品, 4辅料） |
| status | 列表、详情 | 状态 |
| isBatchManaged | 列表、详情 | 是否批次管理 |
| syncMes | 详情 | 是否已同步到 MES（根据是否有对应 MES 物料判断） |

### MES 物料列表页

| 字段 | 展示位置 | 说明 |
|------|----------|------|
| code | 列表、详情 | 物料编码 |
| name | 列表、详情 | 物料名称 |
| specification | 列表、详情 | 规格型号 |
| itemTypeName | 列表、详情 | 物料分类名称 |
| batchFlag | 列表、详情 | 是否批次管理 |
| syncMdm | 详情 | 是否已同步到 MDM（根据是否有对应 MDM 物料判断） |

---

## 业务规则说明

### 同步规则

| 场景 | 规则 |
|------|------|
| MDM 新增物料 + syncMes=true | 创建 MDM 物料 → 同步创建 MES 物料和批次配置 |
| MDM 编辑物料 + syncMes=true | 更新 MDM 物料 → 同步更新 MES 物料和批次配置（按 code 匹配） |
| MES 新增物料 + syncMdm=true | 创建 MES 物料 → 同步创建 MDM 物料和批次配置 |
| MES 编辑物料 + syncMdm=true | 更新 MES 物料 → 同步更新 MDM 物料和批次配置（按 code 匹配） |

### 批次配置同步规则

| 场景 | 规则 |
|------|------|
| MDM → MES 同步 | 将 MDM 的 `mdm_item_batch_config` 同步到 MES 的 `mes_md_item_batch_config` |
| MES → MDM 同步 | 将 MES 的 `mes_md_item_batch_config` 同步到 MDM 的 `mdm_item_batch_config` |

### 字段映射规则

| MDM 字段 | MES 字段 | 说明 |
|----------|----------|------|
| code | code | 物料编码，唯一标识 |
| name | name | 物料名称 |
| specification | specification | 规格型号 |
| unitMeasureId (MDM 单位ID) | unitMeasureId (MES 单位ID) | 通过单位编码转换 |
| categoryId (MDM 分类ID) | itemTypeId (MES 分类ID) | 通过分类编码转换 |
| itemType | itemOrProduct | 1/2/4→ITEM, 3→PRODUCT |
| isBatchManaged | batchFlag | 是否批次管理 |
| isHighValue | highValue | 是否高值物料 |
| minStock | minStock | 最低库存 |
| maxStock | maxStock | 最高库存 |

### 物料类型映射

| MDM itemType | MDM 说明 | MES itemOrProduct | MES 说明 |
|--------------|----------|-------------------|----------|
| 1 | 原料 | ITEM | 物料 |
| 2 | 半成品 | ITEM | 物料 |
| 3 | 成品 | PRODUCT | 产品 |
| 4 | 辅料 | ITEM | 物料 |

---

## 注意事项

1. **同步失败处理**：同步操作与物料保存是同一事务，如果同步失败，整个保存操作会回滚。

2. **编码唯一性**：物料编码（code）在 MDM 和 MES 中都必须唯一，同步时按 code 进行匹配（存在则更新，不存在则新增）。

3. **单位/分类映射**：MDM 和 MES 的单位、分类是两套独立的主数据，同步时通过编码（code）进行映射，确保两边有相同的编码数据。

4. **批次配置同步时机**：
   - MDM 保存物料时，批次配置保存到本地 `mdm_item_batch_config` 表
   - 如果 `syncMes=true`，同时同步到 MES 的 `mes_md_item_batch_config` 表
   - MES 同理

5. **前端展示建议**：
   - 在列表页增加"同步状态"列，显示是否已同步到对方系统
   - 可以通过物料编码查询对方系统是否存在来判断同步状态

6. **数据一致性**：
   - 建议在一端维护物料数据后，同步到另一端
   - 避免两边同时编辑同一物料导致数据冲突

---

## 调试建议

1. 首先测试 MDM → MES 同步：创建 MDM 物料，勾选 syncMes，检查 MES 是否生成对应物料
2. 测试 MES → MDM 同步：创建 MES 物料，勾选 syncMdm，检查 MDM 是否生成对应物料
3. 测试批次配置同步：在 MDM 设置批次属性，同步后检查 MES 的批次配置是否一致
4. 检查数据库：
   - MDM 物料：`mdm_item`、`mdm_item_batch_config`
   - MES 物料：`mes_md_item`、`mes_md_item_batch_config`