签入版本

EasyGoAdmin_Gin_AntdVue/zh/api-spec/error-code.md

@@ -1,78 +1,70 @@
 # 8.2 错误码对照表
 
 :::tip 概述
-所有接口返回统一的 JSON 结构，通过 `code` 字段区分业务状态。前端应根据 `code` 做差异化处理。
+业务错误码定义在 `utility/apperr`，经 `internal/consts` 别名转出（internal 层只依赖 consts 一个入口）。对外信封除 401 外统一显示为 1，本表用于理解 msg 背后的原因分类。
 :::
 
-## 业务错误码
+## 通用码
 
-| code | ok | 含义 | 使用场景 | 前端处理 |
-|------|-----|------|----------|----------|
-| `0` | true | 成功 | 所有成功操作 | 正常处理 data |
-| `1` | false | 一般失败 | 业务逻辑失败 | 显示 msg 提示 |
-| `401` | false | 未授权 | Token 缺失/无效/过期 | 跳转登录页 |
-| `403` | false | 禁止访问 | 权限不足/租户异常/演示环境 | 显示无权限提示 |
-| `404` | false | 数据不存在 | 查询单条记录为空 | 显示数据不存在 |
-| `422` | false | 参数验证失败 | 表单验证不通过 | 显示具体字段错误 |
+| 码 | 常量 | 消息 |
+|---|---|---|
+| 1 | CodeFailed | 操作失败 |
+| 400 | CodeParamError | 参数校验失败 |
+| 401 | CodeUnauthorized | 登录已过期，请重新登录 |
+| 403 | CodeForbidden | 没有该操作权限 |
+| 429 | CodeTooManyRequests | 请求过于频繁，请稍后再试 |
+| 500 | CodeServerError | 服务器内部错误 |
+| 1009 | CodeRecordExists | 记录已存在 |
+| 1010 | CodeRecordNotFound | 记录不存在 |
 
-## 响应示例
+## 认证与账户
 
-> 响应示例详见 [统一响应格式](/zh/api-spec/response.html)
+| 码 | 常量 | 消息 |
+|---|---|---|
+| 1001 | CodeUserNotFound | 用户不存在 |
+| 1002 | CodeUserDisabled | 账号已被禁用 |
+| 1003 | CodePasswordWrong | 密码错误 |
+| 1004 | CodeCaptchaError | 验证码错误或已过期 |
+| 1008 | CodeTokenInvalid | Token无效或已失效 |
+| 1012 | CodeOldPwdWrong | 原密码错误 |
 
-## 常见错误消息
+## 租户
 
-### 认证相关
+| 码 | 常量 | 消息 |
+|---|---|---|
+| 1005 | CodeTenantExpired | 租户已过期 |
+| 1006 | CodeTenantDisabled | 租户已禁用 |
+| 1007 | CodeTenantUserLimit | 租户用户数已达上限 |
+| 1013 | CodeTenantNotFound | 租户不存在 |
 
-| 消息 | 原因 | 解决方案 |
-|------|------|----------|
-| `未提供认证令牌` | 请求头缺少 Authorization | 携带 Token |
-| `无效的认证令牌` | Token 类型不是 access | 使用 access_token |
-| `token已过期` | Token 超过有效期 | 调用刷新接口或重新登录 |
-| `用户名或密码错误` | 账号或密码不正确 | 检查输入 |
-| `账号已被禁用` | 用户 status != 1 | 联系管理员 |
+## 业务约束（删除守卫等）
 
-### 权限相关
+| 码 | 常量 | 消息 | 场景 |
+|---|---|---|---|
+| 1011 | CodeHasChildren | 存在下级或关联记录，不能删除 | 树形删除守卫 |
+| 1014 | CodeInUse | 记录已被引用，不能删除 | 引用删除守卫 |
+| 1015 | CodeDemoMode | 演示环境，禁止操作! | demo 中间件命中 |
 
-| 消息 | 原因 | 解决方案 |
-|------|------|----------|
-| `无访问权限：xxx` | 用户无该接口权限 | 联系管理员分配权限 |
-| `租户已被禁用` | 租户 status != 1 | 联系平台管理员 |
-| `租户已过期` | 租户 expire_time 已过 | 续费或联系平台 |
-| `演示环境，禁止操作` | 演示模式下写操作被拦截 | 非演示环境操作 |
+## 角色常量（非错误码）
 
-### 业务相关
+| 常量 | 值 | 说明 |
+|---|---|---|
+| RoleCodeSuperAdmin | ROLE_SUPER_ADMIN | 超管角色编码（保留） |
+| PermWildcard | 通配权限码 | 超管通配（保留） |
 
-| 消息 | 原因 | 解决方案 |
-|------|------|----------|
-| `xxx已存在` | 唯一性校验失败 | 修改重复字段值 |
-| `数据不存在` | 记录已被删除或不存在 | 刷新列表 |
-| `请选择要删除的数据` | 批量删除时 ids 为空 | 先选择数据 |
-| `该部门下存在子部门，不可删除` | 删除前钩子校验 | 先删除子部门 |
+保留编码仅平台初始化数据可用，租户自建角色禁止采用（防同名提权；超管判定另有 IsPlatform 门控双重防线）。
 
-## 前端错误处理
+## 新增错误码规约
 
-```typescript
-// Axios 响应拦截器
-axios.interceptors.response.use(response => {
-    const { code, msg, data } = response.data;
+1. 定义在 `utility/apperr`（码值 + 中文默认消息）
+2. 在 `internal/consts/biz_err.go` 别名转出
+3. 编号段规划：1xxx 认证租户业务类 / 10xx 守卫类
+4. 业务侧经 `consts.CodeXxx` 哨兵或 `apperr.Newf(consts.CodeXxx.Code(), "fmt", a...)` 上抛
 
-    if (code === 0) {
-        return data;  // 成功
-    }
+## 对外语义提醒
 
-    if (code === 401) {
-        // Token 过期，跳转登录
-        router.push('/login');
-        return;
-    }
+前端能稳定分支的只有 0 / 1 / 401 三值；细分码用于**服务端日志、排障与文档**。前端如需细分处理，以 msg 关键字或后续扩展专用字段为准，不建议直接依赖内部码。
 
-    if (code === 403) {
-        ElMessage.error(msg || '无权限');
-        return;
-    }
+## 下一步
 
-    // 其他错误
-    ElMessage.error(msg || '操作失败');
-    return Promise.reject(new Error(msg));
-});
-```
+→ [8.3 分页查询规范](/zh/api-spec/pagination.html)