成就系统 API

成就系统模块提供了学习成就的管理功能，包括成就解锁、进度追踪、成就展示等。

📋 接口概览

方法	路径	描述	权限
GET	`/api/achievements`	获取成就列表	所有用户
GET	`/api/achievements/:id`	获取单个成就	所有用户
GET	`/api/achievements/user`	获取用户成就	所有用户
POST	`/api/achievements/:id/unlock`	解锁成就	管理员
GET	`/api/achievements/categories`	获取成就分类	所有用户
GET	`/api/achievements/progress`	获取成就进度	所有用户

🏆 获取成就列表

获取系统中所有可用的成就。

请求

http

GET /api/achievements?category=learning&status=all
Authorization: Bearer <token>

查询参数

参数	类型	必填	默认值	描述
category	string	否	-	成就分类筛选
status	string	否	all	状态筛选 (all, unlocked, locked)
page	number	否	1	页码
limit	number	否	20	每页数量

响应

json

{
  "success": true,
  "data": {
    "achievements": [
      {
        "id": 1,
        "name": "学习新手",
        "description": "完成第一个学习项目",
        "category": "learning",
        "icon": "/assets/ico/achievements/first-study.svg",
        "rarity": "common",
        "points": 10,
        "criteria": {
          "type": "project_completion",
          "value": 1
        },
        "created_at": "2024-01-01T00:00:00Z"
      },
      {
        "id": 2,
        "name": "学习达人",
        "description": "累计学习100小时",
        "category": "learning",
        "icon": "/assets/ico/achievements/study-champion.svg",
        "rarity": "rare",
        "points": 50,
        "criteria": {
          "type": "total_hours",
          "value": 100
        },
        "created_at": "2024-01-01T00:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 25,
      "pages": 2
    }
  },
  "message": "获取成就列表成功"
}

🔍 获取单个成就

获取指定成就的详细信息。

请求

http

GET /api/achievements/1
Authorization: Bearer <token>

响应

json

{
  "success": true,
  "data": {
    "id": 1,
    "name": "学习新手",
    "description": "完成第一个学习项目",
    "category": "learning",
    "icon": "/assets/ico/achievements/first-study.svg",
    "rarity": "common",
    "points": 10,
    "criteria": {
      "type": "project_completion",
      "value": 1,
      "description": "完成1个学习项目"
    },
    "created_at": "2024-01-01T00:00:00Z",
    "user_progress": {
      "current": 1,
      "target": 1,
      "percentage": 100,
      "unlocked": true,
      "unlocked_at": "2024-01-10T12:00:00Z"
    }
  },
  "message": "获取成就详情成功"
}

👤 获取用户成就

获取当前用户已解锁的成就。

请求

http

GET /api/achievements/user?include_progress=true
Authorization: Bearer <token>

查询参数

参数	类型	必填	默认值	描述
include_progress	boolean	否	false	是否包含进度信息

响应

json

{
  "success": true,
  "data": {
    "unlocked_achievements": [
      {
        "id": 1,
        "name": "学习新手",
        "description": "完成第一个学习项目",
        "category": "learning",
        "icon": "/assets/ico/achievements/first-study.svg",
        "rarity": "common",
        "points": 10,
        "unlocked_at": "2024-01-10T12:00:00Z",
        "earned_at": "2024-01-10T12:00:00Z"
      }
    ],
    "total_points": 10,
    "achievement_count": 1,
    "recent_achievements": [
      {
        "id": 1,
        "name": "学习新手",
        "unlocked_at": "2024-01-10T12:00:00Z"
      }
    ]
  },
  "message": "获取用户成就成功"
}

🔓 解锁成就

管理员手动解锁用户成就。

请求

http

POST /api/achievements/1/unlock
Content-Type: application/json
Authorization: Bearer <token>

{
  "user_id": 1,
  "notes": "手动解锁成就"
}

请求参数

参数	类型	必填	描述
user_id	number	是	用户ID
notes	string	否	解锁说明

响应

json

{
  "success": true,
  "data": {
    "achievement_id": 1,
    "user_id": 1,
    "unlocked_at": "2024-01-15T12:00:00Z",
    "points_earned": 10
  },
  "message": "成就解锁成功"
}

🏷️ 获取成就分类

获取系统支持的成就分类。

请求

http

GET /api/achievements/categories
Authorization: Bearer <token>

响应

json

{
  "success": true,
  "data": [
    {
      "id": "learning",
      "name": "学习成就",
      "description": "与学习相关的成就",
      "icon": "graduation-cap",
      "achievement_count": 10,
      "unlocked_count": 3
    },
    {
      "id": "consistency",
      "name": "坚持成就",
      "description": "与学习坚持相关的成就",
      "icon": "calendar-check",
      "achievement_count": 8,
      "unlocked_count": 2
    },
    {
      "id": "efficiency",
      "name": "效率成就",
      "description": "与学习效率相关的成就",
      "icon": "bolt",
      "achievement_count": 7,
      "unlocked_count": 1
    }
  ],
  "message": "获取成就分类成功"
}

📊 获取成就进度

获取用户在各成就上的进度情况。

请求

http

GET /api/achievements/progress?category=learning
Authorization: Bearer <token>

查询参数

参数	类型	必填	默认值	描述
category	string	否	-	成就分类筛选

响应

json

{
  "success": true,
  "data": {
    "progress": [
      {
        "id": 1,
        "name": "学习新手",
        "current": 1,
        "target": 1,
        "percentage": 100,
        "unlocked": true,
        "unlocked_at": "2024-01-10T12:00:00Z"
      },
      {
        "id": 2,
        "name": "学习达人",
        "current": 67.5,
        "target": 100,
        "percentage": 67.5,
        "unlocked": false
      }
    ],
    "summary": {
      "total_achievements": 25,
      "unlocked_achievements": 8,
      "unlock_rate": 32.0,
      "total_points": 150,
      "next_achievement": {
        "id": 2,
        "name": "学习达人",
        "progress": 67.5
      }
    }
  },
  "message": "获取成就进度成功"
}

🎯 成就类型说明

学习成就 (Learning)

项目完成: 完成指定数量的学习项目
学习时长: 累计学习指定时长
学习频率: 连续学习指定天数

坚持成就 (Consistency)

连续学习: 连续学习指定天数
月度目标: 完成月度学习目标
年度坚持: 坚持学习一整年

效率成就 (Efficiency)

高效学习: 单次学习时长达到指定值
专注时间: 累计专注学习时长
学习质量: 学习效率达到指定标准

🚀 使用示例

JavaScript 示例

javascript

// 获取成就列表
async function getAchievements(token, params = {}) {
  const queryString = new URLSearchParams(params).toString();
  const response = await fetch(`/api/achievements?${queryString}`, {
    headers: {
      'Authorization': `Bearer ${token}`
    }
  });
  return await response.json();
}

// 获取用户成就
async function getUserAchievements(token, includeProgress = false) {
  const response = await fetch(`/api/achievements/user?include_progress=${includeProgress}`, {
    headers: {
      'Authorization': `Bearer ${token}`
    }
  });
  return await response.json();
}

// 获取成就进度
async function getAchievementProgress(token, category = '') {
  const params = category ? `?category=${category}` : '';
  const response = await fetch(`/api/achievements/progress${params}`, {
    headers: {
      'Authorization': `Bearer ${token}`
    }
  });
  return await response.json();
}

cURL 示例

bash

# 获取成就列表
curl -k -X GET "https://localhost:3001/api/achievements?category=learning" \
  -H "Authorization: Bearer YOUR_TOKEN"

# 获取用户成就
curl -k -X GET "https://localhost:3001/api/achievements/user?include_progress=true" \
  -H "Authorization: Bearer YOUR_TOKEN"

# 获取成就进度
curl -k -X GET "https://localhost:3001/api/achievements/progress?category=learning" \
  -H "Authorization: Bearer YOUR_TOKEN"

# 解锁成就 (管理员)
curl -k -X POST https://localhost:3001/api/achievements/1/unlock \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "user_id": 1,
    "notes": "手动解锁成就"
  }'

📝 注意事项

自动解锁: 大部分成就会在满足条件时自动解锁
进度追踪: 系统会实时追踪用户在各成就上的进度
积分奖励: 解锁成就可以获得积分奖励
权限控制: 只有管理员可以手动解锁成就
成就图标: 成就图标支持自定义上传
数据隔离: 域管理员只能管理自己域内的成就数据
WebSocket通知: 成就解锁会通过WebSocket实时通知管理员

🔧 最新修复

成就系统API更新 (2025-01-XX)

修复内容：

修复了成就解锁时的数据隔离问题
优化了成就进度计算逻辑
改进了WebSocket通知机制
增强了成就解锁的积分奖励系统

技术改进：

完善了数据隔离机制，确保域管理员只能管理自己域的数据
优化了成就条件检查逻辑，提高检查效率
改进了WebSocket广播机制，确保通知及时送达
增强了积分奖励的防重复机制

API影响：

成就解锁API现在支持数据隔离验证
WebSocket通知更加稳定和及时
积分奖励机制更加完善
成就进度计算更加准确

💡 提示

成就系统可以激励学习积极性，建议定期查看成就进度，设定学习目标。

成就系统 API ​

📋 接口概览 ​

🏆 获取成就列表 ​

请求 ​

查询参数 ​

响应 ​

🔍 获取单个成就 ​

请求 ​

响应 ​

👤 获取用户成就 ​

请求 ​

查询参数 ​

响应 ​

🔓 解锁成就 ​

请求 ​

请求参数 ​

响应 ​

🏷️ 获取成就分类 ​

请求 ​

响应 ​

📊 获取成就进度 ​

请求 ​

查询参数 ​

响应 ​

🎯 成就类型说明 ​

学习成就 (Learning) ​

坚持成就 (Consistency) ​

效率成就 (Efficiency) ​

🚀 使用示例 ​

JavaScript 示例 ​

cURL 示例 ​

📝 注意事项 ​

🔧 最新修复 ​

成就系统API更新 (2025-01-XX) ​

成就系统 API

📋 接口概览

🏆 获取成就列表

请求

查询参数

响应

🔍 获取单个成就

请求

响应

👤 获取用户成就

请求

查询参数

响应

🔓 解锁成就

请求

请求参数

响应

🏷️ 获取成就分类

请求

响应

📊 获取成就进度

请求

查询参数

响应

🎯 成就类型说明

学习成就 (Learning)

坚持成就 (Consistency)

效率成就 (Efficiency)

🚀 使用示例

JavaScript 示例

cURL 示例

📝 注意事项

🔧 最新修复

成就系统API更新 (2025-01-XX)