---
description: 全局错误码分段管理规范，微服务多模块隔离
globs: ["**/ErrorCodeConstants.java"]
alwaysApply: false
---
# 冲突优先级声明
Java编码规范优先级高于本文件。

# 全局错误码常量规范
## 一、错误码分段规则（无BPM分段）
采用三段式数字编码：`模块段_子模块_序号`
1. system系统模块：1_001_001 ~ 1_001_999
    用户、部门、角色、菜单、字典、登录权限相关错误；
2. business业务模块：1_100_001 ~ 1_999_999
    所有自定义业务模块错误码，每个业务子模块分配100个序号区间；
3. 通用框架错误：1_000_001 ~ 1_000_999
    参数校验、幂等、文件上传、导出、远程调用通用异常。

## 二、常量定义规范
1. 统一存放于 `ErrorCodeConstants.java` 常量类；
2. 常量命名：全大写，下划线分隔，业务含义清晰；
3. 常量值严格遵循分段编码，注释写明异常提示文案；
4. 示例：
    // 商品模块-商品不存在
    public static final Integer GOODS_NOT_EXIST = 1_100_001;
5. 同一业务模块错误码按业务流程顺序递增，预留间隔序号便于后续扩展；
6. 禁止重复错误码，新增错误码前检查已存在常量。

## 三、异常文案规范
1. 错误提示面向业务操作人员，使用通俗中文；
2. 禁止文案包含数据库字段名、技术术语、英文编码；
3. 参数校验类文案清晰指明错误字段，例："商品名称不能为空"；
4. 远程调用、服务异常文案屏蔽底层技术细节，统一友好提示。

## 四、使用规范
1. 业务抛出异常统一使用工具类：
    ServiceExceptionUtil.exception(ErrorCodeConstants.GOODS_NOT_EXIST);
2. 禁止直接在代码中写数字错误码，全部引用常量；
3. 捕获Feign远程调用异常时，透传远端错误码与提示文案；
4. 前端接收错误码，可根据特定错误码做页面特殊处理（如跳转登录、弹窗提示）。

## 五、禁止事项
❌ 禁止使用重复错误码；
❌ 禁止硬编码数字错误码，必须引用常量；
❌ 禁止文案暴露底层技术、数据库、服务名称；
❌ 禁止跨模块混用错误码分段，严格按区间分配；
❌ 禁止新增BPM流程相关错误码分段。
