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

## 1. 接口概述

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

### 1.2 通用响应格式
```json
{
  "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`

**请求参数**:
```json
{
  "username": "admin",     // 用户名，必填
  "password": "123456"     // 密码，必填
}
```

**响应示例**:
```json
{
  "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`

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

### 2.3 获取当前用户信息
**接口地址**: `GET /auth/admin/info`

**请求头**: `Authorization: Bearer {token}`

**响应示例**:
```json
{
  "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 | 否 | 国家/地区 |

**响应示例**:
```json
{
  "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}`

**请求参数**:
```json
{
  "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}`

**响应示例**:
```json
{
  "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 | 否 | 注册结束时间 |

**响应示例**:
```json
{
  "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`

**请求参数**:
```json
{
  "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`

**请求参数**:
```json
{
  "vip_level": 3,    // VIP等级，1-10
  "days": 30         // 有效天数
}
```

### 4.6 更新用户余额
**接口地址**: `PUT /admin/users/{id}/balance`

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

### 4.7 更新用户积分
**接口地址**: `PUT /admin/users/{id}/points`

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

## 5. 权限管理模块

### 5.1 获取角色列表
**接口地址**: `GET /admin/roles`

**请求头**: `Authorization: Bearer {token}`

**响应示例**:
```json
{
  "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`

**请求参数**:
```json
{
  "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`

**请求参数**:
```json
{
  "permission_ids": [1, 2, 3, 4, 5]  // 权限ID数组
}
```

### 5.4 获取权限列表
**接口地址**: `GET /admin/permissions`

**响应示例**:
```json
{
  "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`

**响应示例**:
```json
{
  "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`

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

## 7. 剧集管理模块

### 7.1 获取剧集列表
**接口地址**: `GET /admin/movies/{movie_id}/episodes`

**响应示例**:
```json
{
  "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`

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

## 8. 统计分析模块

### 8.1 获取系统统计
**接口地址**: `GET /admin/stats`

**响应示例**:
```json
{
  "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）

**响应示例**:
```json
{
  "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 |

**响应示例**:
```json
{
  "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开发团队