# 白名单 API 接口文档

## 基础地址

```
https://your_host_url/api/whitelist
```

## 鉴权

所有接口均需鉴权，任选以下一种方式：

| 方式 | 示例 |
|------|------|
| `X-API-Key` 请求头 | `-H "X-API-Key: <token>"` |
| `X-API-TOKEN` 请求头 | `-H "X-API-TOKEN: <token>"` |
| Query 参数 | `?apiKey=<token>` |
| 管理员 Session Cookie | 浏览器登录 `/admin/login` 后自动携带 |

**鉴权失败响应**（HTTP 403）：
```json
{"code": 403, "msg": "无权限：API Key 无效或未提供", "data": null}
```

## 通用响应格式

所有接口统一返回以下结构：

```json
{
  "code": 200,
  "msg": "提示信息",
  "count": 0,
  "data": {}
}
```

| HTTP 状态码 | `code` | 含义 |
|-------------|--------|------|
| 200 | 200 | 操作成功 |
| 200 | 500 | 业务错误（如玩家不存在、RCON 连接失败） |
| 403 | 403 | 鉴权失败 |

---

## 接口列表

### 1. 获取白名单列表

```
GET /api/whitelist/list
```

查询玩家记录（默认 status=1 已通过）。

**请求参数：**

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| playerName | String | 否 | — | 按玩家名筛选 |
| page | Integer | 否 | 1 | 页码 |
| size | Integer | 否 | 10 | 每页条数 |
| all | Boolean | 否 | false | `true` 时忽略分页，一次性返回全部数据 |

**分页查询：**
```bash
curl -H "X-API-TOKEN: <token>" \
  "https://whitelist.r3944realms.top/api/whitelist/list?page=1&size=10&playerName=Steve"
```

**全部查询（不分页）：**
```bash
curl -H "X-API-TOKEN: <token>" \
  "https://whitelist.r3944realms.top/api/whitelist/list?all=true"
```

<details>
<summary>返回示例</summary>

```json
{
  "code": 200,
  "msg": "查询成功",
  "count": 42,
  "data": [
    {
      "id": 1,
      "playerName": "Steve",
      "uuid": "8667ba71b85a4004af54457a9734eed7",
      "qq": "123456789",
      "status": 1,
      "description": "我是建筑党",
      "createTime": "2026-06-01T12:00:00",
      "regionCode": 110000,
      "regionFullName": "北京市",
      "operatorId": 1,
      "operatorUsername": "admin",
      "operatorNickname": "管理员",
      "totalScore": 85,
      "emailActive": true
    }
  ]
}
```
</details>

---

### 2. 获取待审核列表

```
GET /api/whitelist/pending
```

分页查询待审核的玩家（status=2）。

**请求参数：** 同 `/list`（含 `all` 参数）。

```bash
curl -H "X-API-TOKEN: <token>" \
  "https://whitelist.r3944realms.top/api/whitelist/pending?page=1&size=10"
```

---

### 3. 获取已拒绝列表

```
GET /api/whitelist/rejected
```

分页查询已被拒绝的玩家（status=0）。

**请求参数：** 同 `/list`（含 `all` 参数）。

```bash
curl -H "X-API-TOKEN: <token>" \
  "https://whitelist.r3944realms.top/api/whitelist/rejected?page=1&size=10"
```

---

### 4. 通过审核（加入白名单）

```
POST /api/whitelist/approve/{id}
```

通过申请，通过 RCON 将玩家加入 Minecraft 服务器白名单。
使用 API Key 鉴权时，操作员记录为 `null`。

**路径参数：**

| 参数名 | 类型 | 说明 |
|--------|------|------|
| id | Integer | 玩家 ID |

**成功响应：**
```json
{"code": 200, "msg": "已加入白名单", "data": null}
```

**失败响应：**
```json
{"code": 500, "msg": "操作失败，Rcon连接错误或玩家不存在", "data": null}
```

```bash
curl -X POST -H "X-API-TOKEN: <token>" \
  "https://whitelist.r3944realms.top/api/whitelist/approve/1"
```

---

### 5. 拒绝申请

```
POST /api/whitelist/reject/{id}
```

拒绝申请，设置状态为 0 并发送邮件通知。

**路径参数：** 同 approve。

```bash
curl -X POST -H "X-API-TOKEN: <token>" \
  "https://whitelist.r3944realms.top/api/whitelist/reject/1"
```

**成功响应：**
```json
{"code": 200, "msg": "已拒绝申请", "data": null}
```

---

### 6. 从白名单移除

```
DELETE /api/whitelist/remove/{id}
```

通过 RCON 从 Minecraft 白名单移除并删除记录，同时发送邮件通知。

```bash
curl -X DELETE -H "X-API-TOKEN: <token>" \
  "https://whitelist.r3944realms.top/api/whitelist/remove/1"
```

**成功响应：**
```json
{"code": 200, "msg": "已从白名单移除", "data": null}
```

---

### 7. 批量通过

```
POST /api/whitelist/batchApprove
```

**请求体：**
```json
[1, 2, 3, 5]
```

```bash
curl -X POST -H "Content-Type: application/json" -H "X-API-TOKEN: <token>" \
  -d '[1,2,3]' \
  "https://whitelist.r3944realms.top/api/whitelist/batchApprove"
```

**成功响应：**
```json
{"code": 200, "msg": "成功处理：3/3", "data": null}
```

**部分成功响应：**
```json
{"code": 200, "msg": "成功处理：2/3", "data": null}
```

---

### 8. 批量拒绝

```
POST /api/whitelist/batchReject
```

**请求体：** `[1, 2, 3]`

```bash
curl -X POST -H "Content-Type: application/json" -H "X-API-TOKEN: <token>" \
  -d '[4,5]' \
  "https://whitelist.r3944realms.top/api/whitelist/batchReject"
```

---

### 9. 批量移除

```
DELETE /api/whitelist/batchRemove
```

**请求体：** `[1, 2, 3]`

```bash
curl -X DELETE -H "Content-Type: application/json" -H "X-API-TOKEN: <token>" \
  -d '[1,2]' \
  "https://whitelist.r3944realms.top/api/whitelist/batchRemove"
```

**成功响应：**
```json
{"code": 200, "msg": "成功移除：2/2", "data": null}
```

---

### 10. 白名单统计

```
GET /api/whitelist/stats
```

返回各状态的申请数量。

```bash
curl -H "X-API-TOKEN: <token>" \
  "https://whitelist.r3944realms.top/api/whitelist/stats"
```

**响应示例：**
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "approved": 42,
    "pending": 5,
    "rejected": 10
  }
}
```

---

### 11. 查询玩家白名单状态

```
GET /api/whitelist/check/{playerName}
```

按 Minecraft 用户名查询申请状态。

```bash
curl -H "X-API-TOKEN: <token>" \
  "https://whitelist.r3944realms.top/api/whitelist/check/Steve"
```

**响应（存在）：**
```json
{
  "code": 200,
  "data": {
    "exists": true,
    "status": 1,
    "playerName": "Steve",
    "qq": "12345",
    "uuid": "8667ba71b85a4004af54457a9734eed7",
    "statusText": "已通过"
  }
}
```

**响应（不存在）：**
```json
{
  "code": 200,
  "data": {
    "exists": false
  }
}
```

**statusText 对照表：**

| status | statusText |
|--------|------------|
| 0 | 已拒绝 |
| 1 | 已通过 |
| 2 | 待审核 |

---

### 12. 获取玩家得分

```
GET /api/whitelist/score/{id}
```

查询玩家的答题总分。

```bash
curl -H "X-API-TOKEN: <token>" \
  "https://whitelist.r3944realms.top/api/whitelist/score/1"
```

**响应示例：**
```json
{
  "code": 200,
  "data": {
    "playerId": 1,
    "totalScore": 85
  }
}
```

**失败响应：**
```json
{"code": 500, "msg": "玩家不存在", "data": null}
```

---

## PlayerInfo 字段说明

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Integer | 玩家 ID |
| playerName | String | Minecraft 用户名 |
| uuid | String | Mojang 正版 UUID |
| qq | String | QQ 号 |
| status | Byte | 0=已拒绝, 1=已通过, 2=待审核 |
| description | String | 申请备注 |
| createTime | String | 申请时间（ISO 8601） |
| regionCode | Long | 地区邮政编码 |
| regionFullName | String | 地区全称（如"北京市"） |
| operatorId | Integer | 操作员 ID |
| operatorUsername | String | 操作员用户名 |
| operatorNickname | String | 操作员昵称 |
| totalScore | Integer | 答题总分 |
| emailActive | Boolean | 邮箱是否已验证 |