@ (#111)

docs/api目录文档分类和补全 --------- Co-authored-by: guke <guke@autohome.com.cn> Reviewed-on: #111
2026-07-03 15:00:37 +08:00
parent ee132aa93b
commit a563c1ca4b
102 changed files with 2418 additions and 217 deletions
@@ -0,0 +1,82 @@
+# POST /api/v1/analytics/events — 批量上报埋点事件
+
+> 所属:Analytics 组（前缀 `/api/v1/analytics`） | 鉴权:无（不强制登录，未登录态也要采集行为） | [← 返回 API 索引](../README.md)
+
+批量接收新手引导（及后续）埋点，append 落 `analytics_event` 表。`user_id` 由客户端在 body 可选带上，不靠 Bearer。服务端补 `client_ip`（X-Forwarded-For）与 `server_at`（接收时间）。
+
+## 入参
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `device_id` | string | ✅（≤64） | 设备 ID |
+| `user_id` | int \| null | ❌ | 登录用户 ID（未登录可空） |
+| `sent_at` | int \| null | ❌ | 批次发送时间（epoch ms） |
+| `oem` | string \| null | ❌ | 厂商（如 `Xiaomi`） |
+| `os` | string \| null | ❌ | 操作系统（如 `Android 14`） |
+| `model` | string \| null | ❌ | 机型（如 `24115RA8EC`） |
+| `app_ver` | string \| null | ❌ | App 版本 |
+| `channel` | string \| null | ❌ | 渠道 |
+| `events` | list[object] | ✅（1-200 条） | 事件数组 |
+| `events[].event` | string | ✅（≤64） | 事件名（如 `onboarding_start`） |
+| `events[].client_ts` | int | ✅ | 端事件发生时间（epoch ms） |
+| `events[].session_id` | string \| null | ❌ | 会话 ID |
+| `events[].page` | string \| null | ❌ | 页面标识 |
+| `events[].network` | string \| null | ❌ | 网络类型（如 `wifi`） |
+| `events[].props` | dict | ❌ | 事件属性（key-value） |
+
+Mock 入参:
+```json
+{
+  "device_id": "android_abc123def456",
+  "user_id": 42,
+  "sent_at": 1719993700000,
+  "oem": "Xiaomi",
+  "os": "Android 14",
+  "model": "24115RA8EC",
+  "app_ver": "0.1.5",
+  "channel": "official",
+  "events": [
+    {
+      "event": "onboarding_start",
+      "client_ts": 1719993600000,
+      "session_id": "sess_a1b2c3",
+      "page": "onboarding",
+      "network": "wifi",
+      "props": {"step": "1", "source": "fresh_install"}
+    },
+    {
+      "event": "onboarding_step_complete",
+      "client_ts": 1719993615000,
+      "session_id": "sess_a1b2c3",
+      "page": "onboarding",
+      "network": "wifi",
+      "props": {"step": "1", "duration_ms": "15000"}
+    }
+  ]
+}
+```
+
+## 出参
+
+响应 `200`:`AnalyticsIngestOut`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `ok` | bool | 固定 `true` |
+| `received` | int | 成功写入的条数 |
+
+Mock 出参:
+```json
+{
+  "ok": true,
+  "received": 2
+}
+```
+
+## 错误码
+- `422` `events` 为空或超过 200 条 / 字段类型不符
+
+## 说明
+- `user_id` 不靠 JWT：未登录态也要采集行为（新手引导可能在登录前）
+- 每批最多 200 条，建议客户端攒到一定量再批量上报
+- `client_ts` 是端侧时间（客户端时钟），`server_at` 由服务端补（可靠时间轴）