# 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 player records (default: approved, 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 |
| all | Boolean | no | false | When `true`, returns all records without pagination |

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

**All records (no pagination):**
```bash
curl -H "X-API-TOKEN: <token>" \
  "https://whitelist.r3944realms.top/api/whitelist/list?all=true"
```

<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` (including `all`).

```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` (including `all`).

```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 |