学习记录 API

学习记录模块提供了学习会话的完整管理功能，包括记录学习时间、查询历史记录、统计分析等。

📋 接口概览

方法	路径	描述	权限
GET	`/api/sessions`	获取学习记录列表	所有用户
GET	`/api/sessions/:id`	获取单个学习记录	所有用户
POST	`/api/sessions`	创建学习记录	所有用户
PUT	`/api/sessions/:id`	更新学习记录	记录所有者/管理员
DELETE	`/api/sessions/:id`	删除学习记录	记录所有者/管理员
POST	`/api/sessions/start`	开始学习会话	所有用户
POST	`/api/sessions/:id/end`	结束学习会话	记录所有者
GET	`/api/sessions/stats`	获取学习统计	所有用户
GET	`/api/sessions/calendar`	获取日历数据	所有用户

🔍 获取学习记录列表

获取当前用户的学习记录列表，支持分页和筛选。

请求

http

GET /api/sessions?page=1&limit=10&project_id=1&start_date=2024-01-01&end_date=2024-01-31
Authorization: Bearer <token>

查询参数

参数	类型	必填	默认值	描述
page	number	否	1	页码
limit	number	否	10	每页数量
project_id	number	否	-	项目ID筛选
start_date	string	否	-	开始日期 (YYYY-MM-DD)
end_date	string	否	-	结束日期 (YYYY-MM-DD)
sort	string	否	study_date	排序字段
order	string	否	desc	排序方向 (asc, desc)

响应

json

{
  "success": true,
  "data": {
    "sessions": [
      {
        "id": 1,
        "project_id": 1,
        "project_name": "数学学习",
        "study_date": "2024-01-15",
        "start_time": "10:00:00",
        "end_time": "12:30:00",
        "duration": 150,
        "duration_hours": 2.5,
        "notes": "学习了微积分基础",
        "created_at": "2024-01-15T10:00:00Z",
        "updated_at": "2024-01-15T12:30:00Z",
        "user_id": 1
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 45,
      "pages": 5
    }
  },
  "message": "获取学习记录成功"
}

➕ 创建学习记录

创建新的学习记录。

请求

http

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

{
  "project_name": "数学学习",
  "study_date": "2024-01-15",
  "start_time": "10:00:00",
  "end_time": "12:30:00",
  "notes": "学习了微积分基础"
}

请求参数

参数	类型	必填	描述
project_id	number	否	项目ID
project_name	string	否	项目名称
study_date	string	是	学习日期 (YYYY-MM-DD)
start_time	string	是	开始时间 (HH:MM:SS)
end_time	string	是	结束时间 (HH:MM:SS)
notes	string	否	学习笔记 (最大500字符)

响应

json

{
  "success": true,
  "data": {
    "id": 2,
    "project_id": 1,
    "project_name": "数学学习",
    "study_date": "2024-01-15",
    "start_time": "10:00:00",
    "end_time": "12:30:00",
    "duration": 150,
    "duration_hours": 2.5,
    "notes": "学习了微积分基础",
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T10:00:00Z",
    "user_id": 1
  },
  "message": "学习记录创建成功"
}

▶️ 开始学习会话

开始一个新的学习会话，系统会自动记录开始时间。

请求

http

POST /api/sessions/start
Content-Type: application/json
Authorization: Bearer <token>

{
  "project_id": 1,
  "notes": "开始学习微积分"
}

响应

json

{
  "success": true,
  "data": {
    "session_id": 3,
    "project_id": 1,
    "project_name": "数学学习",
    "start_time": "14:30:00",
    "status": "active",
    "message": "学习会话已开始"
  },
  "message": "学习会话开始成功"
}

⏹️ 结束学习会话

结束当前的学习会话，系统会自动计算学习时长。

请求

http

POST /api/sessions/3/end
Content-Type: application/json
Authorization: Bearer <token>

{
  "notes": "完成了微积分第一章的学习"
}

响应

json

{
  "success": true,
  "data": {
    "id": 3,
    "project_id": 1,
    "project_name": "数学学习",
    "study_date": "2024-01-15",
    "start_time": "14:30:00",
    "end_time": "16:45:00",
    "duration": 135,
    "duration_hours": 2.25,
    "notes": "完成了微积分第一章的学习",
    "status": "completed"
  },
  "message": "学习会话结束成功"
}

📊 获取学习统计

获取用户的学习统计数据。

请求

http

GET /api/sessions/stats?period=month&start_date=2024-01-01&end_date=2024-01-31
Authorization: Bearer <token>

响应

json

{
  "success": true,
  "data": {
    "total_sessions": 45,
    "total_hours": 67.5,
    "average_session_length": 1.5,
    "longest_session": 4.5,
    "shortest_session": 0.25,
    "study_days": 23,
    "current_streak": 5,
    "longest_streak": 12,
    "most_studied_project": {
      "id": 1,
      "name": "数学学习",
      "hours": 25.5
    },
    "daily_average": 2.93
  },
  "message": "获取学习统计成功"
}

📅 获取日历数据

获取用于日历显示的学习记录数据。

请求

http

GET /api/sessions/calendar?year=2024&month=1
Authorization: Bearer <token>

响应

json

{
  "success": true,
  "data": {
    "year": 2024,
    "month": 1,
    "calendar_data": {
      "2024-01-01": [
        {
          "project_name": "数学学习",
          "duration": 120,
          "start_time": "10:00",
          "end_time": "12:00"
        }
      ]
    },
    "monthly_summary": {
      "total_days": 31,
      "study_days": 23,
      "total_hours": 67.5,
      "average_daily_hours": 2.18
    }
  },
  "message": "获取日历数据成功"
}

🚀 使用示例

JavaScript 示例

javascript

// 获取学习记录列表
async function getSessions(token, params = {}) {
  const queryString = new URLSearchParams(params).toString();
  const response = await fetch(`/api/sessions?${queryString}`, {
    headers: {
      'Authorization': `Bearer ${token}`
    }
  });
  return await response.json();
}

// 创建学习记录
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)
  });
  return await response.json();
}

// 开始学习会话
async function startSession(token, projectId, notes = '') {
  const response = await fetch('/api/sessions/start', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify({ project_id: projectId, notes })
  });
  return await response.json();
}

cURL 示例

bash

# 获取学习记录列表
curl -k -X GET "https://your-server-ip:3001/api/sessions?page=1&limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

# 创建学习记录
curl -k -X POST https://your-server-ip:3001/api/sessions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "project_id": 1,
    "study_date": "2024-01-15",
    "start_time": "10:00:00",
    "end_time": "12:30:00",
    "notes": "学习了微积分基础"
  }'

# 开始学习会话
curl -k -X POST https://your-server-ip:3001/api/sessions/start \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "project_id": 1,
    "notes": "开始学习微积分"
  }'

📝 注意事项

时间验证: 结束时间必须晚于开始时间
权限控制: 用户只能操作自己的学习记录
自动计算: 系统会自动计算学习时长
数据完整性: 删除学习记录会影响项目统计
时区处理: 所有时间都使用服务器时区
项目关联: 支持通过项目名称或项目ID关联项目
积分触发: 学习记录创建会自动触发积分规则检查

🔧 最新修复

学习记录API更新 (2025-01-XX)

修复内容：

修复了学习记录更新时的日期格式问题
优化了项目关联逻辑，支持通过项目名称查找项目
改进了时间字段的处理，避免时区转换问题
增强了数据验证和错误处理

技术改进：

修改了时间字段的存储方式，使用日期类型避免时区问题
优化了项目查找逻辑，支持项目名称和ID两种方式
改进了学习记录的更新流程，确保数据一致性
增强了API的容错性和稳定性

API影响：

学习记录创建和更新接口支持更灵活的项目关联方式
时间字段处理更加准确，避免时区转换问题
错误处理更加完善，提供更清晰的错误信息

💡 提示

建议使用开始/结束会话功能来记录学习时间，这样可以获得更准确的学习时长统计。

学习记录 API ​

📋 接口概览 ​

🔍 获取学习记录列表 ​

请求 ​

查询参数 ​

响应 ​

➕ 创建学习记录 ​

请求 ​

请求参数 ​

响应 ​

▶️ 开始学习会话 ​

请求 ​

响应 ​

⏹️ 结束学习会话 ​

请求 ​

响应 ​

📊 获取学习统计 ​

请求 ​

响应 ​

📅 获取日历数据 ​

请求 ​

响应 ​

🚀 使用示例 ​

JavaScript 示例 ​

cURL 示例 ​

📝 注意事项 ​

🔧 最新修复 ​

学习记录API更新 (2025-01-XX) ​

学习记录 API

📋 接口概览

🔍 获取学习记录列表

请求

查询参数

响应

➕ 创建学习记录

请求

请求参数

响应

▶️ 开始学习会话

请求

响应

⏹️ 结束学习会话

请求

响应

📊 获取学习统计

请求

响应

📅 获取日历数据

请求

响应

🚀 使用示例

JavaScript 示例

cURL 示例

📝 注意事项

🔧 最新修复

学习记录API更新 (2025-01-XX)