📋 基础信息

服务器地址: http://your-domain.com:3003

请求格式: JSON (application/json)

字符编码: UTF-8

认证方式

Header 参数	类型	必填	说明
Authorization	string	否	Bearer Token，格式：Bearer {token}
X-Session-Id	string	否	会话ID，用于游客模式

🔐 用户认证

POST 注册/登录

/api/auth/unified

自动判断注册或登录，首次使用自动创建账号

请求示例:

{
  "username": "testuser",
  "password": "password123"
}

响应示例:

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 1,
    "username": "testuser",
    "is_admin": 0
  },
  "isNew": false
}

🏆 成就查询

GET 获取成就列表

/api/achievements

查询参数:

参数	类型	必填	说明
category_id	int	否	分类ID
subcategory_id	int	否	子分类ID
version	string	否	版本号（如：V3.0）
is_completed	int	否	是否完成（0/1）
search	string	否	搜索关键词

GET 获取版本列表

/api/achievements/versions

📊 分类查询

GET 获取分类列表

/api/categories

GET 获取分类统计

/api/categories/stats

获取各分类的完成情况统计

✅ 进度管理

POST 切换成就状态

/api/achievements/:id/toggle

切换指定成就的完成状态（未完成 ↔ 完成）

GET 导出进度

/api/achievements/export

导出当前用户的成就进度（ZIP 文件）

POST 导入进度

/api/achievements/import-progress

Content-Type: multipart/form-data

🗺️ 攻略查询

GET 获取攻略列表

/api/guides

查询参数: category (可选) - 攻略分类

GET 获取攻略分类

/api/guides/categories

⚠️ 错误处理

HTTP 状态码

状态码	说明
200	请求成功
400	请求参数错误
401	未授权（未登录或 Token 失效）
429	请求频率过高
500	服务器内部错误

错误响应格式

{
  "error": "错误信息描述"
}

🚀 使用示例

JavaScript (Fetch API)

// 登录
const response = await fetch('/api/auth/unified', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    username: 'testuser',
    password: 'password123'
  })
});
const data = await response.json();
const token = data.token;

// 获取成就列表
const achievements = await fetch('/api/achievements?version=V3.0', {
  headers: { 'Authorization': `Bearer ${token}` }
}).then(r => r.json());

// 完成成就
await fetch('/api/achievements/1/toggle', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${token}` }
});

Python (requests)

import requests

# 登录
response = requests.post('http://your-domain.com:3003/api/auth/unified',
    json={'username': 'testuser', 'password': 'password123'})
token = response.json()['token']

# 获取成就
headers = {'Authorization': f'Bearer {token}'}
achievements = requests.get(
    'http://your-domain.com:3003/api/achievements',
    headers=headers
).json()

📝 频率限制

📞 技术支持

如有问题，请通过以下方式联系：

• 💬 加入交流群
• 📱 小黑盒: 关注作者