# Leaderboard Service API 文档

## 1. 概述

本文档描述 Leaderboard Service 的 RESTful API 接口规范。

### 1.1 基础信息

| 属性 | 值 |
|------|-----|
| Base URL | `http://localhost:3000` |
| API 版本 | v1 |
| 数据格式 | JSON |
| 字符编码 | UTF-8 |

### 1.2 认证方式

使用 JWT Bearer Token 认证：

```http
Authorization: Bearer <token>
```

### 1.3 通用响应格式

**成功响应**
```json
{
  "data": { ... },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z"
  }
}
```

**错误响应**
```json
{
  "statusCode": 400,
  "message": "错误描述",
  "error": "Bad Request"
}
```

---

## 2. 健康检查 API

### 2.1 存活检查

检查服务是否运行。

**请求**
```http
GET /health
```

**响应**
```json
{
  "status": "ok"
}
```

### 2.2 就绪检查

检查服务及其依赖是否就绪。

**请求**
```http
GET /health/ready
```

**响应**
```json
{
  "status": "ok",
  "details": {
    "database": "up",
    "redis": "up",
    "kafka": "up"
  }
}
```

---

## 3. 排行榜 API

### 3.1 获取日榜

获取当日排行榜数据。

**请求**
```http
GET /leaderboard/daily
```

**查询参数**

| 参数 | 类型 | 必填 | 默认值 | 描述 |
|------|------|------|--------|------|
| limit | number | 否 | 30 | 返回数量限制 (1-100) |
| includeVirtual | boolean | 否 | true | 是否包含虚拟排名 |

**响应**
```json
{
  "type": "DAILY",
  "period": {
    "key": "2024-01-15",
    "startAt": "2024-01-15T00:00:00Z",
    "endAt": "2024-01-15T23:59:59Z"
  },
  "rankings": [
    {
      "displayPosition": 1,
      "userId": "123456789",
      "nickname": "用户A",
      "avatar": "https://...",
      "effectiveScore": 1500,
      "totalTeamPlanting": 2000,
      "maxDirectTeamPlanting": 500,
      "previousRank": 2,
      "rankChange": 1,
      "isVirtual": false
    },
    {
      "displayPosition": 2,
      "userId": null,
      "nickname": "虚拟用户B",
      "avatar": "https://...",
      "effectiveScore": 1400,
      "isVirtual": true
    }
  ],
  "totalCount": 100,
  "lastRefreshedAt": "2024-01-15T10:25:00Z"
}
```

### 3.2 获取周榜

获取当周排行榜数据。

**请求**
```http
GET /leaderboard/weekly
```

**查询参数**

同日榜。

**响应**

```json
{
  "type": "WEEKLY",
  "period": {
    "key": "2024-W03",
    "startAt": "2024-01-15T00:00:00Z",
    "endAt": "2024-01-21T23:59:59Z"
  },
  "rankings": [ ... ]
}
```

### 3.3 获取月榜

获取当月排行榜数据。

**请求**
```http
GET /leaderboard/monthly
```

**查询参数**

同日榜。

**响应**

```json
{
  "type": "MONTHLY",
  "period": {
    "key": "2024-01",
    "startAt": "2024-01-01T00:00:00Z",
    "endAt": "2024-01-31T23:59:59Z"
  },
  "rankings": [ ... ]
}
```

### 3.4 获取我的排名

获取当前登录用户的排名信息。

**请求**
```http
GET /leaderboard/my-rank
Authorization: Bearer <token>
```

**查询参数**

| 参数 | 类型 | 必填 | 默认值 | 描述 |
|------|------|------|--------|------|
| type | string | 否 | DAILY | 榜单类型 (DAILY/WEEKLY/MONTHLY) |

**响应**
```json
{
  "userId": "123456789",
  "daily": {
    "rankPosition": 5,
    "displayPosition": 7,
    "effectiveScore": 1200,
    "totalTeamPlanting": 1500,
    "maxDirectTeamPlanting": 300,
    "previousRank": 8,
    "rankChange": 3
  },
  "weekly": {
    "rankPosition": 10,
    "displayPosition": 12,
    "effectiveScore": 8500,
    "previousRank": 15,
    "rankChange": 5
  },
  "monthly": {
    "rankPosition": 25,
    "displayPosition": 30,
    "effectiveScore": 35000,
    "previousRank": null,
    "rankChange": 0
  }
}
```

### 3.5 获取指定用户排名

获取指定用户的排名信息（管理员）。

**请求**
```http
GET /leaderboard/user/:userId
Authorization: Bearer <token>
```

**路径参数**

| 参数 | 类型 | 描述 |
|------|------|------|
| userId | string | 用户ID |

**响应**

同 "获取我的排名"。

---

## 4. 配置管理 API

> 以下接口需要管理员权限

### 4.1 获取配置

获取排行榜全局配置。

**请求**
```http
GET /leaderboard/config
Authorization: Bearer <token>
```

**响应**
```json
{
  "configKey": "GLOBAL",
  "dailyEnabled": true,
  "weeklyEnabled": true,
  "monthlyEnabled": true,
  "virtualRankingEnabled": true,
  "virtualAccountCount": 30,
  "displayLimit": 30,
  "refreshIntervalMinutes": 5,
  "updatedAt": "2024-01-15T10:00:00Z"
}
```

### 4.2 更新榜单开关

启用或禁用指定类型的排行榜。

**请求**
```http
POST /leaderboard/config/switch
Authorization: Bearer <token>
Content-Type: application/json

{
  "type": "daily",
  "enabled": false
}
```

**请求体**

| 字段 | 类型 | 必填 | 描述 |
|------|------|------|------|
| type | string | 是 | 榜单类型 (daily/weekly/monthly) |
| enabled | boolean | 是 | 是否启用 |

**响应**
```json
{
  "success": true,
  "message": "日榜已禁用",
  "config": { ... }
}
```

### 4.3 更新虚拟排名设置

配置虚拟排名功能。

**请求**
```http
POST /leaderboard/config/virtual-ranking
Authorization: Bearer <token>
Content-Type: application/json

{
  "enabled": true,
  "count": 30
}
```

**请求体**

| 字段 | 类型 | 必填 | 描述 |
|------|------|------|------|
| enabled | boolean | 是 | 是否启用虚拟排名 |
| count | number | 是 | 虚拟账户数量 (0-100) |

**响应**
```json
{
  "success": true,
  "message": "虚拟排名设置已更新",
  "config": { ... }
}
```

### 4.4 更新显示数量

设置前端显示的排名数量。

**请求**
```http
POST /leaderboard/config/display-limit
Authorization: Bearer <token>
Content-Type: application/json

{
  "limit": 50
}
```

**请求体**

| 字段 | 类型 | 必填 | 描述 |
|------|------|------|------|
| limit | number | 是 | 显示数量 (1-100) |

**响应**
```json
{
  "success": true,
  "message": "显示数量已更新为 50",
  "config": { ... }
}
```

### 4.5 更新刷新间隔

设置排行榜自动刷新间隔。

**请求**
```http
POST /leaderboard/config/refresh-interval
Authorization: Bearer <token>
Content-Type: application/json

{
  "minutes": 10
}
```

**请求体**

| 字段 | 类型 | 必填 | 描述 |
|------|------|------|------|
| minutes | number | 是 | 刷新间隔（分钟，1-60）|

**响应**
```json
{
  "success": true,
  "message": "刷新间隔已更新为 10 分钟",
  "config": { ... }
}
```

### 4.6 手动刷新排行榜

立即触发排行榜刷新。

**请求**
```http
POST /leaderboard/config/refresh
Authorization: Bearer <token>
Content-Type: application/json

{
  "type": "DAILY"
}
```

**请求体**

| 字段 | 类型 | 必填 | 描述 |
|------|------|------|------|
| type | string | 否 | 榜单类型，为空则刷新全部 |

**响应**
```json
{
  "success": true,
  "message": "排行榜刷新已触发",
  "refreshedTypes": ["DAILY"],
  "startedAt": "2024-01-15T10:30:00Z"
}
```

---

## 5. 虚拟账户 API

> 以下接口需要管理员权限

### 5.1 获取虚拟账户列表

**请求**
```http
GET /virtual-accounts
Authorization: Bearer <token>
```

**查询参数**

| 参数 | 类型 | 必填 | 默认值 | 描述 |
|------|------|------|--------|------|
| page | number | 否 | 1 | 页码 |
| limit | number | 否 | 20 | 每页数量 |
| type | string | 否 | - | 账户类型过滤 |
| isActive | boolean | 否 | - | 激活状态过滤 |

**响应**
```json
{
  "data": [
    {
      "id": "1",
      "accountType": "RANKING_VIRTUAL",
      "displayName": "虚拟用户A",
      "avatar": "https://...",
      "minScore": 100,
      "maxScore": 500,
      "currentScore": 350,
      "isActive": true,
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 30,
    "totalPages": 2
  }
}
```

### 5.2 创建虚拟账户

**请求**
```http
POST /virtual-accounts
Authorization: Bearer <token>
Content-Type: application/json

{
  "accountType": "RANKING_VIRTUAL",
  "displayName": "新虚拟用户",
  "avatar": "https://...",
  "minScore": 100,
  "maxScore": 500
}
```

**请求体**

| 字段 | 类型 | 必填 | 描述 |
|------|------|------|------|
| accountType | string | 是 | 账户类型 |
| displayName | string | 是 | 显示名称 (1-100字符) |
| avatar | string | 否 | 头像URL |
| minScore | number | 否 | 最小分值 |
| maxScore | number | 否 | 最大分值 |
| provinceCode | string | 否 | 省份代码（省公司用）|
| cityCode | string | 否 | 城市代码（市公司用）|

**响应**
```json
{
  "id": "31",
  "accountType": "RANKING_VIRTUAL",
  "displayName": "新虚拟用户",
  "isActive": true,
  "createdAt": "2024-01-15T10:30:00Z"
}
```

### 5.3 更新虚拟账户

**请求**
```http
PUT /virtual-accounts/:id
Authorization: Bearer <token>
Content-Type: application/json

{
  "displayName": "更新后的名称",
  "isActive": false
}
```

**响应**
```json
{
  "id": "31",
  "displayName": "更新后的名称",
  "isActive": false,
  "updatedAt": "2024-01-15T10:35:00Z"
}
```

### 5.4 删除虚拟账户

**请求**
```http
DELETE /virtual-accounts/:id
Authorization: Bearer <token>
```

**响应**
```json
{
  "success": true,
  "message": "虚拟账户已删除"
}
```

### 5.5 批量创建虚拟账户

**请求**
```http
POST /virtual-accounts/batch
Authorization: Bearer <token>
Content-Type: application/json

{
  "count": 10,
  "accountType": "RANKING_VIRTUAL",
  "minScore": 100,
  "maxScore": 1000
}
```

**请求体**

| 字段 | 类型 | 必填 | 描述 |
|------|------|------|------|
| count | number | 是 | 创建数量 (1-100) |
| accountType | string | 是 | 账户类型 |
| minScore | number | 否 | 最小分值 |
| maxScore | number | 否 | 最大分值 |

**响应**
```json
{
  "success": true,
  "createdCount": 10,
  "accounts": [ ... ]
}
```

---

## 6. 错误码

| 状态码 | 错误码 | 描述 |
|--------|--------|------|
| 400 | BAD_REQUEST | 请求参数错误 |
| 401 | UNAUTHORIZED | 未授权访问 |
| 403 | FORBIDDEN | 无权限访问 |
| 404 | NOT_FOUND | 资源不存在 |
| 409 | CONFLICT | 资源冲突 |
| 422 | VALIDATION_ERROR | 数据验证失败 |
| 500 | INTERNAL_ERROR | 服务器内部错误 |
| 503 | SERVICE_UNAVAILABLE | 服务不可用 |

**错误响应示例**

```json
{
  "statusCode": 400,
  "message": "显示数量必须大于0",
  "error": "Bad Request",
  "timestamp": "2024-01-15T10:30:00Z",
  "path": "/leaderboard/config/display-limit"
}
```

---

## 7. Swagger 文档

服务提供在线 API 文档：

| URL | 描述 |
|-----|------|
| `/api-docs` | Swagger UI 界面 |
| `/api-docs-json` | OpenAPI JSON 规范 |

---

## 8. 速率限制

| 端点类型 | 限制 |
|----------|------|
| 公开端点 | 100 req/min |
| 认证端点 | 300 req/min |
| 管理端点 | 60 req/min |

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

---

## 9. 变更日志

### v1.0.0 (2024-01-15)

- 初始版本发布
- 支持日榜/周榜/月榜查询
- 支持虚拟排名功能
- 支持配置管理
- 支持虚拟账户 CRUD