Knife4j 接口文档按微服务多分组 (#1404 / PR #1405-#1411)

changelogs/2026-04/2026-04-25_knife4j-multi-group-refactor.md

@@ -0,0 +1,75 @@
+# Knife4j 接口文档按微服务多分组(#1404)
+
+**日期**: 2026-04-25
+**关联 PR**: #1405(Phase A) / #1406-#1410(Phase B 5 服务) / #1411(hotfix)
+**工单**: [#1404](https://git.1814.love:8443/wx/HL/issues/1404)
+
+---
+
+## 🚨 前端 / 测试同事必看
+
+### 接口文档地址不变
+- 测试环境:https://api.test.1814.love:9443/doc.html(网关)
+- 内网直连:http://192.168.100.236:8080/doc.html
+
+### 左上角下拉菜单变化
+
+**改造前**:35 个细粒度下拉项,如:
+- `用户服务 - 管理员管理`
+- `用户服务 - 角色管理`
+- `用户服务 - 字典管理`
+- `资源服务 - 酒店管理`
+- `资源服务 - 服务项管理`
+- ... (35 项,菜单冗长)
+
+**改造后**:**5 个微服务级下拉**:
+- 用户服务
+- 资源服务
+- 产品服务
+- 订单服务
+- 小程序 BFF
+
+### 进入 group 后的 tag 列表
+
+每个 tag 用 **4 类前缀**区分端类型,无需服务名前缀:
+- `[admin] 模块名` - 管理端接口
+- `[C端] 模块名` - 小程序端接口
+- `[内部] 模块名` - internal/Feign 接口
+- `[回调] 模块名` - 第三方平台事件回调(企微/公众号)
+
+### 实例
+
+**用户服务 group**(共 48 tag):
+- `[C端] 公开字典` / `[C端] 出行人` / `[C端] 出行人OCR识别` / ...
+- `[admin] Banner管理` / `[admin] 角色管理` / `[admin] 字典管理` / ...
+- `[内部] 心愿` / `[内部] 联系我们` / `[内部] 部门用户` / ...
+- `[回调] 公众号回调`
+
+**订单服务 group**(共 51 tag):
+- `[admin] 订单管理` / `[admin] 合同管理` / `[admin] 退款管理` / `[admin] 保险方案管理` / ...
+- `[内部] 订单同步` / `[内部] 支付` / `[内部] 合同 Feign` / ...
+
+## 改造规模(供 reviewer 参考)
+- 7 PR(#1405-#1411)
+- 274 Controller 文件 @Api(tags) 全量改名
+- 5 个 Knife4jConfig.java 多 Docket 合并为单 Docket
+- gateway/application.yml `knife4j.gateway.routes` 35 项 → 5 项
+
+## 路由结构
+
+| 服务 | 网关下拉名 | swagger group | 注册名 |
+|------|-----------|--------------|--------|
+| hl-user-service | 用户服务 | 用户服务 | hl-user-service |
+| hl-resource-service | 资源服务 | 资源服务 | hl-resource-service |
+| hl-product-service-v2 | 产品服务 | 产品服务 | hl-product-service-v2 |
+| hl-order-service-v2 | 订单服务 | 订单服务 | **hl-order-service**(注:代码模块带 -v2 但 Nacos 注册名不带) |
+| hl-mp-service | 小程序 BFF | 小程序 BFF | hl-mp-service |
+
+## 实施踩坑
+
+PR #1405 把订单服务 service-name 误写为 `hl-order-service-v2`(实际 Nacos 注册名是 `hl-order-service`,代码模块名带 -v2 是 maven module 名,但 spring.application.name 没带 -v2),导致 doc.html 订单 group 404。已在 #1411 hotfix 修正。
+
+经验沉淀:Knife4j gateway routes / Feign client name 统一参考 Nacos 注册名(`spring.application.name`)而非 maven module 名,二者**可能不一致**。
+
+## 不影响业务接口
+本次仅改文档/分组,业务路径 / 鉴权 / 错误码 / Feign 调用全部不变。