视频观看模块接口文档
=================

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

数据结构
-------

Video 视频对象:
{
  id: number,          // 视频ID
  title: string,       // 视频标题
  description: string, // 视频描述
  url: string,        // 视频URL
  thumbnail: string,  // 缩略图URL
  duration: string,   // 视频时长
  category: string,   // 视频分类
  views: number,      // 观看次数
  likes: number,      // 点赞数
  comments: number,   // 评论数
  tags: string[],     // 标签
  uploadTime: string, // 上传时间
  status: string     // 视频状态(active/disabled)
}

API 接口
-------

1. 获取视频列表
GET /api/v1/videos

请求参数：
| 参数名    | 类型   | 必填 | 说明 |
| category | string | 否   | 视频分类 |
| page     | number | 否   | 页码，默认1 |
| size     | number | 否   | 每页数量，默认10 |
| sort     | string | 否   | 排序字段(uploadTime/views/likes) |
| order    | string | 否   | 排序方式(asc/desc) |

响应示例：
{
  "code": 200,
  "message": "success",
  "data": {
    "total": 100,
    "pages": 10,
    "current": 1,
    "records": [
      {
        "id": 1,
        "title": "每日健康操",
        "description": "适合老年人的健康运动视频",
        "url": "http://example.com/video1.mp4",
        "thumbnail": "http://example.com/thumb1.jpg",
        "duration": "10:00",
        "category": "health",
        "views": 1234,
        "likes": 256,
        "comments": 45,
        "tags": ["健康", "运动", "教学"],
        "uploadTime": "2024-03-20 10:00:00",
        "status": "active"
      }
    ]
  }
}

2. 获取视频详情
GET /api/v1/videos/{id}

响应示例：
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "title": "每日健康操",
    "description": "适合老年人的健康运动视频",
    "url": "http://example.com/video1.mp4",
    "thumbnail": "http://example.com/thumb1.jpg",
    "duration": "10:00",
    "category": "health",
    "views": 1234,
    "likes": 256,
    "comments": 45,
    "tags": ["健康", "运动", "教学"],
    "uploadTime": "2024-03-20 10:00:00",
    "status": "active"
  }
}

3. 更新观看次数
POST /api/v1/videos/{id}/view

响应示例：
{
  "code": 200,
  "message": "success",
  "data": {
    "views": 1235
  }
}

4. 点赞视频
POST /api/v1/videos/{id}/like

响应示例：
{
  "code": 200,
  "message": "success",
  "data": {
    "likes": 257
  }
}

5. 获取推荐视频
GET /api/v1/videos/recommended

请求参数：
| 参数名     | 类型   | 必填 | 说明 |
| currentId | number | 否   | 当前视频ID |
| limit     | number | 否   | 返回数量，默认3 |

响应示例：
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 2,
      "title": "太极拳教学",
      "description": "专业老师讲解太极拳基本动作",
      "url": "http://example.com/video2.mp4",
      "thumbnail": "http://example.com/thumb2.jpg",
      "duration": "15:00",
      "category": "health",
      "views": 890,
      "likes": 156,
      "comments": 23,
      "tags": ["太极拳", "运动", "教学"],
      "uploadTime": "2024-03-19 15:00:00",
      "status": "active"
    }
  ]
}

6. 获取热门视频
GET /api/v1/videos/hot

请求参数：
| 参数名 | 类型   | 必填 | 说明 |
| limit  | number | 否   | 返回数量，默认5 |

响应示例：
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 3,
      "title": "广场舞教学",
      "description": "广场舞基础动作教学",
      "url": "http://example.com/video3.mp4",
      "thumbnail": "http://example.com/thumb3.jpg",
      "duration": "20:00",
      "category": "entertainment",
      "views": 2345,
      "likes": 456,
      "comments": 78,
      "tags": ["广场舞", "运动", "教学"],
      "uploadTime": "2024-03-18 14:00:00",
      "status": "active"
    }
  ]
}

7. 获取视频分类
GET /api/v1/videos/categories

响应示例：
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "value": "health",
      "label": "健康讲座",
      "count": 25
    },
    {
      "value": "entertainment",
      "label": "娱乐节目",
      "count": 18
    }
  ]
}

8. 添加视频评论
POST /api/v1/videos/{id}/comments

请求参数：
{
  "content": "视频很有帮助",
  "parentId": null  // 回复其他评论时设置
}

响应示例：
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "content": "视频很有帮助",
    "userId": 10001,
    "userName": "张三",
    "createTime": "2024-03-20 15:30:00",
    "parentId": null,
    "likes": 0
  }
}

9. 获取视频评论列表
GET /api/v1/videos/{id}/comments

请求参数：
| 参数名 | 类型   | 必填 | 说明 |
| page   | number | 否   | 页码，默认1 |
| size   | number | 否   | 每页数量，默认10 |

响应示例：
{
  "code": 200,
  "message": "success",
  "data": {
    "total": 45,
    "pages": 5,
    "current": 1,
    "records": [
      {
        "id": 1,
        "content": "视频很有帮助",
        "userId": 10001,
        "userName": "张三",
        "createTime": "2024-03-20 15:30:00",
        "parentId": null,
        "likes": 5,
        "replies": []
      }
    ]
  }
}

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

注意事项
-------
1. 视频文件上传需要单独处理，建议使用分片上传：
POST /api/v1/videos/upload
Content-Type: multipart/form-data

2. 视频URL需要进行加密和有效期控制，防止视频泄露。

3. 视频播放建议使用 HLS 或 DASH 协议，支持多码率自适应。

4. 缓存策略：
   - 视频元数据缓存：5分钟
   - 视频分类缓存：1小时
   - 热门视频缓存：10分钟