yl-frontend/api-docs/entertainment-api.txt

学习娱乐模块接口文档
================

基础信息
-------
- 基础路径: /api/v1/entertainment
- 请求方式: REST
- 数据格式: JSON
- 认证方式: Bearer Token

数据结构
-------

Course 课程对象:
{
  id: number,          // 课程ID
  title: string,       // 课程标题
  description: string, // 课程描述
  cover: string,       // 封面图片
  category: string,    // 课程分类
  students: number,    // 学习人数
  progress: number,    // 学习进度
  videoUrl: string,    // 视频地址
  chapters: [          // 课程章节
    {
      id: number,
      title: string,
      description: string
    }
  ]
}

LiveChannel 直播频道:
{
  id: number,          // 频道ID
  title: string,       // 直播标题
  anchor: string,      // 主播名称
  cover: string,       // 封面图片
  status: string,      // 状态(live/upcoming/ended)
  viewers: number,     // 观看人数
  likes: number        // 点赞数
}

Game 游戏对象:
{
  id: number,          // 游戏ID
  name: string,        // 游戏名称
  icon: string,        // 游戏图标
  players: number,     // 在线人数
  type: string,        // 游戏类型
  description: string  // 游戏描述
}

Book 电子书对象:
{
  id: number,          // 书籍ID
  title: string,       // 书名
  author: string,      // 作者
  cover: string,       // 封面
  progress: number,    // 阅读进度
  category: string,    // 分类
  description: string  // 描述
}

InterestGroup 兴趣小组:
{
  id: number,          // 小组ID
  name: string,        // 小组名称
  members: number,     // 成员数量
  tags: string[],      // 标签
  joined: boolean,     // 是否已加入
  description: string, // 小组描述
  activities: number   // 活动数量
}

API 接口
-------

1. 获取课程列表
GET /api/v1/entertainment/courses

请求参数：
| 参数名    | 类型   | 必填 | 说明 |
| category | string | 否   | 课程分类 |

响应示例：
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 1,
      "title": "太极拳基础教学",
      "description": "适合老年人的太极拳入门课程",
      "cover": "https://example.com/course1.jpg",
      "category": "health",
      "students": 128,
      "progress": 60,
      "videoUrl": "https://example.com/course1.mp4",
      "chapters": [
        {
          "id": 1,
          "title": "基础站姿",
          "description": "学习太极拳的基本站姿"
        }
      ]
    }
  ]
}

2. 获取课程详情
GET /api/v1/entertainment/courses/{id}

3. 更新学习进度
POST /api/v1/entertainment/courses/{id}/progress

请求参数：
{
  "progress": 75  // 进度百分比
}

4. 获取直播频道
GET /api/v1/entertainment/live

响应示例：
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 1,
      "title": "广场舞教学",
      "anchor": "张老师",
      "cover": "https://example.com/live1.jpg",
      "status": "live",
      "viewers": 256,
      "likes": 128
    }
  ]
}

5. 开始直播
POST /api/v1/entertainment/live/{id}/start

6. 点赞直播
POST /api/v1/entertainment/live/{id}/like

7. 获取游戏列表
GET /api/v1/entertainment/games

请求参数：
| 参数名 | 类型   | 必填 | 说明 |
| type   | string | 否   | 游戏类型 |

8. 获取电子书列表
GET /api/v1/entertainment/books

请求参数：
| 参数名    | 类型   | 必填 | 说明 |
| category | string | 否   | 图书分类 |

9. 更新阅读进度
POST /api/v1/entertainment/books/{id}/progress

请求参数：
{
  "progress": 45  // 阅读进度百分比
}

10. 获取兴趣小组
GET /api/v1/entertainment/groups

11. 加入/退出小组
POST /api/v1/entertainment/groups/{id}/membership

12. 保存学习笔记
POST /api/v1/entertainment/courses/{id}/notes

请求参数：
{
  "content": "学习笔记内容"
}

13. 获取学习统计
GET /api/v1/entertainment/stats

响应示例：
{
  "code": 200,
  "message": "success",
  "data": {
    "totalTime": 1500,
    "completedCourses": 5,
    "certificates": 2
  }
}

错误码说明
--------
| 错误码 | 说明 |
| 200    | 成功 |
| 400    | 请求参数错误 |
| 401    | 未授权 |
| 403    | 禁止访问 |
| 404    | 资源不存在 |
| 500    | 服务器内部错误 |

注意事项
-------
1. 课程相关：
   - 视频支持断点续播
   - 进度自动保存
   - 支持倍速播放

2. 直播相关：
   - 支持实时互动
   - 支持回放功能
   - 网络自适应码率

3. 游戏相关：
   - 支持在线对战
   - 支持AI对手
   - 支持排行榜

4. 电子书相关：
   - 支持字体大小调节
   - 支持夜间模式
   - 支持书签功能

5. 小组相关：
   - 支持群聊功能
   - 支持活动发起
   - 支持资源共享