# 采购入库流程优化 - 前端联调方案

## 业务流程概述

优化后的采购入库流程：

```
ERP采购订单 -> MES到货通知 -> MES采购入库 -> BPM审批 -> 入库成功
```

核心改进：**每一步自动带入上游数据，物料统一使用MDM模块数据，减少手动输入**。

---

## 涉及页面

- 到货通知列表页（`/mes/wm/arrival-notice`）
- 到货通知新增/编辑弹窗
- 采购入库列表页（`/mes/wm/item-receipt`）
- 采购入库新增/编辑弹窗
- 采购订单选择器弹窗（新增组件）
- 到货通知选择器弹窗（新增组件）

---

## 数据带入规则

### 1. 采购订单 -> 到货通知

| 目标字段 | 数据来源 | 自动带入 | 说明 |
|----------|----------|----------|------|
| 供应商 | 采购订单.supplierId | ✅ | 自动填充，不可修改 |
| 采购订单编码 | 采购订单.no | ✅ | 显示用，不可修改 |
| 采购订单ID | 采购订单.id | ✅ | 关联字段 |

### 2. 采购订单行 -> 到货通知行

| 目标字段 | 数据来源 | 自动带入 | 说明 |
|----------|----------|----------|------|
| 采购订单行ID | 采购订单行.id | ✅ | 关联字段，用于追溯 |
| 物料编码 | ERP产品编码映射MDM物料 | ⚠️ | 需用户选择映射关系 |
| 到货数量 | 订购数量 - 已入库数量 | ✅ | 可修改 |
| 是否需检验 | 默认false | ✅ | 可修改 |

### 3. 到货通知 -> 采购入库

| 目标字段 | 数据来源 | 自动带入 | 说明 |
|----------|----------|----------|------|
| 供应商 | 到货通知.vendorId | ✅ | 自动填充，不可修改 |
| 到货通知编码 | 到货通知.code | ✅ | 显示用 |
| 采购订单编码 | 到货通知.purchaseOrderCode | ✅ | 显示用 |

### 4. 到货通知行 -> 采购入库行

| 目标字段 | 数据来源 | 自动带入 | 说明 |
|----------|----------|----------|------|
| 物料ID | 到货通知行.itemId | ✅ | 不可修改 |
| 到货通知行ID | 到货通知行.id | ✅ | 关联字段 |
| 采购订单行ID | 到货通知行.purchaseOrderItemId | ✅ | 关联字段 |
| 入库数量 | 到货通知行.qualifiedQuantity | ✅ | 可修改 |
| 批次信息 | 自动生成 | ✅ | 根据批次规则 |

---

## 新增 API 接口

### 到货通知模块

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/mes/wm/arrival-notice/generate-from-purchase-order?purchaseOrderId={id}` | 根据采购订单生成到货通知单 |

**请求参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| purchaseOrderId | Long | 是 | ERP采购订单编号 |

**响应：** `{ "code": 200, "data": 123, "msg": "操作成功" }` （data为生成的到货通知单编号）

### 采购入库模块

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/mes/wm/item-receipt/generate-from-arrival-notice?arrivalNoticeId={id}` | 根据到货通知单生成采购入库单 |
| PUT | `/mes/wm/item-receipt/submit-approval?id={id}&processDefinitionKey={key}` | 提交采购入库单审批 |

**请求参数（generate-from-arrival-notice）：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| arrivalNoticeId | Long | 是 | 到货通知单编号 |

**请求参数（submit-approval）：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | Long | 是 | 采购入库单编号 |
| processDefinitionKey | String | 是 | BPM流程定义Key |

---

## 前端实现要点

### 1. 到货通知页面改造

#### 1.1 新增"从采购订单生成"按钮

```html
<el-button type="primary" @click="handleGenerateFromPO">
  从采购订单生成
</el-button>
```

#### 1.2 采购订单选择器弹窗

- 调用 ERP 接口获取已审核状态的采购订单列表
- 显示字段：订单号、供应商名称、订单日期、总金额
- 选择后调用 `/mes/wm/arrival-notice/generate-from-purchase-order` 接口

#### 1.3 数据获取时机

```
用户点击"从采购订单生成" 
  -> 弹出采购订单选择器 
  -> 选择订单 
  -> 调用 generate-from-purchase-order API 
  -> 跳转到到货通知编辑页（ID为返回值）
  -> 显示已带入的数据
```

#### 1.4 字段显示规则

- 自动带入的字段显示为**禁用状态**（灰色背景）
- 物料选择器仍保留，允许用户补充物料映射关系

### 2. 采购入库页面改造

#### 2.1 新增"从到货通知生成"按钮

```html
<el-button type="primary" @click="handleGenerateFromAN">
  从到货通知生成
</el-button>
```

#### 2.2 到货通知选择器弹窗

- 调用 MES 接口获取状态为"待入库"的到货通知单列表
- 显示字段：通知单号、供应商名称、到货日期、状态
- 选择后调用 `/mes/wm/item-receipt/generate-from-arrival-notice` 接口

#### 2.3 数据获取时机

```
用户点击"从到货通知生成" 
  -> 弹出到货通知选择器 
  -> 选择通知单 
  -> 调用 generate-from-arrival-notice API 
  -> 跳转到采购入库编辑页（ID为返回值）
  -> 显示已带入的数据
```

#### 2.4 BPM审批流程

- 状态为"草稿"时显示"提交审批"按钮
- 点击后弹出流程选择器（复用现有BPM流程选择组件）
- 选择流程后调用 `submit-approval` API
- 状态变为"审批中"，禁止编辑

### 3. 状态流转图

#### 到货通知状态

```
草稿(0) --提交--> 待质检(2) --IQC完成--> 待入库(3) --入库完成--> 已完成(4)
              \
               -> 待入库(3) [无需检验]
```

#### 采购入库状态（新增BPM审批）

```
草稿(0) --提交审批--> 审批中(2) --审批通过--> 待上架(3) --上架--> 待入库(4) --入库--> 已完成(5)
                        \
                         -> 审批拒绝 -> 草稿(0) [可重新提交]
```

---

## 注意事项

### 数据带入强调

1. **物料信息必须从MDM模块获取**，不允许手动输入物料编码/名称
2. **采购订单行关联**：到货通知行必须关联采购订单行，确保数据可追溯
3. **入库数量校验**：入库数量不能超过到货通知行的合格数量

### 前端校验规则

1. 从采购订单生成到货通知时，校验采购订单状态必须为"已审核"
2. 从到货通知生成采购入库时，校验到货通知状态必须为"待入库"
3. 提交审批时，校验入库单状态必须为"草稿"，且至少有一条入库行

### 错误处理

| 错误码 | 说明 | 前端提示 |
|--------|------|----------|
| 1040705007 | 采购订单不存在 | "所选采购订单不存在，请刷新后重试" |
| 1040705008 | 采购订单无明细数据 | "该采购订单没有明细数据" |
| WM_ARRIVAL_NOTICE_NO_LINE | 到货通知无行数据 | "该到货通知没有明细数据" |

---

## 后端修改文件清单

### 数据库变更
- `sql/mysql/mes_purchase_receipt_enhance.sql`

### ERP API 扩展
- `yudao-module-erp-api/.../ErpPurchaseOrderApi.java`
- `yudao-module-erp-api/.../ErpPurchaseOrderItemRespDTO.java`
- `yudao-module-erp/.../ErpPurchaseOrderApiImpl.java`

### MES DO/VO 修改
- `MesWmArrivalNoticeDO.java` - 新增 purchaseOrderCode
- `MesWmArrivalNoticeLineDO.java` - 新增 purchaseOrderItemId
- `MesWmItemReceiptDO.java` - 新增 processInstanceId
- `MesWmItemReceiptLineDO.java` - 新增 purchaseOrderItemId
- 对应的 SaveReqVO 和 RespVO

### MES Service 新增方法
- `MesWmArrivalNoticeService.generateArrivalNoticeFromPurchaseOrder()`
- `MesWmItemReceiptService.generateItemReceiptFromArrivalNotice()`
- `MesWmItemReceiptService.submitItemReceiptApproval()`
- `MesWmItemReceiptService.updateItemReceiptAuditStatus()`

### MES Controller 新增接口
- `POST /mes/wm/arrival-notice/generate-from-purchase-order`
- `POST /mes/wm/item-receipt/generate-from-arrival-notice`
- `PUT /mes/wm/item-receipt/submit-approval`

### BPM 监听器
- `MesWmItemReceiptStatusListener.java`