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

647 lines
14 KiB
Go
Raw Normal View History

初始化v1
2025-08-03 00:11:15 +08:00
# 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开发团队
Reference in New Issue Copy Permalink