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