宁夏三级mom后端
编辑 | blame | 历史 | 原始文档

防伪防窜货管理 - 前端联调方案

涉及页面

  • 窜货预警管理页（新增菜单：防伪防窜货管理 → 窜货预警）
  • 扫码地理分布页（复用消费者扫码统计接口）
  • 数据完整性校验页（新增菜单：防伪防窜货管理 → 数据完整性校验）
  • 消费者溯源 H5 页面（正品验证信息展示增强）

业务流程与数据带入

  1. 窜货预警的产生：消费者扫码溯源成功后，后端自动比对「扫码 IP 归属地」与「袋码出库经销商地区」；不一致时自动生成预警记录。预警无需前端触发，只需提供查询、处理、统计入口。
  2. 预警 → 明细：窜货预警分页列表中，可查看预警涉及的袋码/托盘码、批次号、经销商、扫码地区、预警类型与状态。
  3. 完整性校验的入口：数据完整性校验页输入「业务类型 + 业务编号」发起校验。业务编号可从对应业务列表（批次 / 出库单 / 扫码事件）带入，避免手工填写。
  4. H5 正品验证：溯源接口响应新增 antiFake 区块，展示该追溯码累计扫码次数、首次/最近扫码时间，帮助消费者识别被多次扫描的疑似复制码。

API

1. 窜货预警

方法 路径 说明 权限
GET /mes/trace-cross-region/page 窜货预警分页 mes:trace-cross-region:query
PUT /mes/trace-cross-region/handle 处理预警（已处理/误报） mes:trace-cross-region:handle
GET /mes/trace-cross-region/summary 预警汇总（总数/待处理/跨省/跨市） mes:trace-cross-region:query
GET /mes/trace-cross-region/statistics 预警分布统计（按省份/经销商/物料等分组） mes:trace-cross-region:query
GET /mes/trace-cross-region/config 查询判定规则配置 mes:trace-cross-region:query
PUT /mes/trace-cross-region/config 更新判定规则（省/市粒度切换） mes:trace-cross-region:handle

GET /page 请求参数：

参数 类型 必填 说明
status Integer 否 状态：10 待处理 / 20 已处理 / 30 误报
warningType String 否 预警类型：CROSS_PROVINCE / CROSS_CITY
batchId Long 否 批次编号
batchCode String 否 批次号（模糊）
bagCode String 否 袋码（模糊）
clientId Long 否 经销商编号
clientName String 否 经销商名称（模糊）
eventTime[] LocalDateTime[] 否 预警产生时间范围

| pageNo / pageSize | - | 否 | 分页参数 |

GET /page 响应字段：

字段 类型 说明
warningNo String 预警编号
bagCode / palletCode String 袋码 / 托盘码
batchCode String 批次号
itemName String 物料名称
salesCode String 出库单号
clientName String 经销商名称
dealerProvince / dealerCity String 经销商省份 / 城市
scanProvince / scanCity String 扫码省份 / 城市
warningType / warningTypeName String 预警类型 / 类型名称
status / statusName Integer / String 状态 / 状态名称
handleRemark String 处理备注
handleUserName String 处理人姓名
handleTime / eventTime LocalDateTime 处理时间 / 预警产生时间

PUT /handle 请求体：

参数 类型 必填 说明
id Long 是 预警编号
status Integer 是 处理状态：20 已处理 / 30 误报
handleRemark String 否 处理备注

GET /summary 请求参数： startTime、endTime（可选，LocalDateTime，格式 yyyy-MM-dd HH:mm:ss）

GET /summary 响应字段：

字段 类型 说明
total / pending / handled / falseAlarm Long 总数 / 待处理 / 已处理 / 误报
crossProvince / crossCity Long 跨省预警数 / 跨市预警数

GET /statistics 请求参数：

参数 类型 必填 说明
groupBy String 是 分组维度：scanProvince / scanCity / clientId / itemId / batchId
startTime / endTime LocalDateTime 否 时间范围

GET /statistics 响应字段： name（分组名）、count（数量），按数量倒序。

GET /config 响应字段： warningLevel（PROVINCE 跨省 / CITY 跨市）、remark。

PUT /config 请求参数： warningLevel（必填，仅支持 PROVINCE / CITY）。

2. 数据完整性校验

方法 路径 说明 权限
GET /mes/trace-integrity/verify 校验数据完整性（重算摘要比对） mes:trace-integrity:verify
GET /mes/trace-integrity/page 完整性记录分页 mes:trace-integrity:query

GET /verify 请求参数：

参数 类型 必填 说明
bizType String 是 业务类型：BATCH 批次 / SALES 销售出库 / SCAN 消费者扫码
bizId Long 是 业务记录编号

GET /verify 响应字段：

字段 类型 说明

| bizType / bizId / bizCode | - | 业务类型 / 编号 / 编码 |
| matched | Boolean | 是否校验通过 |
| storedHash | String | 存储的摘要 SHA-256 |
| currentHash | String | 当前数据重算摘要 SHA-256 |
| bagSetHash | String | 仅 BATCH 校验返回：批次当前袋码集合摘要（供人工比对袋码防篡改） |
| message | String | 校验说明 |

GET /page 请求参数： bizType、bizId、bizCode（均可选）。

GET /page 响应字段： id、bizType、bizId、bizCode、contentHash、eventTime。

3. 消费者溯源 H5 响应新增区块

溯源接口（/public/mes/trace/query）响应新增 antiFake 区块（有扫码记录才返回）：

字段 类型 说明
antiFake.scanCount Long 该追溯码累计扫码次数
antiFake.firstScanTime LocalDateTime 首次扫码时间
antiFake.lastScanTime LocalDateTime 最近扫码时间

字段展示规则

字段 展示位置 说明
预警类型 窜货预警列表、详情 CROSS_PROVINCE=跨省 / CROSS_CITY=跨市
状态 窜货预警列表、详情 待处理 / 已处理 / 误报，列表建议按状态着色
经销商 vs 扫码地区 窜货预警详情 两列对比展示，异常字段高亮
处理备注 窜货预警详情 处理时可填写
matched 数据完整性校验页 校验结果，通过显示绿色、不通过显示红色并给出两个摘要值

业务规则说明

场景 规则
判定粒度 管理端可在 PROVINCE（跨省）与 CITY（跨市）间切换；CITY 粒度下若扫码市与经销商市都为空则退回省级判断
不产生预警的情况 批次码入口扫码、扫码无地区（IP 解析失败）、袋码未出库、经销商无地区信息
预警处理 仅「待处理」状态可处理为「已处理」或「误报」；处理后不可再次处理
完整性覆盖范围 只校验不可变核心字段，正常业务流转（草稿→生产中→完成、出库后状态更新）不会导致校验误报
未生成摘要 若业务数据未生成过摘要（如历史数据），verify 返回"数据完整性记录不存在"错误码

注意事项

  • 窜货预警分页的 eventTime 传两个值（eventTime[0] 起、eventTime[1] 止）表示时间范围。
  • statistics 的 groupBy 只能传白名单内的维度，传其他值后端会拒绝。
  • 数据完整性校验的业务编号建议从对应列表带入，SCAN 类型的 bizId 为消费者扫码事件主键，可在扫码统计记录中查看。
  • 消费者 H5 端 antiFake 区块无扫码记录时不返回该字段，前端需做空值兜底。
  • 窜货预警、完整性校验菜单需后端执行菜单 SQL 后才会在管理后台可见。