social-app/docs/protocols/app/analytics-events.md

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

{
  "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

{
  "received": 1,
  "queued": true
}

语义说明：

• received 表示本次接收的事件条数。
• queued=true 表示事件已被服务端接收并触发写入流程；该字段不承诺具体调度方式（请求内写入或队列写入）。

3. Dashboard Login

Endpoint

• Method: POST
• Path: /api/v1/analytics/login

Request Body

{
  "password": "<analytics-password>"
}

Response Body

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