消费者扫码访问事件与统计 - 前端联调方案
涉及页面
- H5 消费者溯源查询页（仅由后端自动记录访问事件）
- MES 管理端消费者扫码访问统计页
业务流程与数据带入
- 消费者访问 H5 溯源查询接口时，后端使用原始扫码内容解析追溯码。
- 查询成功后记录入口类型和生产批次编号；查询失败时记录失败事件及失败编码。
- 事件记录失败不会影响 H5 溯源查询结果。
- 管理端统计接口按访问时间筛选；分布接口仅支持
sourceType、success、channel、province、city、batchId 六个固定维度，不允许传入任意数据库字段。
channel 根据 User-Agent 归类为微信、支付宝或浏览器；province、city 根据客户端 IP 归属地解析，解析不到时展示“未知”。
API
H5 溯源查询（已有接口，新增事件记录）
| 方法 |
路径 |
说明 |
| GET |
/public/mes/trace/query |
查询追溯信息，同时记录成功或失败访问事件 |
请求参数 code 为追溯码或包含 code 参数的二维码 URL。事件记录失败时接口仍按原有规则返回查询结果或业务错误。
管理端汇总
| 方法 |
路径 |
权限 |
| GET |
/mes/trace-consumer-scan/summary |
mes:trace-consumer-scan:query |
可选参数：startTime、endTime，格式为 yyyy-MM-dd HH:mm:ss，统计范围为开始时间（含）至结束时间（不含）。
响应字段：total 总访问次数、success 成功次数、failed 失败次数、uniqueBatchCount 时间范围内 batch_id 非空的去重批次数量。该口径与 batchId 分布中的非“未知”分组数量一致。
管理端趋势
| 方法 |
路径 |
权限 |
| GET |
/mes/trace-consumer-scan/trend |
mes:trace-consumer-scan:query |
可选参数同汇总。响应为数组，字段包括 date、total、success、failed。
管理端分布
| 方法 |
路径 |
权限 |
| GET |
/mes/trace-consumer-scan/distribution |
mes:trace-consumer-scan:query |
请求参数：
| 参数 |
类型 |
必填 |
允许值 |
说明 |
groupBy |
String |
是 |
sourceType、success、channel、province、city、batchId |
分组维度；后端采用固定白名单映射，非法值拒绝 |
startTime |
DateTime |
否 |
yyyy-MM-dd HH:mm:ss |
开始时间（含） |
endTime |
DateTime |
否 |
yyyy-MM-dd HH:mm:ss |
结束时间（不含） |
响应数组字段：name 分组名称、count 访问次数。空值分组名称返回“未知”。
字段展示规则
| 字段 |
展示位置 |
说明 |
total、success、failed、uniqueBatchCount |
汇总卡片 |
展示访问总量、成功/失败量及非空批次去重数量 |
date、total、success、failed |
趋势图 |
后端已补齐查询区间内无数据日期，数值为 0 |
name、count |
分布图/表格 |
根据选择的固定分组维度展示 |
业务规则说明
| 场景 |
规则 |
| 成功查询 |
记录 success=1、入口类型、渠道、省份、城市及批次编号 |
| 追溯码为空或不存在 |
记录 success=0 和失败编码 |
| 记录事件异常 |
仅记录后端日志，不改变溯源接口返回结果 |
| IP 与 User-Agent |
IP 与 User-Agent 仅保存 SHA-256 摘要；渠道、省份、城市只保存归类/归属地名称 |
| 分组参数 |
后端只接受固定白名单值，非法值返回参数错误 |
前端页面接入
菜单与路由
- 菜单已初始化（
sql/mysql/mes_trace_consumer_scan_menu.sql），挂在 MES 系统(5100) 下，页面路径 mes/trace-consumer-scan/index，组件名建议 MesTraceConsumerScan。
- 页面查询权限标识：
mes:trace-consumer-scan:query。登录用户需被授予该权限才能看到菜单并调用接口。
- 统计接口统一路径前缀
/mes/trace-consumer-scan，共三个：/summary、/trend、/distribution。
页面区块建议
| 区块 |
数据来源 |
展示建议 |
| 汇总卡片 |
/summary |
总访问、成功、失败、非空批次去重数 |
| 趋势图 |
/trend |
按日折线/柱状，展示总量与成功/失败；后端已补齐无数据日期为 0 |
| 分布图 |
/distribution |
按 sourceType/success/channel/province/city/batchId 切换分组，展示名称与访问量 |
时间范围交互
- 三个接口均可选传
startTime/endTime（格式 yyyy-MM-dd HH:mm:ss），范围左闭右开。
- 页面提供默认时间范围（如近 30 天），由前端在请求时传入；不传则后端按已有数据区间统计。
空数据处理
trend 空数据时返回补 0 的日期序列，前端直接渲染即可。distribution 空数据时返回空数组，页面展示"暂无扫码数据"。province/city 解析不到时分组名为"未知"。
注意事项
- 需要先执行
sql/mysql/mes_trace_consumer_scan_event.sql 创建事件表。
- 需要执行
sql/mysql/mes_trace_consumer_scan_menu.sql 初始化菜单权限（若使用 ruoyi-vue-pro 等其它库，注意同步表结构）。
- 管理端页面需要根据权限控制菜单和接口访问。
- 统计接口的时间参数应使用后端约定格式，结束时间不包含边界时刻。
- 不需要新增前端上传或事件写入接口。
