首页 › API 参考 › 学习路线接口
API 参考

学习路线接口

学习路线模块提供路线的创建、AI 生成、报名、进度跟踪等功能，挂载于 /api/learning-paths。所有接口均需认证。

获取学习路线列表

GET /api/learning-paths

获取公开路线及当前用户创建的路线，支持筛选和分页。

Query 参数

参数说明
subject按科目筛选
difficultybeginner / intermediate / advanced
page页码，默认 1
limit每页数量，默认 20

成功响应 200

{
  "success": true,
  "data": {
    "paths": [
      {
        "id": "uuid",
        "title": "高中数学函数专题",
        "description": "从基础函数概念到高阶应用",
        "subject": "数学",
        "grade": "高中",
        "difficulty": "intermediate",
        "estimated_hours": 20,
        "is_public": 1,
        "creator_name": "张老师",
        "enrolled_count": 15,
        "created_at": "2024-01-15T08:00:00.000Z"
      }
    ],
    "total": 50,
    "page": 1,
    "limit": 20
  }
}

获取路线详情

GET /api/learning-paths/:id

获取学习路线完整信息，包含所有学习节点和当前用户的学习进度。

成功响应 200

{
  "success": true,
  "data": {
    "id": "uuid",
    "title": "高中数学函数专题",
    "nodes": [
      {
        "id": "uuid",
        "path_id": "uuid",
        "title": "函数的基本概念",
        "description": "学习函数定义、定义域、值域",
        "content": "## 函数基本概念\n\n...",
        "node_type": "lesson",
        "order_index": 0,
        "estimated_minutes": 45,
        "prerequisites": [],
        "resources": ["人教版数学必修1 第1章"]
      }
    ],
    "userProgress": {
      "status": "in_progress",
      "progress_percentage": 30,
      "current_node_id": "uuid",
      "started_at": "2024-01-10T08:00:00.000Z"
    }
  }
}

AI 生成学习路线

POST /api/learning-paths/generate 🤖 AI · 限速 20次/分钟

根据学生信息，调用 AI 生成完整的学习路线（含多个节点），并自动保存到数据库。

请求体

{
  "subject": "数学",              // 必填
  "grade": "高中二年级",          // 必填
  "currentLevel": "基础",         // 必填：初学/基础/中级/高级
  "goals": "掌握函数的基本概念和图像，能解决高考常见函数题型"  // 必填
}

成功响应 201

{
  "success": true,
  "message": "学习路线生成成功",
  "data": {
    "id": "uuid",
    "title": "高中数学函数专项突破",
    "description": "...",
    "difficulty": "intermediate",
    "estimated_hours": 30,
    "nodes": [
      {
        "title": "函数的概念与性质",
        "node_type": "lesson",
        "estimated_minutes": 60,
        "order_index": 0,
        "resources": ["人教版数学必修1"]
      }
    ]
  }
}

手动创建学习路线

POST /api/learning-paths

请求体

{
  "title": "物理力学专题",        // 必填
  "subject": "物理",              // 必填
  "description": "从牛顿定律到运动学",  // 可选
  "grade": "高中一年级",          // 可选
  "difficulty": "beginner",       // 可选
  "estimatedHours": 15            // 可选
}

报名加入路线

POST /api/learning-paths/:id/enroll

将当前用户加入指定学习路线。若已报名，直接返回成功。无需请求体。

成功响应 201

{ "success": true, "message": "报名成功", "data": { "id": "uuid" } }

更新学习进度

PUT /api/learning-paths/:id/progress

请求体

{
  "currentNodeId": "uuid",       // 当前学习到的节点 ID
  "progressPercentage": 45,      // 总体完成百分比 0-100
  "status": "in_progress"        // enrolled / in_progress / completed
}
当 progressPercentage 为 100 时，系统自动记录 completed_at 完成时间。

获取我已报名的路线

GET /api/learning-paths/my/enrolled

返回当前用户报名的所有学习路线及其进度信息。

添加路线节点

POST /api/learning-paths/:id/nodes

只有路线创建者才能添加节点。

请求体

{
  "title": "函数的图像与变换",   // 必填
  "description": "学习函数图像的平移、翻转",
  "content": "## 内容...",       // Markdown 格式
  "nodeType": "lesson",          // lesson / quiz / project
  "orderIndex": 1,
  "estimatedMinutes": 45,
  "resources": ["教材第2章"]
}