12 KiB

Raw Blame History

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 认证：

Authorization: Bearer <token>

1.3 通用响应格式

成功响应

{
  "data": { ... },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

错误响应

{
  "statusCode": 400,
  "message": "错误描述",
  "error": "Bad Request"
}

2. 健康检查 API

2.1 存活检查

检查服务是否运行。

请求

GET /health

响应

{
  "status": "ok"
}

2.2 就绪检查

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

请求

GET /health/ready

响应

{
  "status": "ok",
  "details": {
    "database": "up",
    "redis": "up",
    "kafka": "up"
  }
}

3. 排行榜 API

3.1 获取日榜

获取当日排行榜数据。

请求

GET /leaderboard/daily

查询参数

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

响应

{
  "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 获取周榜

获取当周排行榜数据。

请求

GET /leaderboard/weekly

查询参数

同日榜。

响应

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

3.3 获取月榜

获取当月排行榜数据。

请求

GET /leaderboard/monthly

查询参数

同日榜。

响应

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

3.4 获取我的排名

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

请求

GET /leaderboard/my-rank
Authorization: Bearer <token>

查询参数

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

响应

{
  "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 获取指定用户排名

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

请求

GET /leaderboard/user/:userId
Authorization: Bearer <token>

路径参数

参数	类型	描述
userId	string	用户ID

响应

同 "获取我的排名"。

4. 配置管理 API

以下接口需要管理员权限

4.1 获取配置

获取排行榜全局配置。

请求

GET /leaderboard/config
Authorization: Bearer <token>

响应

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

4.2 更新榜单开关

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

请求

POST /leaderboard/config/switch
Authorization: Bearer <token>
Content-Type: application/json

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

请求体

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

响应

{
  "success": true,
  "message": "日榜已禁用",
  "config": { ... }
}

4.3 更新虚拟排名设置

配置虚拟排名功能。

请求

POST /leaderboard/config/virtual-ranking
Authorization: Bearer <token>
Content-Type: application/json

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

请求体

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

响应

{
  "success": true,
  "message": "虚拟排名设置已更新",
  "config": { ... }
}

4.4 更新显示数量

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

请求

POST /leaderboard/config/display-limit
Authorization: Bearer <token>
Content-Type: application/json

{
  "limit": 50
}

请求体

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

响应

{
  "success": true,
  "message": "显示数量已更新为 50",
  "config": { ... }
}

4.5 更新刷新间隔

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

请求

POST /leaderboard/config/refresh-interval
Authorization: Bearer <token>
Content-Type: application/json

{
  "minutes": 10
}

请求体

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

响应

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

4.6 手动刷新排行榜

立即触发排行榜刷新。

请求

POST /leaderboard/config/refresh
Authorization: Bearer <token>
Content-Type: application/json

{
  "type": "DAILY"
}

请求体

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

响应

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

5. 虚拟账户 API

以下接口需要管理员权限

5.1 获取虚拟账户列表

请求

GET /virtual-accounts
Authorization: Bearer <token>

查询参数

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

响应

{
  "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 创建虚拟账户

请求

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	否	城市代码（市公司用）

响应

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

5.3 更新虚拟账户

请求

PUT /virtual-accounts/:id
Authorization: Bearer <token>
Content-Type: application/json

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

响应

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

5.4 删除虚拟账户

请求

DELETE /virtual-accounts/:id
Authorization: Bearer <token>

响应

{
  "success": true,
  "message": "虚拟账户已删除"
}

5.5 批量创建虚拟账户

请求

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	否	最大分值

响应

{
  "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	服务不可用

错误响应示例

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

12 KiB Raw Blame History Unescape Escape

Leaderboard Service API 文档

1. 概述

1.1 基础信息

1.2 认证方式

1.3 通用响应格式

2. 健康检查 API

2.1 存活检查

2.2 就绪检查

3. 排行榜 API

3.1 获取日榜

3.2 获取周榜

3.3 获取月榜

3.4 获取我的排名

3.5 获取指定用户排名

4. 配置管理 API

4.1 获取配置

4.2 更新榜单开关

4.3 更新虚拟排名设置

4.4 更新显示数量

4.5 更新刷新间隔

4.6 手动刷新排行榜

5. 虚拟账户 API

5.1 获取虚拟账户列表

5.2 创建虚拟账户

5.3 更新虚拟账户

5.4 删除虚拟账户

5.5 批量创建虚拟账户

6. 错误码

7. Swagger 文档

8. 速率限制

9. 变更日志

v1.0.0 (2024-01-15)

12 KiB

Raw Blame History