diff --git a/docs/AI代码理解指南.md b/dev-docs/AI代码理解指南.md similarity index 100% rename from docs/AI代码理解指南.md rename to dev-docs/AI代码理解指南.md diff --git a/docs/admin/后台管理前端架构说明.md b/dev-docs/admin/后台管理前端架构说明.md similarity index 100% rename from docs/admin/后台管理前端架构说明.md rename to dev-docs/admin/后台管理前端架构说明.md diff --git a/docs/admin/管理端前端目录结构详细说明.md b/dev-docs/admin/管理端前端目录结构详细说明.md similarity index 100% rename from docs/admin/管理端前端目录结构详细说明.md rename to dev-docs/admin/管理端前端目录结构详细说明.md diff --git a/docs/docker安装说明文档.md b/dev-docs/docker安装说明文档.md similarity index 100% rename from docs/docker安装说明文档.md rename to dev-docs/docker安装说明文档.md diff --git a/docs/phpapi/API接口文档.md b/dev-docs/phpapi/API接口文档.md similarity index 100% rename from docs/phpapi/API接口文档.md rename to dev-docs/phpapi/API接口文档.md diff --git a/docs/phpapi/业务流程说明.md b/dev-docs/phpapi/业务流程说明.md similarity index 100% rename from docs/phpapi/业务流程说明.md rename to dev-docs/phpapi/业务流程说明.md diff --git a/docs/phpapi/会员管理开发文档.md b/dev-docs/phpapi/会员管理开发文档.md similarity index 100% rename from docs/phpapi/会员管理开发文档.md rename to dev-docs/phpapi/会员管理开发文档.md diff --git a/docs/phpapi/分销系统说明文档.md b/dev-docs/phpapi/分销系统说明文档.md similarity index 100% rename from docs/phpapi/分销系统说明文档.md rename to dev-docs/phpapi/分销系统说明文档.md diff --git a/docs/phpapi/后端代码目录结构说明.md b/dev-docs/phpapi/后端代码目录结构说明.md similarity index 100% rename from docs/phpapi/后端代码目录结构说明.md rename to dev-docs/phpapi/后端代码目录结构说明.md diff --git a/docs/phpapi/后端系统事件文档说明.md b/dev-docs/phpapi/后端系统事件文档说明.md similarity index 100% rename from docs/phpapi/后端系统事件文档说明.md rename to dev-docs/phpapi/后端系统事件文档说明.md diff --git a/docs/phpapi/商品管理开发文档.md b/dev-docs/phpapi/商品管理开发文档.md similarity index 100% rename from docs/phpapi/商品管理开发文档.md rename to dev-docs/phpapi/商品管理开发文档.md diff --git a/docs/phpapi/客服系统开发文档.md b/dev-docs/phpapi/客服系统开发文档.md similarity index 100% rename from docs/phpapi/客服系统开发文档.md rename to dev-docs/phpapi/客服系统开发文档.md diff --git a/docs/phpapi/开发规范说明.md b/dev-docs/phpapi/开发规范说明.md similarity index 100% rename from docs/phpapi/开发规范说明.md rename to dev-docs/phpapi/开发规范说明.md diff --git a/docs/phpapi/支付开发流程文档-V2.md b/dev-docs/phpapi/支付开发流程文档-V2.md similarity index 100% rename from docs/phpapi/支付开发流程文档-V2.md rename to dev-docs/phpapi/支付开发流程文档-V2.md diff --git a/docs/phpapi/支付开发流程文档.md b/dev-docs/phpapi/支付开发流程文档.md similarity index 100% rename from docs/phpapi/支付开发流程文档.md rename to dev-docs/phpapi/支付开发流程文档.md diff --git a/docs/phpapi/数据库结构设计.md b/dev-docs/phpapi/数据库结构设计.md similarity index 100% rename from docs/phpapi/数据库结构设计.md rename to dev-docs/phpapi/数据库结构设计.md diff --git a/docs/phpapi/服务管理开发文档.md b/dev-docs/phpapi/服务管理开发文档.md similarity index 100% rename from docs/phpapi/服务管理开发文档.md rename to dev-docs/phpapi/服务管理开发文档.md diff --git a/docs/phpapi/消息通知开发文档.md b/dev-docs/phpapi/消息通知开发文档.md similarity index 100% rename from docs/phpapi/消息通知开发文档.md rename to dev-docs/phpapi/消息通知开发文档.md diff --git a/docs/phpapi/物流管理开发文档.md b/dev-docs/phpapi/物流管理开发文档.md similarity index 100% rename from docs/phpapi/物流管理开发文档.md rename to dev-docs/phpapi/物流管理开发文档.md diff --git a/docs/phpapi/系统分销开发文档.md b/dev-docs/phpapi/系统分销开发文档.md similarity index 100% rename from docs/phpapi/系统分销开发文档.md rename to dev-docs/phpapi/系统分销开发文档.md diff --git a/docs/phpapi/系统安装流程文档.md b/dev-docs/phpapi/系统安装流程文档.md similarity index 100% rename from docs/phpapi/系统安装流程文档.md rename to dev-docs/phpapi/系统安装流程文档.md diff --git a/docs/phpapi/系统用户管理开发文档.md b/dev-docs/phpapi/系统用户管理开发文档.md similarity index 100% rename from docs/phpapi/系统用户管理开发文档.md rename to dev-docs/phpapi/系统用户管理开发文档.md diff --git a/docs/phpapi/系统设置开发文档.md b/dev-docs/phpapi/系统设置开发文档.md similarity index 100% rename from docs/phpapi/系统设置开发文档.md rename to dev-docs/phpapi/系统设置开发文档.md diff --git a/docs/phpapi/系统错误码说明.md b/dev-docs/phpapi/系统错误码说明.md similarity index 100% rename from docs/phpapi/系统错误码说明.md rename to dev-docs/phpapi/系统错误码说明.md diff --git a/docs/phpapi/系统队列任务开发文档.md b/dev-docs/phpapi/系统队列任务开发文档.md similarity index 100% rename from docs/phpapi/系统队列任务开发文档.md rename to dev-docs/phpapi/系统队列任务开发文档.md diff --git a/docs/phpapi/系统队列任务文档说明.md b/dev-docs/phpapi/系统队列任务文档说明.md similarity index 100% rename from docs/phpapi/系统队列任务文档说明.md rename to dev-docs/phpapi/系统队列任务文档说明.md diff --git a/docs/phpapi/统计分析开发文档.md b/dev-docs/phpapi/统计分析开发文档.md similarity index 100% rename from docs/phpapi/统计分析开发文档.md rename to dev-docs/phpapi/统计分析开发文档.md diff --git a/docs/phpapi/营销活动开发文档.md b/dev-docs/phpapi/营销活动开发文档.md similarity index 100% rename from docs/phpapi/营销活动开发文档.md rename to dev-docs/phpapi/营销活动开发文档.md diff --git a/docs/phpapi/订单模块说明.md b/dev-docs/phpapi/订单模块说明.md similarity index 100% rename from docs/phpapi/订单模块说明.md rename to dev-docs/phpapi/订单模块说明.md diff --git a/docs/phpapi/配置参数说明.md b/dev-docs/phpapi/配置参数说明.md similarity index 100% rename from docs/phpapi/配置参数说明.md rename to dev-docs/phpapi/配置参数说明.md diff --git a/docs/phpapi/项目架构说明.md b/dev-docs/phpapi/项目架构说明.md similarity index 100% rename from docs/phpapi/项目架构说明.md rename to dev-docs/phpapi/项目架构说明.md diff --git a/docs/phpapi/项目目录文档.md b/dev-docs/phpapi/项目目录文档.md similarity index 100% rename from docs/phpapi/项目目录文档.md rename to dev-docs/phpapi/项目目录文档.md diff --git a/docs/uniapp/uniapp目录结构.md b/dev-docs/uniapp/uniapp目录结构.md similarity index 100% rename from docs/uniapp/uniapp目录结构.md rename to dev-docs/uniapp/uniapp目录结构.md diff --git a/docs/uniapp/移动端前端架构说明.md b/dev-docs/uniapp/移动端前端架构说明.md similarity index 100% rename from docs/uniapp/移动端前端架构说明.md rename to dev-docs/uniapp/移动端前端架构说明.md diff --git a/docs/uniapp/移动端前端目录结构详细说明.md b/dev-docs/uniapp/移动端前端目录结构详细说明.md similarity index 100% rename from docs/uniapp/移动端前端目录结构详细说明.md rename to dev-docs/uniapp/移动端前端目录结构详细说明.md diff --git a/dev-docs/错误码说明文档.md b/dev-docs/错误码说明文档.md new file mode 100644 index 000000000..907d247eb --- /dev/null +++ b/dev-docs/错误码说明文档.md @@ -0,0 +1,280 @@ +# CRMEB 错误码说明文档 + +## 1. 引言 + +### 1.1 文档目的 +- 规范 CRMEB 系统中的错误码使用 +- 提供错误码的分类和定义标准 +- 为开发人员提供错误处理的参考指南 +- 确保系统错误信息的一致性和可维护性 + +### 1.2 适用范围 +- CRMEB 系统所有模块的开发和维护 +- API 接口错误处理 +- 后台管理系统错误处理 +- 移动端应用错误处理 + +### 1.3 术语定义 +- **错误码**:系统中用于标识特定错误类型的数字编码 +- **异常类**:用于处理和抛出错误的类 +- **多语言**:系统支持的不同语言错误信息 + +## 2. 错误码设计规范 + +### 2.1 错误码格式 +- **格式**:纯数字,长度为 3-6 位 +- **示例**:400, 401, 400001, 400086 + +### 2.2 错误码分类 + +| 范围 | 分类 | 说明 | 示例 | +|------|------|------|------| +| 100-199 | 信息提示 | 一般性信息提示 | 100 | +| 200-299 | 成功响应 | 请求处理成功 | 200 | +| 300-399 | 重定向 | 需要重定向 | 301, 302 | +| 400-499 | 客户端错误 | 客户端请求错误 | 400, 401, 403, 404 | +| 500-599 | 服务器错误 | 服务器内部错误 | 500, 501, 503 | +| 400000-499999 | 业务错误 | 具体业务逻辑错误 | 400086, 400087 | +| 600000-699999 | 系统错误 | 系统级错误 | 600001 | +| 700000-799999 | 第三方错误 | 第三方服务错误 | 700001 | + +### 2.3 错误码命名规则 +- 错误码应具有语义化,便于理解和记忆 +- 同一模块的错误码应集中在一个范围内 +- 错误码应保持唯一性,避免重复 + +## 3. 错误处理机制 + +### 3.1 异常类体系 + +CRMEB 系统使用以下异常类处理错误: + +| 异常类 | 命名空间 | 用途 | +|--------|----------|------| +| ApiException | crmeb\exceptions | API 接口错误 | +| AuthException | crmeb\exceptions | 认证授权错误 | +| AdminException | crmeb\exceptions | 后台管理错误 | +| PayException | crmeb\exceptions | 支付相关错误 | +| CrudException | crmeb\exceptions | CRUD 操作错误 | +| ApiStatusException | crmeb\exceptions | 带状态码的 API 错误 | +| OAuthException | crmeb\services\oauth | OAuth 认证错误 | + +### 3.2 错误抛出方式 + +#### 3.2.1 直接抛出异常 +```php +// 使用错误信息 +throw new ApiException('参数错误'); + +// 使用错误码 +throw new ApiException(400086); + +// 使用错误码和替换参数 +throw new ApiException(400086, ['name' => '用户名']); + +// 使用数组形式 +throw new ApiException([400086, '参数错误']); +``` + +#### 3.2.2 在验证器中使用 +```php +protected $message = [ + 'name.require' => '400086', + 'sort.require' => '400087', + 'sort.number' => '400088' +]; +``` + +### 3.3 错误信息获取 + +系统使用 `getLang()` 函数获取错误信息,支持多语言: + +```php +// 获取错误信息 +$message = getLang($code, $replace); +``` + +## 4. 常见错误码列表 + +### 4.1 基础错误码 + +| 错误码 | 错误信息 | 说明 | 分类 | +|--------|----------|------|------| +| 200 | 操作成功 | 请求处理成功 | 成功响应 | +| 400 | 参数错误 | 请求参数格式错误 | 客户端错误 | +| 401 | 未授权 | 未登录或登录已过期 | 客户端错误 | +| 403 | 禁止访问 | 没有权限执行此操作 | 客户端错误 | +| 404 | 资源不存在 | 请求的资源不存在 | 客户端错误 | +| 500 | 服务器内部错误 | 服务器处理请求时发生错误 | 服务器错误 | +| 501 | 功能未实现 | 请求的功能尚未实现 | 服务器错误 | +| 503 | 服务不可用 | 服务器暂时无法处理请求 | 服务器错误 | + +### 4.2 业务错误码 + +#### 4.2.1 用户相关 + +| 错误码 | 错误信息 | 说明 | +|--------|----------|------| +| 400001 | 用户名已存在 | 注册时用户名已被使用 | +| 400002 | 手机号已被注册 | 注册时手机号已被使用 | +| 400003 | 邮箱已被注册 | 注册时邮箱已被使用 | +| 400004 | 用户名或密码错误 | 登录时用户名或密码不正确 | +| 400005 | 用户不存在 | 请求的用户不存在 | +| 400006 | 账号已被禁用 | 用户账号被管理员禁用 | +| 400007 | 验证码错误 | 验证码不正确 | +| 400008 | 验证码已过期 | 验证码已超过有效期 | + +#### 4.2.2 商品相关 + +| 错误码 | 错误信息 | 说明 | +|--------|----------|------| +| 400101 | 商品不存在 | 请求的商品不存在 | +| 400102 | 商品已下架 | 商品已被下架 | +| 400103 | 商品库存不足 | 商品库存不足 | +| 400104 | 商品价格异常 | 商品价格不符合要求 | +| 400105 | 商品分类不存在 | 请求的商品分类不存在 | + +#### 4.2.3 订单相关 + +| 错误码 | 错误信息 | 说明 | +|--------|----------|------| +| 400201 | 订单不存在 | 请求的订单不存在 | +| 400202 | 订单状态错误 | 订单状态不符合操作要求 | +| 400203 | 订单金额错误 | 订单金额计算错误 | +| 400204 | 支付失败 | 支付过程中发生错误 | +| 400205 | 退款失败 | 退款过程中发生错误 | +| 400206 | 地址信息错误 | 收货地址信息不正确 | + +#### 4.2.4 权限相关 + +| 错误码 | 错误信息 | 说明 | +|--------|----------|------| +| 400301 | 无权限操作 | 用户没有权限执行此操作 | +| 400302 | 角色不存在 | 请求的角色不存在 | +| 400303 | 菜单不存在 | 请求的菜单不存在 | +| 400304 | 权限不足 | 用户权限不足 | + +#### 4.2.5 系统相关 + +| 错误码 | 错误信息 | 说明 | +|--------|----------|------| +| 400401 | 配置错误 | 系统配置错误 | +| 400402 | 网络错误 | 网络连接失败 | +| 400403 | 文件上传失败 | 文件上传过程中发生错误 | +| 400404 | 数据库错误 | 数据库操作失败 | +| 400405 | 缓存错误 | 缓存操作失败 | + +### 4.3 验证器错误码 + +| 错误码 | 错误信息 | 说明 | +|--------|----------|------| +| 400086 | 名称不能为空 | 验证名称字段必填 | +| 400087 | 排序不能为空 | 验证排序字段必填 | +| 400088 | 排序必须为数字 | 验证排序字段必须为数字 | + +## 5. 错误码管理 + +### 5.1 错误码定义 + +错误码应在语言文件中统一定义,便于管理和多语言支持: + +```php +// 语言文件示例 +return [ + 400001 => '用户名已存在', + 400002 => '手机号已被注册', + // 更多错误码... +]; +``` + +### 5.2 错误码分配 + +- 错误码应按模块分配不同的范围 +- 新增错误码时应避免与现有错误码冲突 +- 错误码分配应记录在文档中,便于查阅 + +### 5.3 错误码维护 + +- 定期检查错误码使用情况 +- 清理不再使用的错误码 +- 统一错误码的命名和描述规范 + +## 6. 错误处理最佳实践 + +### 6.1 前端错误处理 + +1. **统一错误提示**:使用统一的错误提示组件 +2. **错误码映射**:根据错误码显示相应的错误信息 +3. **用户友好**:错误信息应简洁明了,便于用户理解 +4. **错误日志**:记录前端错误日志,便于排查问题 + +### 6.2 后端错误处理 + +1. **分层处理**:不同层次使用不同的异常类 +2. **详细日志**:记录详细的错误日志,包括错误码、错误信息、请求参数等 +3. **错误码规范**:严格按照错误码规范使用错误码 +4. **异常捕获**:合理捕获异常,避免系统崩溃 +5. **错误信息国际化**:支持多语言错误信息 + +### 6.3 错误码使用建议 + +1. **语义化**:错误码应具有语义,便于理解 +2. **一致性**:相同类型的错误应使用相同范围的错误码 +3. **可扩展性**:预留足够的错误码空间,便于后续扩展 +4. **文档化**:及时更新错误码文档,确保文档与代码一致 + +## 7. 错误码扩展 + +### 7.1 自定义错误码 + +开发人员可以根据业务需求自定义错误码,遵循以下步骤: + +1. 确定错误码的范围和分类 +2. 在语言文件中定义错误信息 +3. 在代码中使用错误码 +4. 更新错误码文档 + +### 7.2 错误码版本管理 + +当系统版本升级时,错误码的管理应注意: + +1. 保持向后兼容:避免修改现有错误码的含义 +2. 新增错误码:在预留范围内新增错误码 +3. 废弃错误码:标记不再使用的错误码 + +## 8. 常见问题 + +### 8.1 错误码重复 + +**问题**:不同模块使用了相同的错误码 + +**解决方案**: +- 按模块分配错误码范围 +- 建立错误码管理机制 +- 定期检查错误码使用情况 + +### 8.2 错误信息不明确 + +**问题**:错误信息不够明确,难以理解 + +**解决方案**: +- 错误信息应简洁明了 +- 错误信息应包含具体的错误原因 +- 错误信息应便于用户理解 + +### 8.3 错误处理不一致 + +**问题**:不同模块的错误处理方式不一致 + +**解决方案**: +- 统一错误处理机制 +- 使用统一的异常类 +- 遵循错误处理最佳实践 + +## 9. 总结 + +错误码是系统中重要的组成部分,合理的错误码设计和使用可以提高系统的可维护性和用户体验。本文档提供了 CRMEB 系统错误码的设计规范、使用方法和最佳实践,希望能够帮助开发人员更好地理解和使用错误码。 + +在实际开发中,开发人员应严格遵循本文档的规范,确保错误码的一致性和可维护性。同时,应根据业务需求不断完善和扩展错误码体系,以适应系统的发展和变化。 + +> **提示**:该文档由AI生成,仅供参考。 \ No newline at end of file