672 lines
12 KiB
Markdown
672 lines
12 KiB
Markdown
# 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
|