# 消费者扫码访问事件与统计 - 前端联调方案

## 涉及页面

- H5 消费者溯源查询页（仅由后端自动记录访问事件）
- MES 管理端消费者扫码访问统计页

## 业务流程与数据带入

1. 消费者访问 H5 溯源查询接口时，后端使用原始扫码内容解析追溯码。
2. 查询成功后记录入口类型和生产批次编号；查询失败时记录失败事件及失败编码。
3. 事件记录失败不会影响 H5 溯源查询结果。
4. 管理端统计接口按访问时间筛选；分布接口仅支持 `sourceType`、`success`、`channel`、`province`、`city`、`batchId` 六个固定维度，不允许传入任意数据库字段。
5. `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` 等其它库，注意同步表结构）。
- 管理端页面需要根据权限控制菜单和接口访问。
- 统计接口的时间参数应使用后端约定格式，结束时间不包含边界时刻。
- 不需要新增前端上传或事件写入接口。