147 lines
3.4 KiB
Markdown
147 lines
3.4 KiB
Markdown
|
# 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` 内部字段）。
|
||
|
|
- 不允许移除现有必填字段或修改既有字段语义；若必须变更，需新增版本化协议文档并提供迁移说明。
|