# nl-video-api 错误码定义文档

## 1. 错误码规范

### 1.1 错误码格式
- 错误码采用4位数字格式
- 第1位表示错误类型：1-业务错误，2-系统错误，3-第三方错误
- 第2-4位表示具体错误编号

### 1.2 响应格式
```json
{
  "code": 1001,
  "message": "参数错误：用户名不能为空",
  "data": null
}
```

## 2. 通用错误码 (1000-1099)

| 错误码 | 错误信息 | 说明 | HTTP状态码 |
|--------|----------|------|------------|
| 0 | 成功 | 请求成功 | 200 |
| 1001 | 参数错误 | 请求参数格式错误或缺少必填参数 | 400 |
| 1002 | 业务逻辑错误 | 业务规则验证失败 | 400 |
| 1003 | 认证失败 | Token无效或已过期 | 401 |
| 1004 | 权限不足 | 用户没有访问该资源的权限 | 403 |
| 1005 | 资源不存在 | 请求的资源不存在 | 404 |
| 1006 | 资源已存在 | 创建的资源已存在（违反唯一性约束） | 409 |
| 1007 | 服务器内部错误 | 系统内部错误 | 500 |
| 1008 | 请求方法不允许 | HTTP方法不被允许 | 405 |
| 1009 | 请求频率过高 | 请求过于频繁，触发限流 | 429 |
| 1010 | 文件上传失败 | 文件上传过程中出现错误 | 400 |

## 3. 认证模块错误码 (1100-1199)

| 错误码 | 错误信息 | 说明 |
|--------|----------|------|
| 1101 | 用户名或密码错误 | 登录凭证不正确 |
| 1102 | 账户已被禁用 | 用户账户状态为禁用 |
| 1103 | 账户已被锁定 | 用户账户被临时锁定 |
| 1104 | Token已过期 | JWT Token已过期，需要重新登录 |
| 1105 | Token格式错误 | JWT Token格式不正确 |
| 1106 | 用户名已存在 | 注册时用户名已被使用 |
| 1107 | 邮箱已存在 | 注册时邮箱已被使用 |
| 1108 | 手机号已存在 | 注册时手机号已被使用 |
| 1109 | 验证码错误 | 短信或邮箱验证码不正确 |
| 1110 | 验证码已过期 | 验证码超过有效期 |
| 1111 | 原密码错误 | 修改密码时原密码不正确 |
| 1112 | 新密码不能与原密码相同 | 密码修改规则限制 |

## 4. 用户管理模块错误码 (1200-1299)

| 错误码 | 错误信息 | 说明 |
|--------|----------|------|
| 1201 | 用户不存在 | 指定的用户ID不存在 |
| 1202 | 用户名格式错误 | 用户名长度或格式不符合要求 |
| 1203 | 手机号格式错误 | 手机号格式不正确 |
| 1204 | 邮箱格式错误 | 邮箱格式不正确 |
| 1205 | 密码格式错误 | 密码长度或复杂度不符合要求 |
| 1206 | 昵称格式错误 | 昵称长度不符合要求 |
| 1207 | 性别参数错误 | 性别参数值不在允许范围内 |
| 1208 | VIP等级参数错误 | VIP等级不在允许范围内 |
| 1209 | 用户状态参数错误 | 用户状态参数值不正确 |
| 1210 | 余额不足 | 用户账户余额不足 |
| 1211 | 积分不足 | 用户积分不足 |
| 1212 | VIP已过期 | 用户VIP会员已过期 |
| 1213 | 不能删除系统用户 | 系统预设用户不允许删除 |
| 1214 | 批量操作用户数量超限 | 批量操作的用户数量超过限制 |

## 5. 影片管理模块错误码 (1300-1399)

| 错误码 | 错误信息 | 说明 |
|--------|----------|------|
| 1301 | 影片不存在 | 指定的影片ID不存在 |
| 1302 | 影片标题不能为空 | 影片标题为必填项 |
| 1303 | 影片类型错误 | 影片类型参数不正确 |
| 1304 | 分类不存在 | 指定的分类ID不存在 |
| 1305 | 年份格式错误 | 年份参数格式不正确 |
| 1306 | 国家地区不能为空 | 国家地区为必填项 |
| 1307 | 时长参数错误 | 影片时长参数不正确 |
| 1308 | 总集数参数错误 | 电视剧总集数参数不正确 |
| 1309 | 影片状态参数错误 | 影片状态参数不正确 |
| 1310 | 封面图片格式错误 | 封面图片格式不支持 |
| 1311 | 视频文件格式错误 | 视频文件格式不支持 |
| 1312 | 影片已存在 | 相同标题和年份的影片已存在 |
| 1313 | 不能删除有剧集的影片 | 存在剧集的影片不允许删除 |
| 1314 | 评分参数错误 | 评分必须在0-10之间 |

## 6. 剧集管理模块错误码 (1400-1499)

| 错误码 | 错误信息 | 说明 |
|--------|----------|------|
| 1401 | 剧集不存在 | 指定的剧集ID不存在 |
| 1402 | 集数参数错误 | 集数必须为正整数 |
| 1403 | 剧集标题不能为空 | 剧集标题为必填项 |
| 1404 | 剧集时长参数错误 | 剧集时长必须为正数 |
| 1405 | 视频文件不能为空 | 视频文件为必填项 |
| 1406 | 剧集状态参数错误 | 剧集状态参数不正确 |
| 1407 | 剧集已存在 | 相同集数的剧集已存在 |
| 1408 | 集数超出范围 | 集数不能超过影片总集数 |
| 1409 | 视频文件不存在 | 指定的视频文件不存在 |
| 1410 | 不能删除最后一集 | 至少需要保留一集 |

## 7. 权限管理模块错误码 (1500-1599)

| 错误码 | 错误信息 | 说明 |
|--------|----------|------|
| 1501 | 角色不存在 | 指定的角色ID不存在 |
| 1502 | 角色名称不能为空 | 角色名称为必填项 |
| 1503 | 角色编码不能为空 | 角色编码为必填项 |
| 1504 | 角色编码已存在 | 角色编码必须唯一 |
| 1505 | 角色等级参数错误 | 角色等级必须在1-10之间 |
| 1506 | 不能删除系统角色 | 系统预设角色不允许删除 |
| 1507 | 不能修改系统角色 | 系统预设角色不允许修改 |
| 1508 | 权限不存在 | 指定的权限ID不存在 |
| 1509 | 权限名称不能为空 | 权限名称为必填项 |
| 1510 | 权限编码不能为空 | 权限编码为必填项 |
| 1511 | 权限编码已存在 | 权限编码必须唯一 |
| 1512 | 权限类型参数错误 | 权限类型参数不正确 |
| 1513 | 父权限不存在 | 指定的父权限ID不存在 |
| 1514 | 不能删除有子权限的权限 | 存在子权限的权限不允许删除 |
| 1515 | 角色权限分配失败 | 角色权限关联操作失败 |

## 8. 分类管理模块错误码 (1600-1699)

| 错误码 | 错误信息 | 说明 |
|--------|----------|------|
| 1601 | 分类不存在 | 指定的分类ID不存在 |
| 1602 | 分类名称不能为空 | 分类名称为必填项 |
| 1603 | 分类名称已存在 | 同级分类名称必须唯一 |
| 1604 | 父分类不存在 | 指定的父分类ID不存在 |
| 1605 | 不能删除有子分类的分类 | 存在子分类的分类不允许删除 |
| 1606 | 不能删除有影片的分类 | 存在影片的分类不允许删除 |
| 1607 | 分类层级过深 | 分类层级不能超过3级 |
| 1608 | 不能将分类设为自己的子分类 | 分类层级关系错误 |

## 9. 文件上传模块错误码 (1700-1799)

| 错误码 | 错误信息 | 说明 |
|--------|----------|------|
| 1701 | 文件不能为空 | 上传文件为必填项 |
| 1702 | 文件格式不支持 | 文件格式不在允许范围内 |
| 1703 | 文件大小超限 | 文件大小超过最大限制 |
| 1704 | 文件上传失败 | 文件保存过程中出现错误 |
| 1705 | 文件不存在 | 指定的文件不存在 |
| 1706 | 文件已损坏 | 文件内容不完整或已损坏 |
| 1707 | 存储空间不足 | 服务器存储空间不足 |
| 1708 | 文件名包含非法字符 | 文件名格式不正确 |

## 10. 搜索模块错误码 (1800-1899)

| 错误码 | 错误信息 | 说明 |
|--------|----------|------|
| 1801 | 搜索关键词不能为空 | 搜索关键词为必填项 |
| 1802 | 搜索关键词过短 | 搜索关键词至少2个字符 |
| 1803 | 搜索关键词过长 | 搜索关键词不能超过50个字符 |
| 1804 | 搜索类型参数错误 | 搜索类型参数不正确 |
| 1805 | 搜索结果为空 | 没有找到匹配的结果 |
| 1806 | 搜索服务不可用 | 搜索引擎服务异常 |

## 11. 系统错误码 (2000-2999)

| 错误码 | 错误信息 | 说明 |
|--------|----------|------|
| 2001 | 数据库连接失败 | 无法连接到数据库 |
| 2002 | 数据库查询失败 | 数据库查询执行失败 |
| 2003 | 数据库事务失败 | 数据库事务回滚 |
| 2004 | Redis连接失败 | 无法连接到Redis服务 |
| 2005 | 缓存操作失败 | Redis缓存操作失败 |
| 2006 | 配置文件读取失败 | 系统配置文件不存在或格式错误 |
| 2007 | 日志写入失败 | 日志文件写入失败 |
| 2008 | 内存不足 | 系统内存不足 |
| 2009 | 磁盘空间不足 | 系统磁盘空间不足 |
| 2010 | 网络连接超时 | 网络请求超时 |

## 12. 第三方服务错误码 (3000-3999)

| 错误码 | 错误信息 | 说明 |
|--------|----------|------|
| 3001 | 短信发送失败 | 短信服务提供商返回失败 |
| 3002 | 邮件发送失败 | 邮件服务提供商返回失败 |
| 3003 | 支付接口调用失败 | 支付服务提供商返回失败 |
| 3004 | 视频处理失败 | 视频转码服务失败 |
| 3005 | 图片处理失败 | 图片处理服务失败 |
| 3006 | CDN服务异常 | CDN服务不可用 |
| 3007 | 第三方API限流 | 第三方服务请求频率超限 |
| 3008 | 第三方服务维护 | 第三方服务正在维护 |

## 13. 错误处理最佳实践

### 13.1 错误信息国际化
```go
// 错误信息支持多语言
var ErrorMessages = map[string]map[int]string{
    "zh-CN": {
        1001: "参数错误",
        1002: "业务逻辑错误",
        // ...
    },
    "en-US": {
        1001: "Parameter error",
        1002: "Business logic error",
        // ...
    },
}
```

### 13.2 错误日志记录
```go
// 记录详细的错误信息用于调试
func LogError(code int, message string, err error, context map[string]interface{}) {
    log.Error().
        Int("code", code).
        Str("message", message).
        Err(err).
        Interface("context", context).
        Msg("API Error")
}
```

### 13.3 错误响应统一处理
```go
// 统一的错误响应处理
func HandleError(r *ghttp.Request, code int, message string, err error) {
    // 记录错误日志
    LogError(code, message, err, map[string]interface{}{
        "url":    r.URL.String(),
        "method": r.Method,
        "ip":     r.GetClientIp(),
    })
    
    // 返回错误响应
    response.JsonExit(r, code, message)
}
```

### 13.4 客户端错误处理建议
```javascript
// 前端错误处理示例
function handleApiError(error) {
    const { code, message } = error.response.data;
    
    switch (code) {
        case 1003:
            // Token过期，跳转到登录页
            router.push('/login');
            break;
        case 1004:
            // 权限不足，显示提示
            showMessage('权限不足', 'error');
            break;
        default:
            // 其他错误，显示具体错误信息
            showMessage(message, 'error');
    }
}
```

## 14. 错误码维护规范

### 14.1 新增错误码规范
1. 按模块分配错误码范围，避免冲突
2. 错误码必须有明确的含义和说明
3. 错误信息要简洁明了，便于用户理解
4. 新增错误码需要更新文档和测试用例

### 14.2 错误码废弃流程
1. 标记为废弃状态，但保留定义
2. 在新版本中移除废弃的错误码
3. 更新相关文档和代码

### 14.3 错误码版本管理
- 错误码定义纳入版本控制
- 重大变更需要版本号升级
- 保持向后兼容性

---

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