docs(API.md): 更新API文档以明确认证要求和玩家查询参数

- 修改“公开端点”描述，明确其无需 API Token 但可能需要其他凭证
- 为 `/api/v1/register` 和 `/api/v1/admin/generate-token` 添加详细认证说明
- 更新 `/api/v1/player` 端点描述，支持通过查询参数 `name` 和 `includeOffline` 获取玩家数据
- 增加对离线玩家查询、并发限制和超时机制的说明
- 补充相关 curl 示例和错误响应示例，提升接口使用清晰度

Author: xiaoxiao-cvs

API.md

@@ -76,9 +76,14 @@ curl -H "X-Admin-Password: your-admin-password" \
 
 ### 公开端点
 
-以下端点无需认证（如果认证被禁用，所有端点都无需认证）：
-- `/api/v1/register` - 用户注册
-- `/api/v1/admin/generate-token` - 生成注册令牌
+以下端点无需 API Token 认证（如果认证被禁用，所有端点都无需认证）：
+- `/api/v1/register` - 用户注册（无需认证，但需要有效的注册令牌）
+- `/api/v1/admin/generate-token` - 生成注册令牌（无需 API Token，但需要管理员密码）
+
+**说明：**
+- "公开端点"指的是不需要 API Token 的端点
+- `/api/v1/register` 虽然不需要 API Token，但需要提供有效的注册令牌（token）才能注册
+- `/api/v1/admin/generate-token` 虽然不需要 API Token，但需要通过 `X-Admin-Password` 头提供管理员密码
 
 ### 自动生成凭证
 
@@ -124,15 +129,17 @@ auth:
 ### 用户注册 API
 | 端点 | 方法 | 描述 | 认证要求 |
 |------|------|------|----------|
-| `/api/v1/register` | POST | 用户注册（使用注册令牌） | 无（公开） |
-| `/api/v1/admin/generate-token` | POST | 生成注册令牌 | 无（公开）* |
+| `/api/v1/register` | POST | 用户注册（使用注册令牌） | 注册令牌 |
+| `/api/v1/admin/generate-token` | POST | 生成注册令牌 | 管理员密码 |
 
-*注：虽然是公开端点，但需要管理员密码验证
+**说明：**
+- `/api/v1/register` 不需要 API Token，但需要在请求体中提供有效的注册令牌（token）
+- `/api/v1/admin/generate-token` 不需要 API Token，但需要在请求头 `X-Admin-Password` 中提供管理员密码
 
 ### 玩家数据查询 API
 | 端点 | 方法 | 描述 | 认证要求 |
 |------|------|------|----------|
-| `/api/v1/player/{playerName}` | GET | 获取玩家详细数据 | API Token |
+| `/api/v1/player` | GET | 获取玩家详细数据（使用查询参数 `?name=玩家名`） | API Token |
 
 ### 服务器监控 API
 | 端点 | 方法 | 描述 | 认证要求 |
@@ -616,11 +623,17 @@ X-Admin-Password: your-admin-password
 
 **查询参数：**
 - `name` (string, 必需): 玩家名称
+- `includeOffline` (boolean, 可选): 是否查询离线玩家，默认为 `false`。设置为 `true` 可以查询离线玩家的基本信息
 
 **请求示例：**
 ```bash
+# 查询在线玩家
 curl -H "X-API-Key: sk-your-api-token-here" \
      -X GET "http://your-server:22222/api/v1/player?name=PlayerName"
+
+# 查询离线玩家
+curl -H "X-API-Key: sk-your-api-token-here" \
+     -X GET "http://your-server:22222/api/v1/player?name=PlayerName&includeOffline=true"
 ```
 
 **响应示例（在线玩家）：**
@@ -772,6 +785,15 @@ curl -H "X-API-Key: sk-your-api-token-here" \
 ```
 
 **错误响应示例：**
+```json
+{
+  "success": false,
+  "error": "玩家不在线 (提示: 使用 ?includeOffline=true 查询离线玩家)",
+  "code": 404,
+  "timestamp": "2025-10-02T12:00:00"
+}
+```
+
 ```json
 {
   "success": false,
@@ -781,6 +803,24 @@ curl -H "X-API-Key: sk-your-api-token-here" \
 }
 ```
 
+```json
+{
+  "success": false,
+  "error": "服务器繁忙,请稍后重试(TPS过低)",
+  "code": 504,
+  "timestamp": "2025-10-02T12:00:00"
+}
+```
+
+```json
+{
+  "success": false,
+  "error": "查询请求过多,请稍后再试",
+  "code": 429,
+  "timestamp": "2025-10-02T12:00:00"
+}
+```
+
 **数据字段说明：**
 
 | 字段 | 类型 | 说明 |
@@ -833,10 +873,13 @@ curl -H "X-API-Key: sk-your-api-token-here" \
 - 生成玩家数据报告
 
 **注意事项：**
-- 离线玩家只能获取有限的基本信息
+- 离线玩家只能获取有限的基本信息（需要设置 `includeOffline=true`）
 - 在线玩家可以获取完整的实时数据
 - 需要 API Token 认证才能访问
 - 玩家名称区分大小写
+- 查询在线玩家超时时间为 3 秒，离线玩家为 5 秒
+- 系统限制最多 5 个并发查询，超过限制将返回 429 错误
+- 如果服务器 TPS 过低可能返回 504 超时错误
 
 ### 服务器监控 API
 
@@ -1057,6 +1100,18 @@ curl -X POST http://localhost:22222/api/v1/register \
   }'
 ```
 
+### 玩家数据查询示例
+
+```bash
+# 查询在线玩家数据
+curl -X GET "http://localhost:22222/api/v1/player?name=PlayerName" \
+  -H "X-API-Key: sk-your-api-token-here"
+
+# 查询离线玩家数据
+curl -X GET "http://localhost:22222/api/v1/player?name=PlayerName&includeOffline=true" \
+  -H "X-API-Key: sk-your-api-token-here"
+```
+
 ### 系统监控示例
 
 ```bash
@@ -1149,6 +1204,15 @@ A: 可以通过 `GET /api/v1/whitelist/stats` 查看 `uuid_pending_entries` 数
 **Q: 旧的API调用还能使用吗？**
 A: 是的，系统保持向后兼容，但建议使用新的简化API以获得更好的体验。
 
+**Q: 为什么查询玩家数据时提示"玩家不在线"？**
+A: 默认情况下，API 只查询在线玩家。如果需要查询离线玩家，请在 URL 中添加 `includeOffline=true` 参数。
+
+**Q: 查询玩家数据时为什么会超时？**
+A: 玩家数据查询需要在 Minecraft 主线程执行，如果服务器 TPS 过低或负载过高，可能导致超时。查询在线玩家超时时间为 3 秒，离线玩家为 5 秒。
+
+**Q: 为什么会收到 429 错误（请求过多）？**
+A: 系统限制最多同时处理 5 个玩家数据查询请求，以保护服务器性能。请稍后重试或减少并发请求数量。
+
 ---
 
 *本文档描述了ConvenientAccess白名单管理系统的API接口。系统基于WhitelistPlus设计理念，专注于简化白名单管理流程，同时保持数据完整性和系统可靠性。*