编辑 | blame | 历史 | 原始文档

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 不变

响应示例(未绑定批次)

{
  "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,前端沿用原有错误提示,不需要改动。
  • 本次为**放宽**校验,不影响已绑定批次的历史数据,接口向后兼容。