lq/nl-video-api
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b88c8b8afa5a37984b7871265eb8e99e0847a224
nl-video-api/docs/api-documentation.md
liqi b88c8b8afa 初始化v1
2025-08-03 00:11:15 +08:00

14 KiB
Raw Blame History

nl-video-api 在线影院后端API接口文档

1. 接口概述

1.1 基本信息

  • 项目名称: nl-video-api 在线影院后端系统
  • 版本: v1.0.0
  • 基础URL: http://localhost:8000/api/v1
  • 认证方式: JWT Token
  • 数据格式: JSON

1.2 通用响应格式

{
  "code": 0,           // 状态码，0表示成功，非0表示失败
  "message": "success", // 响应消息
  "data": {}           // 响应数据，可能为对象、数组或null
}

1.3 通用错误码

错误码 说明
0 成功
1001 参数错误
1002 业务逻辑错误
1003 认证失败
1004 权限不足
1005 资源不存在
1006 资源已存在
1007 服务器内部错误

1.4 认证说明

  • 除了登录接口外，所有接口都需要在请求头中携带JWT Token
  • Header格式: Authorization: Bearer {token}

2. 认证模块

2.1 管理员登录

接口地址: POST /auth/admin/login

请求参数:

{
  "username": "admin",     // 用户名，必填
  "password": "123456"     // 密码，必填
}

响应示例:

{
  "code": 0,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "admin": {
      "id": 1,
      "username": "admin",
      "nickname": "超级管理员",
      "email": "admin@example.com",
      "status": 1,
      "last_login_time": "2024-01-01 12:00:00"
    }
  }
}

2.2 管理员注册

接口地址: POST /auth/admin/register

请求参数:

{
  "username": "newadmin",      // 用户名，必填，2-20位
  "password": "123456",        // 密码，必填，6-20位
  "nickname": "新管理员",       // 昵称，必填，2-20位
  "email": "admin@example.com" // 邮箱，必填
}

2.3 获取当前用户信息

接口地址: GET /auth/admin/info

请求头: Authorization: Bearer {token}

响应示例:

{
  "code": 0,
  "message": "获取成功",
  "data": {
    "id": 1,
    "username": "admin",
    "nickname": "超级管理员",
    "email": "admin@example.com",
    "status": 1,
    "permissions": ["user:list", "movie:create", "role:assign"]
  }
}

3. 影片管理模块

3.1 获取影片列表

接口地址: GET /movies

请求参数:

参数名 类型 必填 说明
page int 否 页码，默认1
page_size int 否 每页数量，默认20
title string 否 影片标题模糊搜索
category_id int 否 分类ID
type int 否 影片类型：1电影，2电视剧
status int 否 状态：0禁用，1启用
year int 否 年份
country string 否 国家/地区

响应示例:

{
  "code": 0,
  "message": "获取成功",
  "data": {
    "list": [
      {
        "id": 1,
        "title": "复仇者联盟",
        "type": 1,
        "category_id": 1,
        "category_name": "动作片",
        "cover": "https://example.com/cover.jpg",
        "year": 2012,
        "country": "美国",
        "director": "乔斯·韦登",
        "actors": "小罗伯特·唐尼,克里斯·埃文斯",
        "rating": 8.5,
        "duration": 143,
        "status": 1,
        "created_at": "2024-01-01 12:00:00"
      }
    ],
    "total": 100,
    "page": 1,
    "page_size": 20
  }
}

3.2 创建影片

接口地址: POST /admin/movies

请求头: Authorization: Bearer {token}

请求参数:

{
  "title": "新影片",           // 影片标题，必填
  "type": 1,                 // 影片类型：1电影，2电视剧，必填
  "category_id": 1,          // 分类ID，必填
  "cover": "cover.jpg",      // 封面图片，可选
  "year": 2024,              // 年份，必填
  "country": "中国",          // 国家/地区，必填
  "director": "导演名",       // 导演，可选
  "actors": "演员1,演员2",    // 演员，可选
  "description": "影片描述",  // 描述，可选
  "duration": 120,           // 时长（分钟），电影必填
  "total_episodes": 24,      // 总集数，电视剧必填
  "status": 1                // 状态：0禁用，1启用
}

3.3 更新影片

接口地址: PUT /admin/movies/{id}

请求参数: 同创建影片，所有字段可选

3.4 删除影片

接口地址: DELETE /admin/movies/{id}

3.5 获取影片详情

接口地址: GET /movies/{id}

响应示例:

{
  "code": 0,
  "message": "获取成功",
  "data": {
    "id": 1,
    "title": "复仇者联盟",
    "type": 1,
    "category_id": 1,
    "category_name": "动作片",
    "cover": "https://example.com/cover.jpg",
    "year": 2012,
    "country": "美国",
    "director": "乔斯·韦登",
    "actors": "小罗伯特·唐尼,克里斯·埃文斯",
    "description": "超级英雄集结拯救世界",
    "rating": 8.5,
    "duration": 143,
    "view_count": 10000,
    "like_count": 500,
    "status": 1,
    "episodes": [  // 如果是电视剧，包含剧集信息
      {
        "id": 1,
        "episode_number": 1,
        "title": "第1集",
        "duration": 45,
        "video_url": "https://example.com/video1.mp4"
      }
    ],
    "created_at": "2024-01-01 12:00:00",
    "updated_at": "2024-01-01 12:00:00"
  }
}

4. 用户管理模块

4.1 获取用户列表

接口地址: GET /admin/users

请求头: Authorization: Bearer {token}

请求参数:

参数名 类型 必填 说明
page int 否 页码，默认1
page_size int 否 每页数量，默认20
username string 否 用户名模糊搜索
phone string 否 手机号模糊搜索
email string 否 邮箱模糊搜索
status int 否 状态：0禁用，1启用
vip_level int 否 VIP等级：0-10
gender int 否 性别：0未知，1男，2女
start_time string 否 注册开始时间
end_time string 否 注册结束时间

响应示例:

{
  "code": 0,
  "message": "获取成功",
  "data": {
    "list": [
      {
        "id": 1,
        "username": "user001",
        "phone": "13800138000",
        "email": "user@example.com",
        "nickname": "普通用户",
        "avatar": "https://example.com/avatar.jpg",
        "gender": 1,
        "vip_level": 2,
        "vip_expire_time": "2024-12-31 23:59:59",
        "balance": 100.50,
        "points": 1000,
        "status": 1,
        "last_login_time": "2024-01-01 12:00:00",
        "last_login_ip": "192.168.1.1",
        "created_at": "2024-01-01 10:00:00"
      }
    ],
    "total": 500,
    "page": 1,
    "page_size": 20
  }
}

4.2 创建用户

接口地址: POST /admin/users

请求参数:

{
  "username": "newuser",       // 用户名，必填，2-20位，唯一
  "phone": "13800138001",      // 手机号，必填，11位，唯一
  "email": "user@example.com", // 邮箱，必填，唯一
  "password": "123456",        // 密码，必填，6-20位
  "nickname": "新用户",        // 昵称，必填，2-20位
  "gender": 1,                 // 性别：0未知，1男，2女
  "vip_level": 0,              // VIP等级，0-10
  "status": 1                  // 状态：0禁用，1启用
}

4.3 更新用户信息

接口地址: PUT /admin/users/{id}

请求参数: 同创建用户，除username外所有字段可选

4.4 删除用户

接口地址: DELETE /admin/users/{id}

4.5 升级用户VIP

接口地址: POST /admin/users/{id}/vip

请求参数:

{
  "vip_level": 3,    // VIP等级，1-10
  "days": 30         // 有效天数
}

4.6 更新用户余额

接口地址: PUT /admin/users/{id}/balance

请求参数:

{
  "amount": 100.50,     // 金额，正数为增加，负数为减少
  "type": 1,            // 类型：1充值，2消费，3退款，4奖励
  "remark": "管理员充值" // 备注
}

4.7 更新用户积分

接口地址: PUT /admin/users/{id}/points

请求参数:

{
  "points": 500,        // 积分，正数为增加，负数为减少
  "type": 1,            // 类型：1签到，2消费，3奖励，4兑换
  "remark": "活动奖励"   // 备注
}

5. 权限管理模块

5.1 获取角色列表

接口地址: GET /admin/roles

请求头: Authorization: Bearer {token}

响应示例:

{
  "code": 0,
  "message": "获取成功",
  "data": {
    "list": [
      {
        "id": 1,
        "name": "超级管理员",
        "code": "super_admin",
        "level": 1,
        "description": "系统最高权限",
        "sort": 1,
        "status": 1,
        "is_system": 1,
        "created_at": "2024-01-01 10:00:00"
      }
    ],
    "total": 5,
    "page": 1,
    "page_size": 20
  }
}

5.2 创建角色

接口地址: POST /admin/roles

请求参数:

{
  "name": "内容管理员",        // 角色名称，必填，2-50位
  "code": "content_admin",    // 角色编码，必填，2-50位，唯一
  "level": 3,                 // 角色等级，1-10
  "description": "负责内容管理", // 角色描述
  "sort": 10,                 // 排序
  "status": 1                 // 状态：0禁用，1启用
}

5.3 为角色分配权限

接口地址: POST /admin/roles/{id}/permissions

请求参数:

{
  "permission_ids": [1, 2, 3, 4, 5]  // 权限ID数组
}

5.4 获取权限列表

接口地址: GET /admin/permissions

响应示例:

{
  "code": 0,
  "message": "获取成功",
  "data": {
    "list": [
      {
        "id": 1,
        "name": "用户管理",
        "code": "user:manage",
        "type": 1,
        "parent_id": 0,
        "path": "/admin/users",
        "method": "GET",
        "icon": "user",
        "sort": 1,
        "status": 1,
        "children": [
          {
            "id": 2,
            "name": "用户列表",
            "code": "user:list",
            "type": 2,
            "parent_id": 1,
            "path": "/admin/users",
            "method": "GET"
          }
        ]
      }
    ]
  }
}

6. 分类管理模块

6.1 获取分类列表

接口地址: GET /categories

响应示例:

{
  "code": 0,
  "message": "获取成功",
  "data": {
    "list": [
      {
        "id": 1,
        "name": "动作片",
        "parent_id": 0,
        "sort": 1,
        "status": 1,
        "children": [
          {
            "id": 2,
            "name": "科幻动作",
            "parent_id": 1,
            "sort": 1,
            "status": 1
          }
        ]
      }
    ]
  }
}

6.2 创建分类

接口地址: POST /admin/categories

请求参数:

{
  "name": "新分类",      // 分类名称，必填
  "parent_id": 0,       // 父分类ID，0为顶级分类
  "sort": 1,            // 排序
  "status": 1           // 状态：0禁用，1启用
}

7. 剧集管理模块

7.1 获取剧集列表

接口地址: GET /admin/movies/{movie_id}/episodes

响应示例:

{
  "code": 0,
  "message": "获取成功",
  "data": {
    "list": [
      {
        "id": 1,
        "movie_id": 1,
        "episode_number": 1,
        "title": "第1集",
        "duration": 45,
        "video_url": "https://example.com/video1.mp4",
        "status": 1,
        "created_at": "2024-01-01 12:00:00"
      }
    ]
  }
}

7.2 创建剧集

接口地址: POST /admin/movies/{movie_id}/episodes

请求参数:

{
  "episode_number": 1,           // 集数，必填
  "title": "第1集",              // 标题，必填
  "duration": 45,                // 时长（分钟），必填
  "video_url": "video1.mp4",     // 视频文件，必填
  "status": 1                    // 状态：0禁用，1启用
}

8. 统计分析模块

8.1 获取系统统计

接口地址: GET /admin/stats

响应示例:

{
  "code": 0,
  "message": "获取成功",
  "data": {
    "users": {
      "total": 10000,
      "today_new": 50,
      "active": 5000,
      "vip": 1000
    },
    "movies": {
      "total": 500,
      "today_new": 5,
      "hot": 100
    },
    "views": {
      "total": 1000000,
      "today": 10000
    }
  }
}

9. 文件上传模块

9.1 上传文件

接口地址: POST /upload

请求方式: multipart/form-data

请求参数:

  • file: 文件，必填
  • type: 文件类型，可选（image/video/document）

响应示例:

{
  "code": 0,
  "message": "上传成功",
  "data": {
    "url": "https://example.com/uploads/2024/01/01/file.jpg",
    "filename": "file.jpg",
    "size": 1024000,
    "type": "image/jpeg"
  }
}

10. 搜索模块

10.1 全局搜索

接口地址: GET /search

请求参数:

参数名 类型 必填 说明
keyword string 是 搜索关键词
type string 否 搜索类型：movie/user/all
page int 否 页码，默认1
page_size int 否 每页数量，默认20

响应示例:

{
  "code": 0,
  "message": "搜索成功",
  "data": {
    "movies": [
      {
        "id": 1,
        "title": "复仇者联盟",
        "cover": "https://example.com/cover.jpg",
        "rating": 8.5,
        "year": 2012
      }
    ],
    "total": 10,
    "page": 1,
    "page_size": 20
  }
}

11. 接口测试说明

11.1 测试环境

  • 服务器地址: http://localhost:8000
  • 测试工具: Postman、ApiPost、VS Code REST Client

11.2 测试流程

  1. 启动服务器: go run main.go
  2. 初始化数据库: go run main.go init-db
  3. 管理员登录获取Token
  4. 使用Token测试其他接口

11.3 测试用例

项目提供了完整的HTTP测试文件：

  • test_movie_api.http - 影片管理接口测试
  • test_user_api.http - 用户管理接口测试
  • test_permission_api.http - 权限管理接口测试

12. 错误处理

12.1 常见错误

错误码 HTTP状态码 错误信息 解决方案
1001 400 参数错误 检查请求参数格式和必填项
1003 401 认证失败 检查Token是否有效
1004 403 权限不足 检查用户权限
1005 404 资源不存在 检查资源ID是否正确
1006 409 资源已存在 检查唯一性约束

12.2 调试建议

  1. 检查请求URL和方法是否正确
  2. 确认请求头包含正确的Token
  3. 验证请求参数格式和类型
  4. 查看服务器日志获取详细错误信息

文档版本: v1.0.0
最后更新: 2024-01-01
维护者: nl-video-api开发团队

Reference in New Issue View Git Blame Copy Permalink