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

概述

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

采购来源：从批次反查采购入库单 + IQC 质检结论（原料侧断链打通）
销售去向：从批次反查销售出库单 + OQC 质检结论（成品侧断链打通）
工序流转：从批次查看产出/投入的工序级事件（无需建表，动态聚合）
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	是	批次编码

响应：

{
  "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	是	批次编码

响应：

{
  "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	是	批次编码

响应：

{
  "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：

{
  "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` 作为详情弹窗查询依据（或直接使用返回数据）

五、接口调用时序

追溯页加载批次列表（/mes/wm/batch/page）
点击某批次行 → 打开详情弹窗，弹窗内默认展示"生产"页签（向前/向后追溯）
切换"采购来源/销售去向/工序流转"页签时，按需调用对应接口（建议懒加载：首次切换才请求）
顶部 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 反查批次