|
|
@@ -74,6 +74,8 @@ curl -X POST https://pharmacopoeia.kailin.com.cn/api/v1/analytics/events \
|
|
|
|
|
|
## 二、标准事件类型定义
|
|
|
|
|
|
+> 以下为推荐约定，**接入方也可使用任意自定义 `event_type`**（后端原样存储，超长截断至 64 字符）。自定义类型会出现在 `GET /event-types` 与事件列表中，可正常查询；但概览看板的 `page_views / searches / ai_qa` 等聚合指标按固定类型统计，自定义类型不纳入。
|
|
|
+
|
|
|
### 页面行为
|
|
|
|
|
|
| event_type | 触发时机 | event_data |
|
|
|
@@ -120,6 +122,10 @@ curl -X POST https://pharmacopoeia.kailin.com.cn/api/v1/analytics/events \
|
|
|
| `api_call` | 任意 API 调用完成 | `{url: "/api/v1/chat/stream", method: "POST", status: 200, elapsed_ms: 342}` |
|
|
|
| `api_call` | API 调用失败 | `{url: "/api/v1/drug/search", method: "GET", status: 0, elapsed_ms: 5000, error: "network_error"}` |
|
|
|
|
|
|
+> **服务端已自动埋点，前端勿重复拦截**：本后端对所有 `/api/**` 入站请求（`/api/v1/analytics/events` 自身除外）已由服务端 `ApiTrackingFilter` 自动记录一条 `api_call`（`system` 固定为 `AI药典`，`url` 为相对路径）。因此：
|
|
|
+> - 调用**本后端 API** 的 `api_call` 已被自动覆盖，前端**不要再拦截 fetch 重复上报**，否则同一请求会产生两份记录（client 绝对 URL + server 相对路径，难以去重）。
|
|
|
+> - 下文「自动拦截 fetch」示例**仅适用于**追踪「调用接入方自家后端 / 外部资源」的请求；对本后端 API 不要启用。
|
|
|
+
|
|
|
---
|
|
|
|
|
|
## 三、来源系统（system）
|
|
|
@@ -225,3 +231,43 @@ track('custom_event', { key1: 'value1', key2: 'value2' });
|
|
|
4. **user_key** — 建议前端传 JWT Token（`Authorization: Bearer xxx`），后端自动提取用户标识；不传则记为 `anonymous`
|
|
|
5. **event_data** — 建议始终传 `{}` 而非 `null`，方便后端统一处理
|
|
|
6. **page_url** — 建议传完整 URL，方便分析不同页面的行为分布
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 六、限流与错误响应
|
|
|
+
|
|
|
+埋点写入接口按来源 IP 限流，默认 **600 次/分钟**（后端配置项 `rate-limit.analytics-per-minute`，可调整）。超出阈值返回 429，响应体**不是** `{code, message, data}` 形状：
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "error": "请求过于频繁，请稍后再试",
|
|
|
+ "detail": "请求过于频繁，请稍后再试",
|
|
|
+ "code": 429
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+> 接入方需单独处理 429：埋点丢失不应影响业务，建议失败指数退避重试，并控制上报频率在阈值内；如需集中回补大量历史事件，请联系后端临时调参。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 七、第三方接入须知
|
|
|
+
|
|
|
+本接口定位为「多业务系统共用的行为埋点 sink」。第三方接入前请知悉以下限制，部分为**当前未实现、属待办**（见末尾清单）：
|
|
|
+
|
|
|
+### 1. 用户标识（user_key）
|
|
|
+`user_key` 由后端从**本系统 JWT** 提取；埋点接口走 `permitAll`，**不经过鉴权**，因此第三方传入的 Token 不会被校验或解析，第三方事件会记为 `anonymous`。如需按用户分群，请把用户标识放进 `event_data`（如 `{user_id: "xxx"}`）——但该标识**不会进入 `dimension=user` 维度统计**（该维度基于服务端提取的 `user_key`）。
|
|
|
+
|
|
|
+### 2. 来源系统（system）无白名单
|
|
|
+`system` 为自由文本，仅截断至 64 字符，**后端不做取值校验**。任意调用方都能以 `system:"中医"` 等名义写入事件，存在被冒名灌脏数据的风险。建议接入方约定稳定系统名并知悉该风险。
|
|
|
+
|
|
|
+### 3. 接口无鉴权（安全风险）
|
|
|
+埋点接口 `permitAll` + CORS 回射任意 Origin，**无 API Key / 共享密钥**，任何网络方都能写入任意事件。**请勿在 `event_data` 中放置敏感个人信息（PII）、密钥、token 等。**
|
|
|
+
|
|
|
+### 4. event_data 体积
|
|
|
+`event_data` 整块 JSON 原样存储（JSONB），**后端不做体积截断**（仅 `page_url / referrer / user_agent / system / event_type / user_key / ip` 等标量字段截断）。请接入方自行控制单条 `event_data` 大小，避免超大 payload。
|
|
|
+
|
|
|
+### 待办（需后端改造，未含在本文档承诺内）
|
|
|
+- 接入方密钥 / 签名鉴权
|
|
|
+- `system` 取值白名单
|
|
|
+- `event_data` 体积上限校验
|
|
|
+- 第三方 `external_user_id` 字段（接入方自填，进入 `user` 维度统计）
|
liuchengsen