# 服务器列表接口 API 文档

## 接口说明

`getAllServerList` 和 `getLastServerList` 接口已升级，支持查询玩家在各个服务器的角色信息。

---

## 1. 获取所有服务器列表

### 接口地址
- **GET** `/getAllServerList`
- **POST** `/getAllServerList`

### 请求参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| channel_id | number | 否 | 渠道ID，默认为1 |
| uid | string | 否 | 玩家ID，提供时会查询角色信息。不提供时只返回基本服务器信息 |

### 请求示例

#### 不查询角色信息
```bash
GET /getAllServerList?channel_id=11
```

#### 查询角色信息
```bash
GET /getAllServerList?channel_id=11&uid=12345678
```

#### POST请求
```bash
POST /getAllServerList
Content-Type: application/json

{
  "channel_id": 11,
  "uid": "12345678"
}
```

### 响应参数

#### 不提供uid时的响应
```json
[
  {
    "id": 1,
    "name": "1区",
    "ip": "192.168.1.100",
    "port": 8080,
    "status": 0,
    "tips": "正常"
  }
]
```

#### 提供uid时的响应
```json
[
  {
    "id": 1,
    "name": "1区",
    "ip": "192.168.1.100",
    "port": 8080,
    "status": 0,
    "tips": "正常",
    "roleName": "玩家昵称",
    "roleLevel": 50,
    "head": "avatar_001.png",
    "hasRole": true
  },
  {
    "id": 2,
    "name": "2区",
    "ip": "192.168.1.101",
    "port": 8080,
    "status": 0,
    "tips": "正常",
    "roleName": null,
    "roleLevel": null,
    "head": null,
    "hasRole": false
  }
]
```

---

## 2. 获取最近登录服务器列表

### 接口地址
- **POST** `/getLastServerList`

### 请求参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| uid | string | 否 | 玩家ID，用于查询角色信息。不提供时只返回基本服务器信息 |
| channel_id | number | 否 | 渠道ID，默认为1 |

### 请求示例

#### 查询角色信息
```bash
POST /getLastServerList
Content-Type: application/json

{
  "uid": "12345678",
  "channel_id": 11
}
```

#### 不查询角色信息
```bash
POST /getLastServerList
Content-Type: application/json

{
  "channel_id": 11
}
```

### 响应参数
```json
[
  {
    "channel": "小程序",
    "minSid": 1,
    "maxSid": 10,
    "isNewAccount": 0,
    "sid": 1,
    "id": 1,
    "name": "1区",
    "tips": "正常",
    "server": "ws://192.168.1.100:8080",
    "status": 0,
    "roleName": "玩家昵称",
    "roleLevel": 50,
    "head": "avatar_001.png",
    "hasRole": true
  }
]
```

---

## 3. 角色信息字段说明

| 字段 | 类型 | 说明 |
|------|------|------|
| roleName | string/null | 角色名称，无角色时为null |
| roleLevel | number/null | 角色等级，无角色时为null |
| head | string/null | 角色头像，无角色时为null |
| hasRole | boolean | 是否有角色，true表示有角色，false表示无角色 |

---

## 4. 数据库查询逻辑

### 数据库名称生成规则
```
数据库名称 = "ckwy_fy_S" + (350001 + 服务器ID).padStart(3, '0')
```

### 查询条件
- 集合名称：`char`
- 查询条件：`{uid: 玩家ID}`

### 返回字段
- `name`: 角色名称
- `lv`: 角色等级
- `roleId`: 角色ID
- `head`: 角色头像

---

## 5. 错误处理

- 如果查询角色信息失败，会记录错误日志，但不会影响服务器列表的返回
- 查询失败时，角色相关字段会设置为null或false
- 数据库连接失败时会返回默认值

---

## 6. 性能优化

- 使用 `Promise.all` 并行查询多个服务器的角色信息
- 查询失败时不会阻塞其他服务器的查询
- 只查询有玩家ID的请求，避免不必要的数据库查询

---

## 7. 使用示例

### JavaScript示例
```javascript
// 获取所有服务器列表（带角色信息）
const getAllServers = async (uid) => {
  const response = await fetch(`/getAllServerList?uid=${uid}&channel_id=11`);
  const servers = await response.json();
  
  servers.forEach(server => {
    if (server.hasRole) {
      console.log(`服务器${server.name}: ${server.roleName} (等级${server.roleLevel}) 头像: ${server.head}`);
    } else {
      console.log(`服务器${server.name}: 无角色`);
    }
  });
};

// 获取最近登录服务器列表
const getLastServers = async (uid) => {
  const response = await fetch('/getLastServerList', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ uid, channel_id: 11 })
  });
  const servers = await response.json();
  return servers;
};
```

---

## 8. 重要说明

- **向后兼容**: 不提供uid时，接口行为与之前完全一致
- **性能考虑**: 提供uid时会查询所有服务器的角色信息，可能影响响应时间
- **数据一致性**: 角色信息来自MongoDB，与游戏服务器数据保持同步
- **错误容错**: 单个服务器查询失败不会影响整体结果