feat: 添加 Analytics 分析功能（行为追踪、错误码、协议更新）

2026-04-02 11:52:23 +08:00
parent b101826de5
commit 7b6dbe72c3
24 changed files with 682 additions and 52 deletions
@@ -0,0 +1,146 @@
+# Analytics Events And Dashboard Protocol
+
+本文档定义 analytics 采集与查询协议，覆盖移动端/前端事件上报、Dashboard 登录与按日数据读取。
+
+## 1. Scope
+
+- 事件写入接口：`POST /api/v1/analytics/events`
+- Dashboard 登录接口：`POST /api/v1/analytics/login`
+- 按日数据读取接口：`GET /api/v1/analytics/data/{YYYY-MM-DD}`
+- 存储介质：服务端 JSONL 文件（由 `SOCIAL_ANALYTICS__DATA_PATH` 指定）
+
+## 2. Event Ingestion
+
+### Endpoint
+
+- Method: `POST`
+- Path: `/api/v1/analytics/events`
+
+### Request Body
+
+```json
+{
+  "client_time": "2026-04-02T10:00:00Z",
+  "sdk_version": "1.0.0",
+  "events": [
+    {
+      "event_id": "evt-1",
+      "event_type": "page_view",
+      "timestamp": "2026-04-02T10:00:00Z",
+      "user_id": "user-1",
+      "device_id": "device-1",
+      "session_id": "session-1",
+      "platform": "android",
+      "app_version": "0.1.2",
+      "app_build": "5",
+      "env": "prod",
+      "page_name": "home",
+      "trace_id": "trace-1",
+      "request_id": "request-1",
+      "attributes": {
+        "from": "banner"
+      },
+      "metrics": {
+        "latency_ms": 123
+      },
+      "context": {
+        "network_type": "wifi",
+        "os_version": "Android 14",
+        "device_model": "Pixel",
+        "locale": "zh-CN",
+        "timezone": "Asia/Shanghai"
+      }
+    }
+  ]
+}
+```
+
+### Response Body
+
+```json
+{
+  "received": 1,
+  "queued": true
+}
+```
+
+语义说明：
+
+- `received` 表示本次接收的事件条数。
+- `queued=true` 表示事件已被服务端接收并触发写入流程；该字段不承诺具体调度方式（请求内写入或队列写入）。
+
+## 3. Dashboard Login
+
+### Endpoint
+
+- Method: `POST`
+- Path: `/api/v1/analytics/login`
+
+### Request Body
+
+```json
+{
+  "password": "<analytics-password>"
+}
+```
+
+### Response Body
+
+```json
+{
+  "success": true,
+  "data_base_url": "/api/v1/analytics/data",
+  "token": "<bearer-token>"
+}
+```
+
+语义说明：
+
+- `token` 为短时效 Bearer Token。
+- `data_base_url` 为前端读取按日数据的基路径。
+
+## 4. Read Daily Data
+
+### Endpoint
+
+- Method: `GET`
+- Path: `/api/v1/analytics/data/{date}`
+- Header: `Authorization: Bearer <token>`
+- `date` 格式要求：`YYYY-MM-DD`
+
+### Success Response
+
+- Status: `200`
+- Content-Type: `application/x-ndjson`
+- Body: 当日 JSONL 文本（每行一个事件 JSON）
+
+## 5. Error Contract
+
+错误响应必须遵循 RFC7807 + 稳定错误码规范，错误码注册表见：
+
+- `docs/protocols/common/http-error-codes.md`
+
+analytics 相关错误码包括：
+
+- `ANALYTICS_LOGIN_PASSWORD_INVALID`
+- `ANALYTICS_AUTH_HEADER_MISSING`
+- `ANALYTICS_AUTH_SCHEME_INVALID`
+- `ANALYTICS_AUTH_TOKEN_MISSING`
+- `ANALYTICS_TOKEN_MALFORMED`
+- `ANALYTICS_TOKEN_SIGNATURE_INVALID`
+- `ANALYTICS_TOKEN_PAYLOAD_INVALID`
+- `ANALYTICS_TOKEN_EXPIRED`
+- `ANALYTICS_DATE_FORMAT_INVALID`
+- `ANALYTICS_FILE_NOT_FOUND`
+
+## 6. Storage Contract
+
+- 后端写入路径由 `SOCIAL_ANALYTICS__DATA_PATH` 控制，默认：`backend/data/analytics`。
+- 按日存储文件名：`{YYYY-MM-DD}.jsonl`。
+- 生产部署推荐将宿主机目录挂载到容器内该路径，避免容器重建导致数据丢失。
+
+## 7. Compatibility Strategy
+
+- 策略：**backward-compatible additive change**。
+- 允许在事件对象中新增可选字段（`attributes` / `metrics` / `context` 内部字段）。
+- 不允许移除现有必填字段或修改既有字段语义；若必须变更，需新增版本化协议文档并提供迁移说明。