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

## 涉及页面

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

## 业务流程与数据带入

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

## 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 | 工序投入、产出流转信息 |

### 响应示例

```json
{
  "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 原文。