积分系统 API

积分系统模块提供了积分管理、积分兑换、积分记录等功能。

📋 接口概览

方法	路径	描述	权限
GET	`/api/points/balance`	获取积分余额	所有用户
GET	`/api/points/records`	获取积分记录	所有用户
GET	`/api/points/products`	获取兑换商品	所有用户
POST	`/api/points/exchange`	兑换商品	所有用户
GET	`/api/points/exchange-records`	获取兑换记录	所有用户
GET	`/api/points-exchange/admin/points-rules`	获取积分规则列表	域管理员
POST	`/api/points-exchange/admin/points-rules`	创建积分规则	域管理员
PUT	`/api/points-exchange/admin/points-rules/:id`	更新积分规则	域管理员
DELETE	`/api/points-exchange/admin/points-rules/:id`	删除积分规则	域管理员

💰 获取积分余额

http

GET /api/points/balance
Authorization: Bearer <token>

响应示例:

json

{
  "success": true,
  "data": {
    "balance": 150,
    "total_earned": 200,
    "total_spent": 50,
    "this_month_earned": 30,
    "level": "bronze",
    "level_name": "青铜会员"
  }
}

📊 获取积分记录

http

GET /api/points/records?page=1&limit=10
Authorization: Bearer <token>

响应示例:

json

{
  "success": true,
  "data": {
    "records": [
      {
        "id": 1,
        "type": "earned",
        "amount": 10,
        "balance": 150,
        "description": "解锁成就：学习新手",
        "source": "achievement",
        "created_at": "2024-01-10T12:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 25,
      "pages": 3
    }
  }
}

🛍️ 获取兑换商品

http

GET /api/points/products?category=all
Authorization: Bearer <token>

响应示例:

json

{
  "success": true,
  "data": {
    "products": [
      {
        "id": 1,
        "name": "学习笔记本",
        "description": "高质量学习笔记本，A5尺寸",
        "category": "stationery",
        "points_required": 20,
        "stock": 50,
        "status": "available"
      }
    ]
  }
}

🛒 兑换商品

http

POST /api/points/exchange
Content-Type: application/json
Authorization: Bearer <token>

{
  "product_id": 1,
  "quantity": 1,
  "notes": "希望尽快发货"
}

响应示例:

json

{
  "success": true,
  "data": {
    "exchange_id": 1,
    "product_id": 1,
    "product_name": "学习笔记本",
    "quantity": 1,
    "points_spent": 20,
    "remaining_balance": 130,
    "status": "pending"
  }
}

📋 获取兑换记录

http

GET /api/points/exchange-records?page=1&limit=10
Authorization: Bearer <token>

响应示例:

json

{
  "success": true,
  "data": {
    "records": [
      {
        "id": 1,
        "product_name": "学习笔记本",
        "quantity": 1,
        "points_spent": 20,
        "status": "approved",
        "created_at": "2024-01-15T12:00:00Z"
      }
    ]
  }
}

🔧 积分规则管理 (域管理员)

获取积分规则列表

http

GET /api/points-exchange/admin/points-rules
Authorization: Bearer <token>

响应示例:

json

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "学习时长奖励",
      "description": "每日学习时长达到指定时间获得积分奖励",
      "trigger_type": "study_duration",
      "conditions": {
        "daily_minutes_required": 30,
        "points_per_day": 5
      },
      "points": 5,
      "is_active": true,
      "sort_order": 1,
      "admin_domain": 13,
      "created_at": "2025-09-03T09:35:38.355Z",
      "updated_at": "2025-09-03T09:35:38.355Z"
    }
  ]
}

创建积分规则

http

POST /api/points-exchange/admin/points-rules
Content-Type: application/json
Authorization: Bearer <token>

{
  "name": "新规则",
  "description": "规则描述",
  "trigger_type": "study_duration",
  "conditions": {
    "daily_minutes_required": 60,
    "points_per_day": 10
  },
  "points": 10,
  "sort_order": 100,
  "is_active": true
}

响应示例:

json

{
  "success": true,
  "data": {
    "success": true,
    "rule_id": 28,
    "message": "创建成功"
  }
}

更新积分规则

http

PUT /api/points-exchange/admin/points-rules/28
Content-Type: application/json
Authorization: Bearer <token>

{
  "name": "更新后的规则",
  "description": "更新后的描述",
  "trigger_type": "study_duration",
  "conditions": {
    "daily_minutes_required": 90,
    "points_per_day": 15
  },
  "points": 15,
  "sort_order": 100,
  "is_active": true
}

响应示例:

json

{
  "success": true
}

删除积分规则

http

DELETE /api/points-exchange/admin/points-rules/28
Authorization: Bearer <token>

响应示例:

json

{
  "success": true
}

积分规则类型

触发类型	描述	条件参数
`study_duration`	学习时长奖励	`daily_minutes_required`, `points_per_day`
`project_completion`	项目完成奖励	`completion_points`
`study_rating`	学习评级奖励	`excellent`, `good`, `average`, `poor`
`continuous_study`	连续学习奖励	`days_required`, `points_per_day`

数据隔离说明

域管理员只能查看和管理自己管理域 (admin_domain) 的积分规则
不同管理域可以创建相同名称的积分规则
系统自动为创建的规则分配当前用户的管理域

🎯 积分获取方式

学习相关

学习时长: 每日学习时长达到要求获得积分奖励
项目完成: 完成学习项目获得基础积分奖励
学习评级: 根据学习时长和项目评级标准获得评级积分奖励
连续学习: 连续学习天数达到要求获得额外奖励
成就解锁: 解锁成就获得积分奖励

积分类型说明

完成奖励积分: 用户录入学习记录即完成项目，获得基础积分奖励
评级奖励积分: 根据学习时长和项目评级标准（优秀/良/中/差）获得相应积分奖励
防重复机制: 评级积分和完成奖励积分分开计算，可以同时获得

其他方式

每日签到: 每日签到获得积分
活动参与: 参与学习活动获得积分

🚀 使用示例

JavaScript 示例

javascript

// 获取积分余额
async function getPointsBalance(token) {
  const response = await fetch('/api/points/balance', {
    headers: {
      'Authorization': `Bearer ${token}`
    }
  });
  return await response.json();
}

// 兑换商品
async function exchangeProduct(token, productId, quantity = 1) {
  const response = await fetch('/api/points/exchange', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify({
      product_id: productId,
      quantity: quantity
    })
  });
  return await response.json();
}

cURL 示例

bash

# 获取积分余额
curl -k -X GET "https://your-server-ip:3001/api/points/balance" \
  -H "Authorization: Bearer YOUR_TOKEN"

# 兑换商品
curl -k -X POST https://localhost:3001/api/points/exchange \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "product_id": 1,
    "quantity": 1
  }'

📝 注意事项

积分获取: 积分主要通过学习和成就获得
积分使用: 积分可用于兑换虚拟商品和服务
兑换审核: 部分商品兑换需要管理员审核
积分等级: 积分达到一定数量可提升会员等级

🔧 最新修复

积分规则管理系统修复 (2025-09-03)

修复内容：

修复了域管理员无法创建积分规则的问题
修复了前端积分规则显示为空的问题
修复了项目完成积分计算错误的问题
完善了数据隔离机制，确保域管理员只能管理自己域的数据

修复效果：

✅ 域管理员可以正常创建、编辑、删除积分规则
✅ 前端正确显示积分规则数据
✅ 项目完成积分计算正确
✅ 数据隔离机制完善，安全性提升

技术改进：

修复了数据库唯一约束，改为按域唯一而不是全局唯一
修复了前端API调用缺少认证头部的问题
修复了积分计算逻辑，正确获取项目完成积分
添加了完整的管理端API路由

积分系统防重复机制优化 (2025-09-02)

修复内容：

修复了评级积分和完成奖励积分无法同时获得的问题
优化了防重复检查逻辑，让两种积分类型分开计算
统一了积分记录描述格式，确保防重复检查的准确性

修复效果：

✅ 用户现在可以同时获得评级积分和完成奖励积分
✅ 防重复机制仍然有效，防止真正的重复获取
✅ 积分系统功能完全正常，测试验证通过

技术改进：

修改了isDuplicatePointsEarning方法，为不同规则类型使用不同的检查策略
统一了积分记录描述格式
保持了向后兼容性

API影响：

积分记录API返回的数据结构保持不变
积分获取逻辑更加准确和完整
用户可以获得更完整的积分奖励

积分系统API更新 (2025-01-XX)

新增功能：

添加了积分规则管理API的完整文档
更新了积分获取方式的详细说明
完善了数据隔离机制的API说明

API改进：

优化了积分记录查询接口的响应格式
改进了积分规则创建和更新的验证逻辑
增强了错误处理和状态码返回

安全增强：

加强了积分规则的数据隔离验证
改进了API权限控制机制
优化了防重复积分的检查逻辑

💡 提示

积分系统可以激励学习积极性，建议合理规划积分使用。现在用户可以获得更完整的积分奖励，包括完成奖励和评级奖励。

积分系统 API ​

📋 接口概览 ​

💰 获取积分余额 ​

📊 获取积分记录 ​

🛍️ 获取兑换商品 ​

🛒 兑换商品 ​

📋 获取兑换记录 ​

🔧 积分规则管理 (域管理员) ​

获取积分规则列表 ​

创建积分规则 ​

更新积分规则 ​

删除积分规则 ​

积分规则类型 ​

数据隔离说明 ​

🎯 积分获取方式 ​

学习相关 ​

积分类型说明 ​

其他方式 ​

🚀 使用示例 ​

JavaScript 示例 ​

cURL 示例 ​

📝 注意事项 ​

🔧 最新修复 ​

积分规则管理系统修复 (2025-09-03) ​

积分系统防重复机制优化 (2025-09-02) ​

积分系统API更新 (2025-01-XX) ​

积分系统 API

📋 接口概览

💰 获取积分余额

📊 获取积分记录

🛍️ 获取兑换商品

🛒 兑换商品

📋 获取兑换记录

🔧 积分规则管理 (域管理员)

获取积分规则列表

创建积分规则

更新积分规则

删除积分规则

积分规则类型

数据隔离说明

🎯 积分获取方式

学习相关

积分类型说明

其他方式

🚀 使用示例

JavaScript 示例

cURL 示例

📝 注意事项

🔧 最新修复

积分规则管理系统修复 (2025-09-03)

积分系统防重复机制优化 (2025-09-02)

积分系统API更新 (2025-01-XX)