# P29 埋点与流量看板接口清单

所有接口前缀 `/api/track`。当前站点未接入后端，以下为接口设计稿，字段与错误码用于前后端对齐。

## 1. 埋点上报

`POST /api/track/report`

请求体：

```json
{
  "sessionId": "s-1739xxxx",
  "eventType": "pageview",
  "pageUrl": "/mall",
  "pageTitle": "PCB 商城",
  "refUrl": "https://example.com/",
  "channel": "search",
  "province": "广东",
  "identity": "visitor",
  "extra": { "supplierId": "P-1001", "toolName": "dfm" },
  "ts": 1739xxxxx
}
```

响应：`{ "code": 0, "msg": "ok" }`

规则：

- 单会话同一事件 1 秒内去重
- 缺少 sessionId 直接丢弃，返回 `400 TRACK_SESSION_REQUIRED`
- 上报体超过 32KB 返回 `413 TRACK_PAYLOAD_TOO_LARGE`
- 服务端按 UA 与访问频率标记爬虫，不阻断请求

## 2. 流量总览

`GET /api/track/overview?from=2026-11-01&to=2026-11-16`

响应：

```json
{
  "uv": 12684, "pv": 57321, "sessions": 15230,
  "bounceRate": 0.423, "avgDuration": 186,
  "compare": { "uv": 0.12, "pv": 0.08 }
}
```

## 3. 渠道统计

`GET /api/track/channel/list?from=&to=`

返回各渠道 UV、询价提交量、转化率，按 UV 降序。

## 4. 询价转化漏斗

`GET /api/track/funnel/rfq?from=&to=`

返回阶段数组：进入询价页、填写表单、提交询价、收到报价、成交，含各阶段人数与转化率。

## 5. 工具使用排行

`GET /api/track/tool/rank?from=&to=&limit=10`

返回工具名称、使用次数、占比。

## 6. 供应商热度榜

`GET /api/track/supplier/rank?from=&to=&limit=20`

返回供应商 ID、名称、店铺 UV、咨询次数、报价次数。

## 7. 原始日志查询（管理员）

`GET /api/track/log/list?from=&to=&eventType=&page=1&size=50`

返回日志列表与总数；仅超级管理员可见 IP 明细，运营角色响应中 IP 字段脱敏为省市。

## 8. 黑名单管理

- `GET /api/track/black/list`
- `POST /api/track/black/save` 请求体 `{ "ip": "", "reason": "" }`
- `POST /api/track/black/del` 请求体 `{ "id": 0 }`

## 9. 供应商本店看板

`GET /api/track/supplier/myshop?from=&to=`

返回本店 UV、咨询次数、报价次数、转化率；供应商仅可访问与自己绑定主体关联的数据。

## 10. 错误码

| 码 | 含义 |
| --- | --- |
| 0 | 成功 |
| 400 | 参数缺失或非法 |
| 401 | 未登录 |
| 403 | 无看板权限或越权访问其他主体数据 |
| 413 | 上报体过大 |
| 429 | 上报频率超限 |
| 500 | 服务端异常 |

## 11. 权限矩阵

| 接口 | 超级管理员 | 运营 | 供应商 | 采购 |
| --- | --- | --- | --- | --- |
| report | 是 | 是 | 是 | 是 |
| overview | 是 | 是 | 否 | 否 |
| channel/list | 是 | 是 | 否 | 否 |
| funnel/rfq | 是 | 是 | 否 | 否 |
| tool/rank | 是 | 是 | 否 | 否 |
| supplier/rank | 是 | 是 | 否 | 否 |
| log/list | 是 | 否（脱敏只读） | 否 | 否 |
| black/* | 是 | 否 | 否 | 否 |
| supplier/myshop | 是 | 是 | 仅本店 | 否 |