优化

ladder-api.md

@@ -0,0 +1,211 @@
+# 天梯系统API接口文档
+
+## 概述
+
+天梯系统API提供与玩家天梯等级、排行榜相关的接口。系统支持基于星星数的等级升降机制和王者分数机制。
+
+## 接口列表
+
+### 1. 获取排行榜
+
+#### 接口地址
+```
+GET /ladder/leaderboard
+```
+
+#### 请求参数
+无
+
+#### 响应数据
+```json
+[
+  {
+    "playerId": "string",         // 玩家ID
+    "username": "string",         // 玩家用户名
+    "avatar": "string",           // 玩家头像
+    "rankId": "number",           // 天梯等级ID
+    "rankScore": "number",        // 王者分数（如果适用）
+    "stars": "number",            // 星星数（如果适用）
+    "totalWins": "number",        // 总胜利场次
+    "position": "number"          // 排名位置
+  }
+]
+```
+
+#### 响应示例
+```json
+[
+  {
+    "playerId": "5f1a2b3c4d5e6f7g8h9i0j1k",
+    "username": "Player1",
+    "avatar": "avatar_01",
+    "rankId": 5,
+    "rankScore": 1250,
+    "stars": 0,
+    "totalWins": 128,
+    "position": 1
+  }
+]
+```
+
+### 2. 获取玩家排名位置
+
+#### 接口地址
+```
+GET /ladder/position/:playerId
+```
+
+#### 请求参数
+| 参数名    | 类型   | 必填 | 说明   |
+| --------- | ------ | ---- | ------ |
+| playerId  | string | 是   | 玩家ID |
+
+#### 响应数据
+```json
+{
+  "position": "number"  // 玩家在排行榜中的位置，未上榜为null
+}
+```
+
+#### 响应示例
+```json
+{
+  "position": 5
+}
+```
+
+### 3. 获取玩家天梯信息
+
+#### 接口地址
+```
+GET /ladder/rank/:playerId
+```
+
+#### 请求参数
+| 参数名    | 类型   | 必填 | 说明   |
+| --------- | ------ | ---- | ------ |
+| playerId  | string | 是   | 玩家ID |
+
+#### 响应数据
+对于开启王者分数机制的玩家：
+```json
+{
+  "rankName": "string",    // 天梯阶级名称
+  "level": "number",       // 天梯等级
+  "score": "number",       // 王者分数
+  "isRankScore": "boolean" // 是否为王者分数机制
+}
+```
+
+对于普通星星机制的玩家：
+```json
+{
+  "rankName": "string",    // 天梯阶级名称
+  "level": "number",       // 天梯等级
+  "stars": "number",       // 当前星星数
+  "maxStars": "number",    // 最大星星数
+  "isRankScore": "boolean" // 是否为王者分数机制
+}
+```
+
+#### 响应示例
+```json
+{
+  "rankName": "Gold",
+  "level": 5,
+  "score": 1250,
+  "isRankScore": true
+}
+```
+
+### 4. 获取所有天梯配置
+
+#### 接口地址
+```
+GET /ladder/config
+```
+
+#### 请求参数
+无
+
+#### 响应数据
+```json
+[
+  {
+    "Id": "number",           // 天梯ID
+    "Rank": "number",         // 天梯阶级
+    "RankName": "string",     // 天梯阶级名称
+    "Level": "number",        // 天梯等级
+    "BeginStar": "number",    // 升级后初始星星数
+    "RankDownStar": "number", // 降级后初始星星数
+    "MaxStar": "number",      // 当前等级的星星上限
+    "WinGetStar": "number",   // 胜利时增加的星星数
+    "ExtraGetStar": "number", // 连胜时额外增加的星星数
+    "LoseLostStar": "number", // 是否失败时减少星星（1为是，0为否）
+    "LoseRankDown": "number", // 是否失败导致等级下降（1为是，0为否）
+    "RankScore": "number",    // 是否开启天梯分数机制（1为开启）
+    "AITimes": "number",      // 等待多久后改为对战机器人
+    "AIDeck": "string",       // 机器人卡组的RANK配置
+    "WaitTime": "number",     // 扩大匹配范围的时间间隔
+    "MaxWaitTime": "number"   // 王者等级匹配时，扩大分数范围的间隔
+  }
+]
+```
+
+#### 响应示例
+```json
+[
+  {
+    "Id": 1,
+    "Rank": 1,
+    "RankName": "Bronze",
+    "Level": 1,
+    "BeginStar": 0,
+    "RankDownStar": 0,
+    "MaxStar": 5,
+    "WinGetStar": 1,
+    "ExtraGetStar": 0,
+    "LoseLostStar": 1,
+    "LoseRankDown": 0,
+    "RankScore": 0,
+    "AITimes": 30,
+    "AIDeck": "bronze_ai",
+    "WaitTime": 10,
+    "MaxWaitTime": 20
+  }
+]
+```
+
+## 错误响应格式
+
+所有接口在出错时都会返回以下格式的错误信息：
+
+```json
+{
+  "error": "string"  // 错误描述
+}
+```
+
+## 天梯系统机制说明
+
+### 星星机制
+- 玩家通过胜利获得星星，失败可能失去星星
+- 当星星数达到当前等级上限时，玩家升级
+- 当星星数为0且再次失败时，可能降级
+
+### 王者分数机制
+- 当玩家达到特定等级后开启王者分数机制
+- 不再使用星星和等级升降，天梯等级固定
+- 玩家首次进入该等级时，获得1000分的初始天梯分数
+- 胜利加分规则：
+  - 若对手分数 > 玩家分数：加分 = MIN(对手分数 / 玩家分数, 3) * 20
+  - 若玩家分数 >= 对手分数：加20分
+  - 若对手未开启天梯分数：加20分
+- 失败减分规则：
+  - 若失败方已有天梯分数：减20分（最低为0分）
+  - 若失败方未开启天梯分数：根据配置决定是否扣除1颗星星
+
+### 排行榜规则
+- 展示天梯等级最高的前100名玩家
+- 排名优先级：天梯等级 > 天梯分数 > 当前天梯星星数 > 玩家胜场数
+- 每天的00:00、12:00、18:00、22:00四个时间点刷新排行榜