# H5 溯源「未绑定批次也可扫码」- 前端联调说明

## 背景

袋码 / 托盘码在生成后、录入生产批次前，是一个「已印制、未投产」的中间态。此前该状态下调用溯源查询接口会直接返回错误码 `1040760000`（未查询到该追溯码），消费者扫到这类包装时无法查看任何信息。

本次调整：**未绑定批次的袋码 / 托盘码同样可以扫码成功**，接口正常返回该码对应的**品种信息**，并新增 `batchBound` 字段标识批次是否已录入，由前端提示「尚未绑定批次」。追溯码本身不存在时，行为不变，仍返回 `1040760000`。

## 涉及接口

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /public/mes/trace/query?code={追溯码} | H5 溯源查询（免登录） |

## 响应新增字段

| 字段 | 类型 | 说明 |
|------|------|------|
| batchBound | Boolean | 是否已录入生产批次。`true` 已绑定（批次区块字段正常返回）；`false` 未绑定，此时**仅** `itemCode` / `itemName` / `itemSpecification` / `itemUnitMeasureName`、`sourceType`、`requestCode`、`antiFake`、`timeline`、`decision` 有值，其余批次相关字段全部为 `null` |

**字段位置：** `requestCode` 之后，`itemCode` 之前。

## 变更前后对比

| 场景 | 变更前 | 变更后 |
|------|--------|--------|
| 袋码已生成、未录入批次 | `code=1040760000`，`data=null`，无法展示任何信息 | `code=0`，`batchBound=false`，返回品种信息，前端提示未绑定批次 |
| 托盘已生成、未录入批次 | 同上 | 同上，品种取托盘内**任一袋码**的品种 |
| 追溯码不存在 | `code=1040760000` | 不变 |

## 响应示例（未绑定批次）

```json
{
  "code": 0,
  "data": {
    "sourceType": "BAG",
    "requestCode": "BAG-00000153",
    "batchBound": false,
    "itemCode": "ITEM_20260917003",
    "itemName": "吨",
    "itemSpecification": null,
    "itemUnitMeasureName": "吨袋子",
    "batchCode": null,
    "tempCode": null,
    "batchStatus": null,
    "batchStatusName": null,
    "produceDate": null,
    "lineCode": null,
    "lineName": null,
    "ownerUserId": null,
    "ownerUserName": null,
    "planQuantity": null,
    "bagQuantity": null,
    "palletQuantity": null,
    "inboundTime": null,
    "remark": null,
    "workers": null,
    "palletCount": null,
    "pallets": null,
    "bagTotal": null,
    "bags": null,
    "inbound": null,
    "quality": null,
    "antiFake": {
      "scanCount": 0,
      "firstScanTime": null,
      "lastScanTime": null
    },
    "purchaseSources": null,
    "salesTargets": null,
    "seedFlows": null,
    "processTraces": null,
    "timeline": [],
    "decision": {
      "qualityRisk": false,
      "inboundQuantity": null,
      "salesTargetCount": 0,
      "consumerScanCount": 0,
      "riskLevel": "NORMAL"
    }
  }
}
```

## 页面展示规则

### 追溯查询区块

| 字段 | 绑定批次（`batchBound=true`） | 未绑定批次（`batchBound=false`） |
|------|------------------------------|--------------------------------|
| 品种名称 | `itemName` + `itemSpecification` 空格拼接 | 同左 |
| 计量单位 | `itemUnitMeasureName` | 同左 |
| 生产经营者 | 页面常量 `COMPANY_NAME` | 同左 |
| 单元识别代码 | `requestCode` → `batchCode` → `tempCode` 依次回退 | `requestCode` |
| 追溯网址 | 页面常量 `TRACE_URL` | 同左 |
| 追溯类型 | `sourceType` | 同左 |
| 批次号 | `batchCode` | **不展示**，替换为提示文案 |
| 生产日期 | `produceDate` | **不展示** |
| 产线 | `lineName`，为空回退 `lineCode` | **不展示** |

**未绑定批次时的提示文案（替代批次号 / 生产日期 / 产线三行）：**

> 该追溯码尚未录入生产批次，批次号、生产日期、产线等信息待完善；当前展示该码对应的品种信息。

### 防伪查询区块

- `batchCode` 有值时，`对应批次` 行展示批次号。
- `batchCode` 为空（即未绑定批次）时，`对应批次` 行展示「尚未绑定批次」，并以弱化 / 警示样式区分，避免被误读为「无数据」。

## 注意事项

- `batchBound` 是**唯一**判断批次是否已录入的字段，前端不要用 `batchCode == null` 推断（历史数据中同样存在批次号为空但批次已绑定的边界情况）。
- 未绑定批次时，`bags` / `pallets` / `workers` / `quality` 等区块均为 `null`（不是空数组），前端渲染前需判空。
- 未绑定批次的扫码**同样会**计入防伪查询次数（`antiFake.scanCount`）与消费者扫码事件，逻辑与正常扫码一致。
- 托盘的品种取「托盘内任一袋码」的品种。理论上同一托盘的袋码品种一致；若出现不一致（数据异常），展示的品种可能与实际不符，属可接受的降级表现。
- 追溯码本身不存在时仍返回 `code=1040760000`，前端沿用原有错误提示，不需要改动。
- 本次为**放宽**校验，不影响已绑定批次的历史数据，接口向后兼容。