docs: 添加了白名单接口API文档
This commit is contained in:
parent
23ec8a8803
commit
d73c343722
415
docs/whitelist-api-en.md
Normal file
415
docs/whitelist-api-en.md
Normal file
|
|
@ -0,0 +1,415 @@
|
||||||
|
# Whitelist API Documentation
|
||||||
|
|
||||||
|
## Base URL
|
||||||
|
|
||||||
|
```
|
||||||
|
https://your_host_url/api/whitelist
|
||||||
|
```
|
||||||
|
|
||||||
|
## Authentication
|
||||||
|
|
||||||
|
All endpoints require authentication. Choose one of the following methods:
|
||||||
|
|
||||||
|
| Method | Example |
|
||||||
|
|--------|---------|
|
||||||
|
| `X-API-Key` header | `-H "X-API-Key: <token>"` |
|
||||||
|
| `X-API-TOKEN` header | `-H "X-API-TOKEN: <token>"` |
|
||||||
|
| Query parameter | `?apiKey=<token>` |
|
||||||
|
| Admin session cookie | Browser login at `/admin/login` |
|
||||||
|
|
||||||
|
**Failure response** (HTTP 403):
|
||||||
|
```json
|
||||||
|
{"code": 403, "msg": "Permission denied: API Key is invalid or missing", "data": null}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Response Format
|
||||||
|
|
||||||
|
All endpoints return the following structure:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"code": 200,
|
||||||
|
"msg": "Success message",
|
||||||
|
"count": 0,
|
||||||
|
"data": {}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
| HTTP Status | `code` | Meaning |
|
||||||
|
|-------------|--------|---------|
|
||||||
|
| 200 | 200 | Success |
|
||||||
|
| 200 | 500 | Business error (e.g. player not found, RCON failure) |
|
||||||
|
| 403 | 403 | Authentication failure |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Endpoints
|
||||||
|
|
||||||
|
### 1. Get Whitelist (Approved Players)
|
||||||
|
|
||||||
|
```
|
||||||
|
GET /api/whitelist/list
|
||||||
|
```
|
||||||
|
|
||||||
|
Returns paginated list of approved players (status=1).
|
||||||
|
|
||||||
|
**Parameters:**
|
||||||
|
|
||||||
|
| Name | Type | Required | Default | Description |
|
||||||
|
|------|------|----------|---------|-------------|
|
||||||
|
| playerName | String | no | — | Filter by player name (partial match) |
|
||||||
|
| page | Integer | no | 1 | Page number |
|
||||||
|
| size | Integer | no | 10 | Items per page |
|
||||||
|
|
||||||
|
**Response `data`:** Array of `PlayerInfo` objects.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -H "X-API-TOKEN: <token>" \
|
||||||
|
"https://whitelist.r3944realms.top/api/whitelist/list?page=1&size=10&playerName=Steve"
|
||||||
|
```
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary>Example response</summary>
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"code": 200,
|
||||||
|
"msg": "查询成功",
|
||||||
|
"count": 42,
|
||||||
|
"data": [
|
||||||
|
{
|
||||||
|
"id": 1,
|
||||||
|
"playerName": "Steve",
|
||||||
|
"uuid": "8667ba71b85a4004af54457a9734eed7",
|
||||||
|
"qq": "123456789",
|
||||||
|
"status": 1,
|
||||||
|
"description": "I love this server",
|
||||||
|
"createTime": "2026-06-01T12:00:00",
|
||||||
|
"regionCode": 110000,
|
||||||
|
"regionFullName": "北京市",
|
||||||
|
"operatorId": 1,
|
||||||
|
"operatorUsername": "admin",
|
||||||
|
"operatorNickname": "Admin",
|
||||||
|
"totalScore": 85,
|
||||||
|
"emailActive": true
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
</details>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 2. Get Pending Applications
|
||||||
|
|
||||||
|
```
|
||||||
|
GET /api/whitelist/pending
|
||||||
|
```
|
||||||
|
|
||||||
|
Returns paginated list of players awaiting review (status=2).
|
||||||
|
|
||||||
|
**Parameters:** Same as `/list`.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -H "X-API-TOKEN: <token>" \
|
||||||
|
"https://whitelist.r3944realms.top/api/whitelist/pending?page=1&size=10"
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 3. Get Rejected Applications
|
||||||
|
|
||||||
|
```
|
||||||
|
GET /api/whitelist/rejected
|
||||||
|
```
|
||||||
|
|
||||||
|
Returns paginated list of rejected players (status=0).
|
||||||
|
|
||||||
|
**Parameters:** Same as `/list`.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -H "X-API-TOKEN: <token>" \
|
||||||
|
"https://whitelist.r3944realms.top/api/whitelist/rejected?page=1&size=10"
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 4. Approve Application (Add to Whitelist)
|
||||||
|
|
||||||
|
```
|
||||||
|
POST /api/whitelist/approve/{id}
|
||||||
|
```
|
||||||
|
|
||||||
|
Approves a pending player and adds them to the Minecraft server whitelist via RCON.
|
||||||
|
When authenticated via API Key, the operator record will be `null`.
|
||||||
|
|
||||||
|
**Path Parameters:**
|
||||||
|
|
||||||
|
| Name | Type | Description |
|
||||||
|
|------|------|-------------|
|
||||||
|
| id | Integer | Player ID |
|
||||||
|
|
||||||
|
**Success response:**
|
||||||
|
```json
|
||||||
|
{"code": 200, "msg": "已加入白名单", "data": null}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Error response:**
|
||||||
|
```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. Reject Application
|
||||||
|
|
||||||
|
```
|
||||||
|
POST /api/whitelist/reject/{id}
|
||||||
|
```
|
||||||
|
|
||||||
|
Rejects an application. Sets status to 0 and notifies via email.
|
||||||
|
|
||||||
|
**Path Parameters:** Same as approve.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -X POST -H "X-API-TOKEN: <token>" \
|
||||||
|
"https://whitelist.r3944realms.top/api/whitelist/reject/1"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Success response:**
|
||||||
|
```json
|
||||||
|
{"code": 200, "msg": "已拒绝申请", "data": null}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 6. Remove from Whitelist
|
||||||
|
|
||||||
|
```
|
||||||
|
DELETE /api/whitelist/remove/{id}
|
||||||
|
```
|
||||||
|
|
||||||
|
Removes a player from the Minecraft whitelist via RCON and deletes their record.
|
||||||
|
An email notification is sent.
|
||||||
|
|
||||||
|
**Path Parameters:** Player ID.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -X DELETE -H "X-API-TOKEN: <token>" \
|
||||||
|
"https://whitelist.r3944realms.top/api/whitelist/remove/1"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Success response:**
|
||||||
|
```json
|
||||||
|
{"code": 200, "msg": "已从白名单移除", "data": null}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 7. Batch Approve
|
||||||
|
|
||||||
|
```
|
||||||
|
POST /api/whitelist/batchApprove
|
||||||
|
```
|
||||||
|
|
||||||
|
Approve multiple applications at once.
|
||||||
|
|
||||||
|
**Request Body:**
|
||||||
|
```json
|
||||||
|
[1, 2, 3, 5]
|
||||||
|
```
|
||||||
|
|
||||||
|
**Success response:**
|
||||||
|
```json
|
||||||
|
{"code": 200, "msg": "成功处理：4/4", "data": null}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Partial success response:**
|
||||||
|
```json
|
||||||
|
{"code": 200, "msg": "成功处理：3/4", "data": null}
|
||||||
|
```
|
||||||
|
|
||||||
|
```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"
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 8. Batch Reject
|
||||||
|
|
||||||
|
```
|
||||||
|
POST /api/whitelist/batchReject
|
||||||
|
```
|
||||||
|
|
||||||
|
Reject multiple applications at once.
|
||||||
|
|
||||||
|
**Request Body:** Same as batchApprove (`[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"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Success response:**
|
||||||
|
```json
|
||||||
|
{"code": 200, "msg": "成功处理：2/2", "data": null}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 9. Batch Remove
|
||||||
|
|
||||||
|
```
|
||||||
|
DELETE /api/whitelist/batchRemove
|
||||||
|
```
|
||||||
|
|
||||||
|
Remove multiple players from whitelist at once.
|
||||||
|
|
||||||
|
**Request Body:** `[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"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Success response:**
|
||||||
|
```json
|
||||||
|
{"code": 200, "msg": "成功移除：2/2", "data": null}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 10. Whitelist Statistics
|
||||||
|
|
||||||
|
```
|
||||||
|
GET /api/whitelist/stats
|
||||||
|
```
|
||||||
|
|
||||||
|
Returns counts by status.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -H "X-API-TOKEN: <token>" \
|
||||||
|
"https://whitelist.r3944realms.top/api/whitelist/stats"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"code": 200,
|
||||||
|
"msg": "操作成功",
|
||||||
|
"data": {
|
||||||
|
"approved": 42,
|
||||||
|
"pending": 5,
|
||||||
|
"rejected": 10
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 11. Check Player Whitelist Status
|
||||||
|
|
||||||
|
```
|
||||||
|
GET /api/whitelist/check/{playerName}
|
||||||
|
```
|
||||||
|
|
||||||
|
Query a player's application status by their Minecraft name.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -H "X-API-TOKEN: <token>" \
|
||||||
|
"https://whitelist.r3944realms.top/api/whitelist/check/Steve"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response (found):**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"code": 200,
|
||||||
|
"data": {
|
||||||
|
"exists": true,
|
||||||
|
"status": 1,
|
||||||
|
"playerName": "Steve",
|
||||||
|
"qq": "12345",
|
||||||
|
"uuid": "8667ba71b85a4004af54457a9734eed7",
|
||||||
|
"statusText": "已通过"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response (not found):**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"code": 200,
|
||||||
|
"data": {
|
||||||
|
"exists": false
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Status codes:**
|
||||||
|
|
||||||
|
| status | statusText |
|
||||||
|
|--------|------------|
|
||||||
|
| 0 | 已拒绝 (Rejected) |
|
||||||
|
| 1 | 已通过 (Approved) |
|
||||||
|
| 2 | 待审核 (Pending) |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 12. Get Player Score
|
||||||
|
|
||||||
|
```
|
||||||
|
GET /api/whitelist/score/{id}
|
||||||
|
```
|
||||||
|
|
||||||
|
Returns the total exam score for a player.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -H "X-API-TOKEN: <token>" \
|
||||||
|
"https://whitelist.r3944realms.top/api/whitelist/score/1"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"code": 200,
|
||||||
|
"data": {
|
||||||
|
"playerId": 1,
|
||||||
|
"totalScore": 85
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Error (not found):**
|
||||||
|
```json
|
||||||
|
{"code": 500, "msg": "玩家不存在", "data": null}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## PlayerInfo Object
|
||||||
|
|
||||||
|
| Field | Type | Description |
|
||||||
|
|-------|------|-------------|
|
||||||
|
| id | Integer | Player ID |
|
||||||
|
| playerName | String | Minecraft username |
|
||||||
|
| uuid | String | Mojang account UUID |
|
||||||
|
| qq | String | QQ number |
|
||||||
|
| status | Byte | 0=rejected, 1=approved, 2=pending |
|
||||||
|
| description | String | Application note |
|
||||||
|
| createTime | String | Application timestamp (ISO 8601) |
|
||||||
|
| regionCode | Long | Region postal code |
|
||||||
|
| regionFullName | String | Full region name (e.g. "北京市") |
|
||||||
|
| operatorId | Integer | ID of the admin who processed |
|
||||||
|
| operatorUsername | String | Admin username |
|
||||||
|
| operatorNickname | String | Admin nickname |
|
||||||
|
| totalScore | Integer | Total exam score |
|
||||||
|
| emailActive | Boolean | Whether email is verified |
|
||||||
399
docs/whitelist-api-zh.md
Normal file
399
docs/whitelist-api-zh.md
Normal file
|
|
@ -0,0 +1,399 @@
|
||||||
|
# 白名单 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 | 每页条数 |
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -H "X-API-TOKEN: <token>" \
|
||||||
|
"https://whitelist.r3944realms.top/api/whitelist/list?page=1&size=10&playerName=Steve"
|
||||||
|
```
|
||||||
|
|
||||||
|
<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`。
|
||||||
|
|
||||||
|
```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`。
|
||||||
|
|
||||||
|
```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 | 邮箱是否已验证 |
|
||||||
Loading…
Reference in New Issue
Block a user