# 批次追溯扩展 - 前端联调方案

## 概述

在现有批次追溯（向前/向后）基础上，扩展 4 个能力，补齐批次全链路追溯：

1. **采购来源**：从批次反查采购入库单 + IQC 质检结论（原料侧断链打通）
2. **销售去向**：从批次反查销售出库单 + OQC 质检结论（成品侧断链打通）
3. **工序流转**：从批次查看产出/投入的工序级事件（无需建表，动态聚合）
4. **SN 反查**：输入 SN 序列号直接定位批次并跳转详情

后端 4 个新接口均已完成并编译通过，本文档指导前端对接。

---

## 一、涉及页面

| 页面 | 路径 | 改动说明 |
|------|------|----------|
| 批次追溯页 | `src/views/mes/qc/batchtrace/index.vue` | 顶部新增 SN 反查输入框 |
| 追溯详情弹窗 | `src/views/mes/qc/batchtrace/modules/trace-detail.vue` | 子页签扩展为 5 个（生产/采购来源/销售去向/工序流转/质检） |
| 采购来源子列表 | `src/views/mes/qc/batchtrace/modules/purchase-source-list.vue` | 新增子组件 |
| 销售去向子列表 | `src/views/mes/qc/batchtrace/modules/sales-target-list.vue` | 新增子组件 |
| 工序流转子列表 | `src/views/mes/qc/batchtrace/modules/process-trace-list.vue` | 新增子组件 |
| 批次 API | `src/api/mes/wm/batch/index.ts` | 新增 4 个接口函数 |
| 列定义 | `src/views/mes/qc/batchtrace/data.ts` | 新增 3 组列配置 |

---

## 二、API 接口

### 2.1 批次采购来源

**请求方式**：GET

**请求路径**：`/mes/wm/batch/purchase-sources`

**请求参数**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| code | String | 是 | 批次编码 |

**响应**：

```json
{
  "code": 0,
  "data": [
    {
      "receiptCode": "IR20250713001",
      "receiptDate": "2026-08-01 10:00:00",
      "purchaseOrderCode": "PO20250701001",
      "vendorId": 20,
      "vendorCode": "VENDOR001",
      "vendorName": "供应商A",
      "iqcCode": "IQC20250713001",
      "checkResult": 1,
      "itemId": 100,
      "itemCode": "ITEM001",
      "itemName": "原料A",
      "batchCode": "BT20260731001",
      "receivedQuantity": 100
    }
  ]
}
```

**字段说明**：

| 字段 | 类型 | 说明 |
|------|------|------|
| receiptCode | String | 采购入库单号 |
| receiptDate | Date | 入库日期 |
| purchaseOrderCode | String | 采购订单号 |
| vendorCode / vendorName | String | 供应商编码/名称（后端富化） |
| iqcCode | String | IQC 质检单号（可能为空） |
| checkResult | Integer | IQC 质检结论，字典 `mes_qc_check_result` |
| itemCode / itemName | String | 物料编码/名称（后端富化） |
| batchCode | String | 批次编码 |
| receivedQuantity | BigDecimal | 入库数量 |

### 2.2 批次销售去向

**请求方式**：GET

**请求路径**：`/mes/wm/batch/sales-targets`

**请求参数**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| code | String | 是 | 批次编码 |

**响应**：

```json
{
  "code": 0,
  "data": [
    {
      "salesCode": "SS20250713001",
      "salesDate": "2026-08-05 14:00:00",
      "salesOrderCode": "SO20250701001",
      "clientId": 30,
      "clientName": "客户A",
      "oqcCode": "OQC20250713001",
      "checkResult": 1,
      "itemId": 100,
      "itemCode": "ITEM001",
      "itemName": "成品A",
      "batchCode": "BT20260804001",
      "quantity": 50,
      "qualityStatus": 1
    }
  ]
}
```

**字段说明**：

| 字段 | 类型 | 说明 |
|------|------|------|
| salesCode | String | 销售出库单号 |
| salesDate | Date | 出库日期 |
| salesOrderCode | String | 销售订单号 |
| clientName | String | 客户名称（后端富化，注意：客户无编码字段） |
| oqcCode | String | OQC 质检单号（可能为空） |
| checkResult | Integer | OQC 质检结论，字典 `mes_qc_check_result` |
| itemCode / itemName | String | 物料编码/名称（后端富化） |
| batchCode | String | 批次编码 |
| quantity | BigDecimal | 出库数量 |
| qualityStatus | Integer | 质量状态，字典 `mes_wm_quality_status` |

### 2.3 批次工序流转

**请求方式**：GET

**请求路径**：`/mes/wm/batch/process-trace`

**请求参数**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| code | String | 是 | 批次编码 |

**响应**：

```json
{
  "code": 0,
  "data": [
    {
      "eventType": "IN",
      "workOrderId": 50,
      "workOrderCode": "WO20260730001",
      "processId": 10,
      "processCode": "P001",
      "processName": "下料",
      "batchCode": "BT20260804001",
      "quantity": 100,
      "qualityStatus": null,
      "eventTime": "2026-08-04 09:00:00",
      "processSort": 1
    },
    {
      "eventType": "OUT",
      "workOrderId": 50,
      "workOrderCode": "WO20260730001",
      "processId": 10,
      "processCode": "P001",
      "processName": "下料",
      "batchCode": "BT20260804001",
      "quantity": 90,
      "qualityStatus": 1,
      "eventTime": "2026-08-04 10:00:00",
      "processSort": 1
    }
  ]
}
```

**字段说明**：

| 字段 | 类型 | 说明 |
|------|------|------|
| eventType | String | 事件类型：`OUT` = 产出、`IN` = 投入 |
| workOrderCode | String | 工单号（后端富化） |
| processCode / processName | String | 工序编码/名称（后端富化） |
| batchCode | String | 批次编码 |
| quantity | BigDecimal | 数量（OUT=产出数量，IN=投入数量） |
| qualityStatus | Integer | 质量状态（仅 OUT 侧有值，IN 侧为 null） |
| eventTime | Date | 事件时间（OUT=产出日期，IN=消耗日期） |
| processSort | Integer | 工序序号（用于展示工序先后） |

**排序规则**：后端已按 `workOrderId asc → processSort asc（空值置后）→ eventTime asc` 排序，前端直接按返回顺序展示即可。

### 2.4 SN 反查批次

**请求方式**：GET

**请求路径**：`/mes/wm/batch/get-by-sn`

**请求参数**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| sn | String | 是 | SN 序列号 |

**响应**：与 `GET /mes/wm/batch/get` 完全一致（`MesWmBatchRespVO`），未命中返回 `data: null`：

```json
{
  "code": 0,
  "data": {
    "id": 1,
    "code": "BT20260804001",
    "itemId": 100,
    "itemCode": "ITEM001",
    "itemName": "成品A",
    "vendorCode": "VENDOR001",
    "vendorName": "供应商A",
    "clientName": "客户A",
    "workOrderCode": "WO20260730001",
    "taskCode": "TASK001",
    "workstationCode": "WS001",
    "toolCode": "TOOL001",
    "lotNumber": "LOT20260801"
  }
}
```

**说明**：SN 在 `mes_wm_sn` 表通过 `code` 唯一匹配，命中后取其 `batch_code` 反查批次。前端根据 `data` 是否为空判断是否提示"未找到对应批次"。

---

## 三、字段展示规则

| 功能 | 展示位置 | 字段说明 |
|------|----------|----------|
| 采购来源 | 详情弹窗子页签"采购来源" | 入库单号、入库日期、采购订单、供应商、IQC单号、IQC结论、物料、数量 |
| 销售去向 | 详情弹窗子页签"销售去向" | 出库单号、出库日期、销售订单、客户、OQC单号、OQC结论、物料、数量、质量状态 |
| 工序流转 | 详情弹窗子页签"工序流转" | 事件类型、工单号、工序编码/名称、数量、时间、质量状态 |
| SN 反查 | 追溯页顶部输入框 | 输入 SN → 命中直接打开批次详情弹窗 |

**字典说明**：

| 字典 | 取值 |
|------|------|
| `mes_qc_check_result` | 1=合格、2=特采、3=退货、4=报废 |
| `mes_wm_quality_status` | 0=待检、1=合格、2=不合格 |

---

## 四、数据带入说明

| 场景 | 带入说明 |
|------|----------|
| 追溯页 → 采购来源 | 点击批次行，携带该行的 `code` 调用 `getPurchaseSourceList(code)` |
| 追溯页 → 销售去向 | 点击批次行，携带该行的 `code` 调用 `getSalesTargetList(code)` |
| 追溯页 → 工序流转 | 点击批次行，携带该行的 `code` 调用 `getProcessTraceList(code)` |
| SN 输入框 → 详情 | 输入 SN 调用 `getBatchBySn(sn)`，返回的 `code` 作为详情弹窗查询依据（或直接使用返回数据） |

---

## 五、接口调用时序

1. 追溯页加载批次列表（`/mes/wm/batch/page`）
2. 点击某批次行 → 打开详情弹窗，弹窗内默认展示"生产"页签（向前/向后追溯）
3. 切换"采购来源/销售去向/工序流转"页签时，按需调用对应接口（建议懒加载：首次切换才请求）
4. 顶部 SN 输入框 → 按回车或点击搜索 → `getBatchBySn` → 命中打开详情弹窗，未命中提示无记录

---

## 六、业务规则说明

| 场景 | 规则 |
|------|------|
| 原料批次 | 有采购来源（入库+IQC），无销售去向；工序流转以 IN 投入为主 |
| 成品批次 | 有销售去向（出库+OQC），无采购来源；工序流转以 OUT 产出为主 |
| 中间批次 | 同时存在 IN 与 OUT 事件，体现工序级流转 |
| 质检单缺失 | `iqcCode`/`oqcCode` 可能为空（单据未关联），结论列展示"-" |
| SN 未命中 | `get-by-sn` 返回 `data: null`，前端提示"未找到该 SN 对应的批次" |
| 数据为空 | 三个子列表接口均可能返回空数组，页面展示空态提示 |

---

## 七、注意事项

- 三个列表接口与既有 forward/backward 相同，均需要 `mes:wm-batch:query` 权限
- 子页签建议懒加载 + 缓存，避免每次切换重复请求
- 工序流转的 `processSort` 由后端排好序，前端勿再排序
- 销售侧 `qualityStatus` 为字典值，展示用 `mes_wm_quality_status` 字典翻译
- 测试环境可能存在无 `batchCode` 的销售出库行数据，属历史脏数据，前端对空字段做兜底展示即可

---

## 八、相关接口汇总

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /mes/wm/batch/purchase-sources | 批次采购来源（入库 + IQC） |
| GET | /mes/wm/batch/sales-targets | 批次销售去向（出库 + OQC） |
| GET | /mes/wm/batch/process-trace | 批次工序流转（产出/投入） |
| GET | /mes/wm/batch/get-by-sn | SN 反查批次 |