# Presence Service API 文档

## 概述

Base URL: `/api/v1`

所有需要认证的接口都需要在请求头中携带 JWT Token：
```
Authorization: Bearer <token>
```

---

## 1. 在线状态 API

### 1.1 记录心跳

记录用户心跳，更新在线状态。

**请求**

```
POST /api/v1/presence/heartbeat
Authorization: Bearer <token>
Content-Type: application/json
```

**请求体**

| 字段 | 类型 | 必填 | 描述 |
|-----|------|-----|------|
| installId | string | 是 | 安装ID (8-64字符) |
| appVersion | string | 是 | 应用版本号 |
| clientTs | number | 是 | 客户端时间戳 (Unix秒) |

**请求示例**

```json
{
  "installId": "uuid-xxxx-xxxx-xxxx",
  "appVersion": "1.0.0",
  "clientTs": 1732685100
}
```

**响应**

```json
{
  "ok": true,
  "serverTs": 1732685100123
}
```

| 字段 | 类型 | 描述 |
|-----|------|------|
| ok | boolean | 是否成功 |
| serverTs | number | 服务器时间戳 (Unix毫秒) |

**错误码**

| HTTP 状态码 | 错误码 | 描述 |
|------------|-------|------|
| 400 | VALIDATION_ERROR | 参数校验失败 |
| 401 | UNAUTHORIZED | 未授权 |

---

### 1.2 查询在线人数

查询当前在线用户数量。

**请求**

```
GET /api/v1/presence/online-count
Authorization: Bearer <token>
```

**查询参数**

| 参数 | 类型 | 必填 | 默认值 | 描述 |
|-----|------|-----|-------|------|
| windowSeconds | number | 否 | 180 | 时间窗口 (秒) |

**响应**

```json
{
  "count": 12345,
  "windowSeconds": 180,
  "queriedAt": "2025-01-01T12:00:00.000Z"
}
```

| 字段 | 类型 | 描述 |
|-----|------|------|
| count | number | 在线用户数 |
| windowSeconds | number | 统计时间窗口 |
| queriedAt | string | 查询时间 (ISO 8601) |

---

### 1.3 查询在线人数历史

查询指定时间范围内的在线人数历史快照。

**请求**

```
GET /api/v1/presence/online-history
Authorization: Bearer <token>
```

**查询参数**

| 参数 | 类型 | 必填 | 默认值 | 描述 |
|-----|------|-----|-------|------|
| startTime | string | 是 | - | 开始时间 (ISO 8601) |
| endTime | string | 是 | - | 结束时间 (ISO 8601) |
| interval | string | 否 | 5m | 聚合间隔: 1m, 5m, 15m, 30m, 1h |

**响应**

```json
{
  "data": [
    {
      "ts": "2025-01-01T12:00:00.000Z",
      "count": 12345
    },
    {
      "ts": "2025-01-01T12:05:00.000Z",
      "count": 12400
    }
  ],
  "interval": "5m",
  "startTime": "2025-01-01T12:00:00.000Z",
  "endTime": "2025-01-01T13:00:00.000Z",
  "total": 12,
  "summary": {
    "max": 12500,
    "min": 12000,
    "avg": 12250
  }
}
```

| 字段 | 类型 | 描述 |
|-----|------|------|
| data | array | 快照数据列表 |
| data[].ts | string | 快照时间 |
| data[].count | number | 在线人数 |
| interval | string | 聚合间隔 |
| startTime | string | 实际开始时间 |
| endTime | string | 实际结束时间 |
| total | number | 数据点总数 |
| summary.max | number | 最大在线人数 |
| summary.min | number | 最小在线人数 |
| summary.avg | number | 平均在线人数 |

**错误码**

| HTTP 状态码 | 错误码 | 描述 |
|------------|-------|------|
| 400 | INVALID_TIME_RANGE | 无效的时间范围 |
| 400 | INVALID_INTERVAL | 无效的聚合间隔 |

---

## 2. 分析事件 API

### 2.1 批量上报事件

批量上报客户端分析事件。

**请求**

```
POST /api/v1/analytics/events
Content-Type: application/json
```

**请求体**

| 字段 | 类型 | 必填 | 描述 |
|-----|------|-----|------|
| events | array | 是 | 事件列表 |
| events[].eventName | string | 是 | 事件名称 (字母开头，1-64字符) |
| events[].installId | string | 是 | 安装ID |
| events[].userId | string | 否 | 用户ID (已登录用户) |
| events[].clientTs | number | 是 | 客户端时间戳 (Unix秒) |
| events[].properties | object | 否 | 事件属性 |

**请求示例**

```json
{
  "events": [
    {
      "eventName": "app_session_start",
      "installId": "uuid-xxxx-xxxx-xxxx",
      "userId": "12345",
      "clientTs": 1732685100,
      "properties": {
        "os": "iOS",
        "osVersion": "17.0",
        "appVersion": "1.0.0",
        "deviceModel": "iPhone 15 Pro",
        "province": "广东省",
        "city": "深圳市"
      }
    },
    {
      "eventName": "presence_heartbeat",
      "installId": "uuid-xxxx-xxxx-xxxx",
      "clientTs": 1732685160
    }
  ]
}
```

**响应**

```json
{
  "accepted": 2,
  "failed": 0,
  "errors": []
}
```

| 字段 | 类型 | 描述 |
|-----|------|------|
| accepted | number | 成功接收的事件数 |
| failed | number | 失败的事件数 |
| errors | array | 错误详情列表 |

**预定义事件名称**

| 事件名称 | 描述 |
|---------|------|
| app_session_start | 应用会话开始 |
| app_session_end | 应用会话结束 |
| presence_heartbeat | 心跳事件 |
| user_login | 用户登录 |
| user_logout | 用户登出 |

---

### 2.2 查询日活统计

查询指定日期范围的日活统计数据。

**请求**

```
GET /api/v1/analytics/dau
Authorization: Bearer <token>
```

**查询参数**

| 参数 | 类型 | 必填 | 描述 |
|-----|------|-----|------|
| startDate | string | 是 | 开始日期 (YYYY-MM-DD) |
| endDate | string | 是 | 结束日期 (YYYY-MM-DD) |

**响应**

```json
{
  "data": [
    {
      "day": "2025-01-01",
      "dauCount": 50000,
      "dauByProvince": {
        "广东省": 15000,
        "北京市": 8000,
        "上海市": 7000
      },
      "dauByCity": {
        "深圳市": 10000,
        "北京市": 8000,
        "上海市": 7000
      }
    }
  ],
  "total": 1,
  "summary": {
    "totalDau": 50000,
    "avgDau": 50000,
    "maxDau": 50000,
    "minDau": 50000
  }
}
```

| 字段 | 类型 | 描述 |
|-----|------|------|
| data | array | 日活数据列表 |
| data[].day | string | 统计日期 |
| data[].dauCount | number | 日活人数 |
| data[].dauByProvince | object | 按省份统计 |
| data[].dauByCity | object | 按城市统计 |
| total | number | 数据天数 |
| summary | object | 汇总统计 |

**错误码**

| HTTP 状态码 | 错误码 | 描述 |
|------------|-------|------|
| 400 | INVALID_DATE_FORMAT | 无效的日期格式 |
| 400 | DATE_RANGE_TOO_LARGE | 日期范围过大 (最多90天) |

---

## 3. 健康检查 API

### 3.1 健康检查

检查服务健康状态。

**请求**

```
GET /api/v1/health
```

**响应**

```json
{
  "status": "ok",
  "service": "presence-service",
  "timestamp": "2025-01-01T12:00:00.000Z"
}
```

---

## 4. 错误响应格式

所有错误响应遵循统一格式：

```json
{
  "statusCode": 400,
  "path": "/api/v1/presence/heartbeat",
  "method": "POST",
  "message": "installId must be a string",
  "timestamp": "2025-01-01T12:00:00.000Z"
}
```

| 字段 | 类型 | 描述 |
|-----|------|------|
| statusCode | number | HTTP 状态码 |
| path | string | 请求路径 |
| method | string | 请求方法 |
| message | string | 错误信息 |
| timestamp | string | 错误时间 |

**ValidationPipe 错误格式**

当请求体校验失败时，message 字段可能为数组：

```json
{
  "statusCode": 400,
  "path": "/api/v1/presence/heartbeat",
  "method": "POST",
  "message": [
    "installId must be a string",
    "clientTs must be a number"
  ],
  "timestamp": "2025-01-01T12:00:00.000Z"
}
```

---

## 5. 通用 HTTP 状态码

| 状态码 | 描述 |
|-------|------|
| 200 | 请求成功 |
| 201 | 资源创建成功 |
| 400 | 请求参数错误 |
| 401 | 未授权 |
| 403 | 禁止访问 |
| 404 | 资源不存在 |
| 422 | 业务逻辑错误 |
| 500 | 服务器内部错误 |

---

## 6. 限流策略

| 接口 | 限制 | 窗口 |
|-----|------|-----|
| POST /heartbeat | 60 次/分钟/用户 | 滑动窗口 |
| POST /events | 100 次/分钟/IP | 滑动窗口 |
| GET /online-count | 120 次/分钟/用户 | 滑动窗口 |
| GET /online-history | 30 次/分钟/用户 | 滑动窗口 |
| GET /dau | 30 次/分钟/用户 | 滑动窗口 |

超出限制返回 `429 Too Many Requests`。

---

## 7. SDK 示例

### JavaScript/TypeScript

```typescript
class PresenceClient {
  private baseUrl: string;
  private token: string;

  constructor(baseUrl: string, token: string) {
    this.baseUrl = baseUrl;
    this.token = token;
  }

  async sendHeartbeat(installId: string, appVersion: string): Promise<void> {
    const response = await fetch(`${this.baseUrl}/api/v1/presence/heartbeat`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${this.token}`,
      },
      body: JSON.stringify({
        installId,
        appVersion,
        clientTs: Math.floor(Date.now() / 1000),
      }),
    });

    if (!response.ok) {
      throw new Error(`Heartbeat failed: ${response.status}`);
    }
  }

  async getOnlineCount(windowSeconds = 180): Promise<number> {
    const response = await fetch(
      `${this.baseUrl}/api/v1/presence/online-count?windowSeconds=${windowSeconds}`,
      {
        headers: {
          'Authorization': `Bearer ${this.token}`,
        },
      }
    );

    const data = await response.json();
    return data.count;
  }
}
```

### cURL 示例

```bash
# 发送心跳
curl -X POST https://api.example.com/api/v1/presence/heartbeat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "installId": "uuid-xxxx-xxxx-xxxx",
    "appVersion": "1.0.0",
    "clientTs": 1732685100
  }'

# 查询在线人数
curl https://api.example.com/api/v1/presence/online-count \
  -H "Authorization: Bearer <token>"

# 查询在线历史
curl "https://api.example.com/api/v1/presence/online-history?startTime=2025-01-01T00:00:00Z&endTime=2025-01-01T12:00:00Z&interval=5m" \
  -H "Authorization: Bearer <token>"

# 批量上报事件
curl -X POST https://api.example.com/api/v1/analytics/events \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "eventName": "app_session_start",
        "installId": "uuid-xxxx-xxxx-xxxx",
        "clientTs": 1732685100,
        "properties": {"os": "iOS"}
      }
    ]
  }'
```