From 3ed955bd71fd90f2987b29b7b2ff01152d49ac48 Mon Sep 17 00:00:00 2001
From: API Changelog Bot <changelog@hulalv.com>
Date: Sat, 25 Apr 2026 01:40:28 +0800
Subject: [PATCH] =?UTF-8?q?=E9=94=99=E8=AF=AF=E7=A0=81=E4=BD=93=E7=B3=BB?=
 =?UTF-8?q?=20v2=20=E5=85=A8=E9=87=8F=E4=B8=8A=E7=BA=BF=20(#1391)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...2026-04-25_error-code-v2-full-migration.md | 110 ++++++++++++++++++
 1 file changed, 110 insertions(+)
 create mode 100644 changelogs/2026-04/2026-04-25_error-code-v2-full-migration.md

diff --git a/changelogs/2026-04/2026-04-25_error-code-v2-full-migration.md b/changelogs/2026-04/2026-04-25_error-code-v2-full-migration.md
new file mode 100644
index 0000000..f6624ea
--- /dev/null
+++ b/changelogs/2026-04/2026-04-25_error-code-v2-full-migration.md
@@ -0,0 +1,110 @@
+# 错误码体系 v2 全量上线(#1391)
+
+**日期**: 2026-04-25
+**影响范围**: 全部服务 `Result.code` 字段
+**关联 PR**: #1392 / #1393 / #1394 / #1395 / #1396 / #1397 / #1398
+**工单**: [#1391](https://git.1814.love:8443/wx/HL/issues/1391)
+
+---
+
+## 🚨 前端接入提示
+
+### ✅ 好消息:401/403/404 保留,现有拦截器零改动
+- HTTP 认证相关错误码(401 未授权 / 403 无权限 / 404 未找到)**完全保留**
+- 前端 axios 拦截器 / 跳登录页逻辑 **无需任何改动**
+- 400 参数校验 / 500 系统错误 **保留原语义**
+
+### 🆕 业务错误码升级为 **6 位数字**,前端可选接入
+- 所有业务模块的 `Result.code` 字段不再是 400/500 通用码,变为 **6 位数字业务码**
+- 如 `400101 = 产品不存在`、`500311 = 订单当前状态不允许取消`、`510411 = 合同签约失败` 等
+- **message 字段保留原业务提示中文**,所有已有 `uni.showToast(res.data.message)` 代码继续生效
+
+---
+
+## 📋 6 位码段位表
+
+| 段位前缀 | 模块 | 示例 |
+|---------|------|------|
+| `100xxx` | common 通用 | `100501` 流控拦截 / `100502` 幂等拦截 / `100901` Feign 空数据 |
+| `110xxx` | auth 认证授权 | `110001` 未认证(预留) |
+| `200xxx-299xxx` | user 用户 | `230301` 短信频率限制 / `230302` 短信日发送上限 / `260204` 状态列无权管理 |
+| `300xxx-399xxx` | resource 资源 | `300106` 景点无权操作 / `310xxx` 酒店 / `340xxx` 用车 / `380001` 备品审批进行中不可删 |
+| `400xxx-499xxx` | product 产品 | `400101` 产品不存在 / `410xxx` 价格 / `430xxx` 行程 / `460xxx` 高德地图 |
+| `500xxx-509xxx` | order 订单核心 | `500xxx` 订单 CRUD / `500311` 状态不允许取消 |
+| `510xxx-549xxx` | order 扩展 | `510xxx` 合同 / `520xxx` 支付 / `530xxx` 退款 / `540xxx` 保险 / `549xxx` 投诉 |
+| `550xxx-599xxx` | order 子域 | `550xxx` 行程 / `560xxx` 团报 / `580xxx` 到达/工单 / `590xxx` 加价折扣 / `593xxx` 发票 |
+| `600xxx-699xxx` | mp 小程序 BFF | `610xxx` 天气 |
+| `900xxx-999xxx` | system 系统级 | `900001` 限流 / `900002` 熔断 |
+
+---
+
+## 🎯 前端可选接入(3 种粒度)
+
+**大多数场景**:继续用 `message` 弹 toast,无需关心 code。
+
+**需要差异化处理的场景**,可按以下 3 种粒度分支:
+
+### Level 1 粒度:HTTP 类(优先)
+```js
+if (res.data.code === 401) // 跳登录
+if (res.data.code === 403) // 无权限提示
+if (res.data.code === 404) // 404 页
+// 已有代码完全兼容,继续用即可
+```
+
+### Level 2 粒度:按段位分支(业务大类)
+```js
+const code = res.data.code;
+if (code >= 400000 && code <= 499999) {
+  // 产品相关错误,可选跳商品首页
+} else if (code >= 500000 && code <= 599999) {
+  // 订单相关错误
+}
+```
+
+### Level 3 粒度:按具体 code 分支(细粒度 UX)
+```js
+if (res.data.code === 400301) {
+  // 产品下架,跳首页
+  uni.reLaunch({ url: '/pages/index/index' });
+} else if (res.data.code === 510411) {
+  // 合同签约失败,重试按钮
+}
+```
+
+**接入优先级建议**:Level 1 必做(已有)→ Level 3 按 UX 需求逐个接入(非强制)。
+
+---
+
+## 🔧 技术变更细节
+
+### 1. Feign 链路透传修复
+**修复前**:下游服务抛 `BusinessException(400301, "产品下架")`,Feign 调用方 `getCheckedData()` 会吞码降级为 500。
+**修复后**:上游 code 完整透传,前端能看到真实业务码。
+
+### 2. 所有 admin/mp 接口的 Result.code 升级
+- 之前:`{code: 400, message: "产品不存在"}` / `{code: 500, message: "订单状态不允许取消"}`
+- 现在:`{code: 400101, message: "产品不存在,ID=xxx"}` / `{code: 500311, message: "当前状态不允许取消,状态=PAID"}`
+
+### 3. message 字段保留关键子串
+迁移采用 MessageFormat 占位符,所有原 message 关键中文子串保留(如"产品不存在"/"审批进行中"等),前端若用 `message.includes(xxx)` 判断仍可工作。
+
+---
+
+## 🧪 新 code 速查接口
+
+各服务启动时自动注册所有错误码到中央 `ErrorCodeRegistry`,如需完整码表可通过以下方式查询:
+
+1. **后端日志**:每个服务启动日志含 `ErrorCodeRegistry scan complete, totalCodes=X, segments=Y`
+2. **容量告警**:任何段位使用率 ≥ 80% 自动 WARN 日志
+3. **未来扩展**:计划提供 `/internal/errorcode/catalog` 接口导出 yaml 码表
+
+---
+
+## ⚠️ 3 日反馈窗口
+
+如前端需要按具体 code 做差异化处理(Level 3),请在 **2026-04-28 前** 反馈:
+- 哪个业务 code 需要特殊 UI 行为(跳页/重试/不展示等)
+- 是否需要前端配置化 code-action 映射
+
+超过 3 日无反馈视为按 Level 1 + message 继续使用,不阻塞迭代。