# 天梯系统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四个时间点刷新排行榜