批次追溯统一聚合接口 - 前端联调方案

涉及页面

MES → 质检 → 批次追溯（/qc/batch-trace）
批次追溯详情
批次码、托盘码、袋码扫码追溯入口

业务流程与数据带入

在批次追溯列表输入生产批次码、临时批次码、袋码或托盘码。
页面调用统一详情接口，后端将入口码解析到生产批次，并聚合生产、质检、仓储、销售和防伪信息。
详情页以生产批次为根展示全链路数据；袋码和托盘信息来自生产赋码数据，仓储与销售信息来自仓储业务数据。
前向追溯展示当前批次产出的下游批次；后向追溯展示当前批次消耗的上游批次。
时间线、阶段视图和决策摘要均使用同一次聚合响应，避免打开详情后重复请求多个旧接口。

API

方法	路径	说明
GET	`/mes/trace/batch/detail`	查询统一批次追溯详情

请求参数

参数	类型	必填	说明
`code`	String	是	生产批次码、临时批次码、袋码或托盘码

示例：code=BAG-202608280001

响应主要字段

字段	类型	说明
`sourceType`	String	入口类型：`BAG`、`PALLET`、`BATCH`
`requestCode`	String	原始输入码
`itemCode` / `itemName`	String	品种编码、名称
`itemSpecification`	String	品种规格
`batchCode` / `tempCode`	String	正式批次号、临时批次码
`batchStatusName`	String	批次状态名称
`produceDate`	DateTime	生产日期
`lineCode` / `lineName`	String	产线编码、名称
`ownerUserName`	String	生产责任人
`planQuantity`	Decimal	计划数量
`bagQuantity` / `palletQuantity`	Integer	袋码数量、托盘数量
`workers`	Array	生产人员
`pallets`	Array	托盘摘要
`bagTotal` / `bags`	Long / Array	袋码总数及最多 100 条明细
`inbound`	Object	最新入库事件
`quality`	Object	种子质量检验与指标
`antiFake`	Object	当前追溯码扫码次数、首次和最近扫码时间
`purchaseSources`	Array	采购来源、供应商和 IQC 信息
`salesTargets`	Array	销售出库、客户和 OQC 信息
`processTraces`	Array	工序投入、产出流转信息

响应示例

{
  "code": 0,
  "data": {
    "sourceType": "BAG",
    "requestCode": "BAG-202608280001",
    "batchCode": "B20260828001",
    "itemName": "示例品种",
    "batchStatusName": "已完成",
    "workers": [],
    "pallets": [],
    "bags": [],
    "purchaseSources": [],
    "salesTargets": [],
    "processTraces": []
  }
}

页面展示规则

视图	展示内容
阶段总览	来源、生产、质检、赋码、入库、销售、消费、防伪八个阶段的状态和数量
全链路时间线	按时间展示采购、生产、质检、赋码、入库、出库和扫码事件；异常状态优先高亮
流动图谱	以批次、工序、仓库、托盘、袋码、销售单和客户为节点；默认展示批次级关系
决策分析	展示质量结论、库存数量、销售去向、防伪扫码次数和窜货风险
采购来源	展示采购入库、供应商、采购订单、IQC 单号及检验结论
销售去向	展示销售出库、客户、销售订单、OQC 单号及质量状态
工序流转	`IN` 显示为投入，`OUT` 显示为产出

业务规则

输入袋码或托盘码时，详情仍以其所属生产批次为根进行聚合。
当前接口返回的袋码明细最多 100 条，bagTotal 用于展示完整数量；大批次不得按明细数量判断总量。
空数组表示该业务阶段暂无记录；quality、inbound、antiFake 为空表示暂无对应信息。
防伪扫码统计仅用于展示，不能替代质量检验结论或出库状态。
客户、供应商、操作人等名称应以接口返回值为准，不在前端重复查询旧批次接口。

注意事项

管理端接口需要批次追溯查询权限：mes:trace-batch:query。
旧的 /mes/wm/batch/* 接口继续供仓储批次页面使用，批次追溯页面切换后不应再并行请求旧的五个详情接口。
后续扩展时间线和图谱时，建议后端增加分页与节点层级参数，避免一次性加载全部袋码。
展示消费者扫码信息时不得展示 IP 地址和 User-Agent 原文。