### 可用 API 接口

本 Mod 提供了一系列 RESTful API 接口，允许外部应用获取服务器的玩家在线数据和实时状态。所有 API 接口均通过 HTTP GET 请求访问。

**基础 URL:** `http://您的服务器IP:配置的端口` (默认端口为 `60048`)

---

#### `GET /api/stats`

*   **描述:** 获取所有玩家的在线时长统计数据。
*   **响应:** JSON 数组，每个元素代表一个玩家的统计信息。
*   **响应示例结构:**

    ```json
    [
      {
        "playerName": "玩家名称",
        "uuid": "114514-1919810",
        "totalTimeSeconds": 123456,
        "totalTimeFormatted": "34h 17m",
        "last30DaysSeconds": 54321,
        "last30DaysFormatted": "15h 05m",
        "last7DaysSeconds": 9876,
        "last7DaysFormatted": "02h 44m"
      }
      // ... 更多玩家
    ]
    ```

*   **字段说明:**
    *   `playerName` (String): 玩家名称。
    *   `uuid` (String): 玩家的 UUID。
    *   `totalTimeSeconds` (long): 总在线时长（秒）。
    *   `totalTimeFormatted` (String): 总在线时长（格式化字符串，例如 "34h 17m"）。
    *   `last30DaysSeconds` (long): 最近 30 天在线时长（秒）。
    *   `last30DaysFormatted` (String): 最近 30 天在线时长（格式化字符串）。
    *   `last7DaysSeconds` (long): 最近 7 天在线时长（秒）。
    *   `last7DaysFormatted` (String): 最近 7 天在线时长（格式化字符串）。

---

#### `GET /api/lang`

*   **描述:** 获取 Mod 当前加载的本地化语言字符串。
    *   **注意:** 此接口主要用于内部调试和网页前端加载语言，不建议公开暴露。
*   **响应:** JSON 对象，键为语言字符串的 key，值为对应的翻译文本。
*   **响应示例结构:**

    ```json
    {
      "playertime.command.title": "§6===== 玩家在线时长 (第 {0}/{1} 页) =====",
      "playertime.web.title": "玩家在线及状态统计",
      // ... 更多语言键值对
    }
    ```

---

#### `GET /api/online-players`

*   **描述:** 获取当前在线玩家的列表，按白名单状态分类。
*   **响应:** JSON 对象，包含两个列表：`whitelisted` 和 `non_whitelisted`。
*   **响应示例结构:**

    ```json
    {
      "whitelisted": [
        {
          "name": "WhitelistedPlayer1",
          "uuid": "114514-1919810"
        }
      ],
      "non_whitelisted": [
        {
          "name": "NonWhitelistedPlayer1",
          "uuid": "51121-55555121"
        }
      ]
    }
    ```

*   **字段说明:**
    *   `whitelisted` (List<Map<String, String>>): 白名单在线玩家列表。每个 Map 包含 `name` (玩家名称) 和 `uuid` (玩家 UUID)。
    *   `non_whitelisted` (List<Map<String, String>>): 非白名单在线玩家列表。每个 Map 包含 `name` (玩家名称) 和 `uuid` (玩家 UUID)。

---

#### `GET /api/player-count`

*   **描述:** 获取当前在线玩家的数量统计。
*   **响应:** JSON 对象，包含总数、白名单玩家数和非白名单玩家数。
*   **响应示例结构:**

    ```json
    {
      "total": 10,
      "whitelisted": 8,
      "non_whitelisted": 2
    }
    ```

*   **字段说明:**
    *   `total` (int): 在线玩家总数。
    *   `whitelisted` (int): 在线白名单玩家数。
    *   `non_whitelisted` (int): 在线非白名单玩家数（通常指假人或未在白名单的玩家）。

---

#### `GET /api/whitelist`

*   **描述:** 获取服务器的白名单列表。
*   **响应:** JSON 数组，每个元素代表一个白名单玩家的信息。
*   **响应示例结构:**

    ```json
    [
      {
        "name": "BRanulf",
        "uuid": "114514-1919810",
        "online": true
      },
      {
        "name": "DarkSharkBee",
        "uuid": "51121-55555121",
        "online": false
      }
      // ... 更多白名单玩家
    ]
    ```

*   **字段说明:**
    *   `name` (String): 白名单玩家名称。
    *   `uuid` (String): 白名单玩家的 UUID。
    *   `online` (boolean): 该玩家当前是否在线。

---

#### `GET /api/server-status`

*   **描述:** 获取服务器的详细运行状态信息。
*   **响应:** JSON 对象，包含内存、磁盘、处理器、运行时间及服务器自身信息。
*   **响应示例结构:**

    ```json
    {
      "memory": {
        "max": 8589934592,
        "total": 8589934592,
        "used": 2147483648,
        "free": 6442450944,
        "usage_percentage": 25.0
      },
      "disk": {
        "total": 1073741824000,
        "free": 536870912000,
        "usable": 536870912000,
        "usage_percentage": 50.0
      },
      "available_processors": 8,
      "uptime": 3600,
      "uptime_formatted": "01小时 00分钟 00秒",
      "server": {
        "version": "1.21.4",
        "motd": "§aWelcome to My Server!",
        "player_count": 5,
        "max_players": 20,
        "average_tick_time_ms": 15.23,
        "recent_tick_samples_ms": [14.5, 16.1, 15.0, 15.8, ...]
      }
    }
    ```

*   **字段说明:**
    *   `memory` (Object): 内存统计信息。
        *   `max` (long): JVM 可用的最大内存（字节）。
        *   `total` (long): JVM 当前分配的总内存（字节）。
        *   `used` (long): JVM 已使用的内存（字节）。
        *   `free` (long): JVM 可用的空闲内存（字节）。
        *   `usage_percentage` (double): 内存使用率（已用 / 最大 * 100）。
    *   `disk` (Object): 磁盘统计信息。
        *   `total` (long): 磁盘总空间（字节）。
        *   `free` (long): 磁盘空闲空间（字节）。
        *   `usable` (long): 磁盘可用空间（字节）。
        *   `usage_percentage` (double): 磁盘使用率（(总 - 空闲) / 总 * 100）。
    *   `available_processors` (int): 服务器可用的处理器核心数。
    *   `uptime` (long): 服务器运行时间（秒）。
    *   `uptime_formatted` (String): 服务器运行时间（格式化字符串，例如 "01小时 00分钟 00秒"）。
    *   `server` (Object): Minecraft 服务器自身信息。
        *   `version` (String): Minecraft 服务器版本。
        *   `motd` (String): 服务器 MOTD。
        *   `player_count` (int): 当前在线玩家数。
        *   `max_players` (int): 服务器最大玩家容量。
        *   `average_tick_time_ms` (double): 服务器平均 Tick 时间（毫秒，即 MSPT）。
        *   `recent_tick_samples_ms` (List<Double>): 最近的 Tick 时间样本（毫秒）。

---

#### `GET /api/playerdata`

*   **描述:** 获取原始的玩家在线时间数据文件内容。
    *   **警告:** 此接口直接暴露服务器的玩家数据文件内容，包含 UUID 和在线时间等敏感信息。**强烈建议不要将此接口公开暴露给外部网络。**
*   **响应:** JSON 对象，内容与 `player_time_data.json` 文件完全一致。
*   **响应示例结构:**

    ```json
    {
      "114514-1919810": {
        "totalTime": 123456,
        "lastLogin": 0, // 0 表示离线，非 0 表示上次登录时间戳
        "rolling30Days": {
          "days": 30,
          "entries": [
            { "timestamp": 1678886400, "seconds": 3600 },
            // ...
          ]
        },
        "rolling7Days": {
          "days": 7,
          "entries": [
            { "timestamp": 1678886400, "seconds": 1800 },
            // ...
          ]
        }
      },
      "51121-55555121": {
        // ...
      }
    }
    ```