Swagger 业务码精简显示 (#1417 / PR #1418-#1420)

changelogs/2026-04/2026-04-25_swagger-error-code-narrow.md

@@ -0,0 +1,37 @@
+# Swagger 业务码精简显示(#1417 / PR #1418-#1420)
+
+**日期**: 2026-04-25
+**状态**: 已上线测试服(dev `3082c367`)
+**关联**: 后续优化于 [#1412](https://git.1814.love:8443/wx/HL/issues/1412)
+
+---
+
+## 改造前(#1412 完成时)
+每个接口的「响应状态」区显示 **193 行**(4 HTTP + 189 业务码全集)— 太冗余。
+
+## 改造后(#1420 上线)
+每个接口显示 **21 行**:
+- 4 HTTP 标准(200 / 401 / 403 / 404)
+- 13 通用业务码:
+  - common 段(100xxx):SYSTEM_ERROR / INVALID_PARAM / DATA_NOT_FOUND / OPERATION_NOT_ALLOWED / RATE_LIMITED / IDEMPOTENT_REJECTED / FEIGN_EMPTY_DATA / FEIGN_CALL_FAILED
+  - auth 段(110xxx):UNAUTHENTICATED / TOKEN_EXPIRED / TOKEN_INVALID / PERMISSION_DENIED / RESOURCE_NOT_FOUND
+  - system 段(900xxx):RATE_LIMITED / CIRCUIT_BROKEN / SERVICE_DEGRADED / GATEWAY_ERROR
+- 0 ~ N 个 controller 字节码直接引用的业务码(由 ASM 启动时扫描)
+
+## 实现路径(踩坑)
+1. **PR #1418**:按服务模块过滤,但 user-service 自己注册的码就 189,过滤无效
+2. **PR #1419**:ASM 扫 controller 字节码 + fallback module 全集,99% controller 不直接 throw 走 fallback 仍 189
+3. **PR #1420(终版)**:删除 fallback,只显示通用 + ASM 扫到的引用
+
+## 完整业务码全集查询
+- 后端启动日志:`ErrorCodeRegistry scan complete, totalCodes=N`
+- 前端文档:[errorcode-catalog](https://git.1814.love:8443/wx/hl-api-changelog/raw/branch/main/changelogs/2026-04/2026-04-25_error-code-v2-full-migration.md)(段位表)
+- 后端代码:`hl-*-service/src/main/java/com/hulalv/*/errorcode/*.java`
+
+## 前端处理建议
+- HTTP 401 / 403 / 404 走拦截器分支(已有,不变)
+- 通用码 100xxx / 110xxx / 900xxx 提示规则统一(如 100501 RATE_LIMITED 显示"操作过于频繁")
+- 业务码用 `message` 弹 toast,不必为每个 code 写分支
+
+## 不影响
+所有业务接口/响应数据结构/前端调用约定**完全不变**,只是文档展示精简。