API 文档

学习追踪系统提供了完整的 RESTful API 接口，支持第三方应用集成和二次开发。

🔑 认证方式

系统使用 JWT (JSON Web Token) 进行身份认证：

Authorization: Bearer <your-jwt-token>

获取 Token

POST /api/auth/login
Content-Type: application/json

{
  "username": "your-username",
  "password": "your-password"
}

响应示例:

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": 1,
      "username": "admin",
      "role": "admin"
    }
  }
}

📋 API 概览

认证接口

• 用户登录 - 用户认证和 Token 获取
• 用户注册 - 新用户注册
• Token 刷新 - 刷新访问令牌

项目管理

• 项目管理 API - 完整的项目CRUD操作和统计功能

学习记录

• 学习记录 API - 学习会话管理和统计分析

数据分析

• 数据分析 API - 全面的学习数据统计和分析

成就系统

• 成就系统 API - 成就解锁、进度追踪和展示

积分系统

• 积分系统 API - 积分管理、兑换和记录功能

钉钉通知

• 钉钉群机器人 API - 钉钉群机器人通知配置和管理

联系请求管理

• 联系请求管理 API - 用户联系管理员申请和状态管理

🔧 请求格式

标准请求头

Content-Type: application/json
Authorization: Bearer <token>
Accept: application/json

标准响应格式

{
  "success": true,
  "data": {
    // 响应数据
  },
  "message": "操作成功",
  "timestamp": "2024-01-01T00:00:00Z"
}

错误响应格式

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "参数验证失败",
    "details": {
      "field": "错误字段",
      "reason": "错误原因"
    }
  },
  "timestamp": "2024-01-01T00:00:00Z"
}

📊 状态码说明

状态码	说明
200	请求成功
201	创建成功
400	请求参数错误
401	未授权访问
403	权限不足
404	资源不存在
422	数据验证失败
500	服务器内部错误

🚀 使用示例

JavaScript 示例

// 用户登录
async function login(username, password) {
  const response = await fetch('/api/auth/login', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ username, password })
  });
  
  const data = await response.json();
  return data;
}

// 获取项目列表
async function getProjects(token) {
  const response = await fetch('/api/projects', {
    headers: {
      'Authorization': `Bearer ${token}`
    }
  });
  
  const data = await response.json();
  return data;
}

// 创建学习记录
async function createSession(token, sessionData) {
  const response = await fetch('/api/sessions', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify(sessionData)
  });
  
  const data = await response.json();
  return data;
}

cURL 示例

# 用户登录
curl -k -X POST https://your-server-ip:3001/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"ChangeMe123!"}'

# 获取项目列表
curl -k -X GET https://your-server-ip:3001/api/projects \
  -H "Authorization: Bearer YOUR_TOKEN"

# 创建项目
curl -k -X POST https://your-server-ip:3001/api/projects \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"name":"新项目","description":"项目描述"}'

🔒 安全说明

• HTTPS: 生产环境必须使用 HTTPS
• Token 过期: JWT Token 默认 15 分钟过期
• 刷新令牌: 使用 Refresh Token 获取新的访问令牌
• 权限控制: 基于角色的访问控制 (RBAC)
• 速率限制: API 请求有速率限制保护

📚 更多资源

• 快速开始 - 了解如何开始使用
• 功能指南 - 详细的功能说明
• 部署指南 - 部署和配置说明

---

💡 提示

API 文档会随着系统更新而更新，建议定期查看最新版本。如有问题，请提交 Issue。