diff --git a/docs/whitelist-api-en.md b/docs/whitelist-api-en.md new file mode 100644 index 0000000..1ed7175 --- /dev/null +++ b/docs/whitelist-api-en.md @@ -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: "` | +| `X-API-TOKEN` header | `-H "X-API-TOKEN: "` | +| Query parameter | `?apiKey=` | +| 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: " \ + "https://whitelist.r3944realms.top/api/whitelist/list?page=1&size=10&playerName=Steve" +``` + +
+Example response + +```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 + } + ] +} +``` +
+ +--- + +### 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: " \ + "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: " \ + "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: " \ + "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: " \ + "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: " \ + "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: " \ + -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: " \ + -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: " \ + -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: " \ + "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: " \ + "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: " \ + "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 | diff --git a/docs/whitelist-api-zh.md b/docs/whitelist-api-zh.md new file mode 100644 index 0000000..da7e48b --- /dev/null +++ b/docs/whitelist-api-zh.md @@ -0,0 +1,399 @@ +# 白名单 API 接口文档 + +## 基础地址 + +``` +https://your_host_url/api/whitelist +``` + +## 鉴权 + +所有接口均需鉴权，任选以下一种方式： + +| 方式 | 示例 | +|------|------| +| `X-API-Key` 请求头 | `-H "X-API-Key: "` | +| `X-API-TOKEN` 请求头 | `-H "X-API-TOKEN: "` | +| Query 参数 | `?apiKey=` | +| 管理员 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: " \ + "https://whitelist.r3944realms.top/api/whitelist/list?page=1&size=10&playerName=Steve" +``` + +
+返回示例 + +```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 + } + ] +} +``` +
+ +--- + +### 2. 获取待审核列表 + +``` +GET /api/whitelist/pending +``` + +分页查询待审核的玩家（status=2）。 + +**请求参数：** 同 `/list`。 + +```bash +curl -H "X-API-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: " \ + "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: " \ + "https://whitelist.r3944realms.top/api/whitelist/approve/1" +``` + +--- + +### 5. 拒绝申请 + +``` +POST /api/whitelist/reject/{id} +``` + +拒绝申请，设置状态为 0 并发送邮件通知。 + +**路径参数：** 同 approve。 + +```bash +curl -X POST -H "X-API-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: " \ + "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: " \ + -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: " \ + -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: " \ + -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: " \ + "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: " \ + "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: " \ + "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 | 邮箱是否已验证 |