docs(changelog): 在线文档恢复显示任务看板等接口分组(文档修复·非契约变更, PR#3597)

hl-user-service Swagger 扫描包过窄(com.hulalv.user.controller)漏扫 task/monitor/file
/callback/notification/wx 等子包,任务看板等整组接口在线文档不显示(接口本身一直可调)。
hl-mp-service 同类问题漏扫 complaint(投诉)。修复后两服务文档分组恢复显示,前端无需改码。

changelogs-v2/2026-06/08_3597_在线接口文档恢复显示任务看板等接口分组-文档修复-管理后台兼小程序.md

@@ -0,0 +1,82 @@
+# 在线接口文档恢复显示任务看板等接口分组 — 文档修复 — 管理后台兼小程序
+
+> 变更类型：📄 文档修复（接口契约零变化，仅在线文档可见性恢复）
+> 端类型：管理后台（hl-user-service）+ 小程序（hl-mp-service）
+> 日期：2026-06-08
+> 服务：hl-user-service、hl-mp-service
+> PR：https://git.1814.love:8443/wx/HL/pulls/3597
+
+---
+
+## ⚠️ 关键说明（务必先看）
+
+1. **这些接口一直都存在，一直可以正常调用** —— 本次 **没有新增、修改或删除任何接口**，没有任何字段 / 路径 / 鉴权变化。
+2. 问题是**在线接口文档（Knife4j / Swagger）的扫描包配置过窄**，导致一批接口分组在文档页面**不显示**。前端如果只看在线文档，会误以为「任务看板等接口没有 / 被删了」。
+3. 本次修复后，这些分组在在线文档中**恢复显示**。前端**无需改任何代码**，刷新文档页面（建议 Ctrl+F5 强刷）即可看到。
+
+---
+
+## 1. 背景与根因
+
+在线接口文档「用户服务」分组下原本看不到「任务看板管理」「任务管理」等接口。
+
+根因：`hl-user-service` 的 Swagger 配置 `Knife4jConfig` 中，文档扫描包 `basePackage` 被限定为 `com.hulalv.user.controller` 这一个子包；而该服务的 Controller 实际散落在 `com.hulalv` 下的多个并列子包中（如任务看板在 `com.hulalv.task.controller`），这些子包全部落在扫描范围之外，于是整组接口在文档里不显示（但 Spring 照常注册、接口照常可调用）。
+
+排查时一并核对了全部 6 个后端服务的 Swagger 配置，发现 `hl-mp-service` 存在同类问题：扫描包 `com.hulalv.mp.controller` 漏掉了 `com.hulalv.mp.complaint.controller`（投诉接口）。其余服务配置正确。
+
+---
+
+## 2. 恢复显示的接口分组清单
+
+### 2.1 hl-user-service（在线文档分组「用户服务」）
+
+修复后该分组 tag 由原先的「仅 user 子包」扩展到全部 86 个，下表为此前**被漏掉、现恢复显示**的代表性分组：
+
+| 接口分组（tag） | 端 | 说明 |
+|---|---|---|
+| [admin] 任务看板管理 | 管理后台 | **本次反馈点**：看板 CRUD / 状态列 / 成员 |
+| [admin] 任务管理 | 管理后台 | 任务 CRUD / 评论 / 提醒 |
+| [admin] MySQL监控 / Redis监控 / RocketMQ监控 / 服务监控 | 管理后台 | 各中间件与服务监控 |
+| [admin] 操作日志 / 登录日志 / 错误日志 / 消息通知日志 / 企微审批日志 | 管理后台 | 各类审计日志查询 |
+| [admin] 微信内容安全-违规命中日志 | 管理后台 | 小程序内容安全命中记录 |
+| [admin] 文件管理 / 通用OSS上传 | 管理后台 | 文件与对象存储 |
+| [C端] 文件上传 | 小程序 | C 端文件上传 |
+| [admin] 管理端站内信 / 站内信实时推送 / 通知中心管理 | 管理后台 | 站内信与通知中心 |
+| [内部] 文件 / 日志接收 / 通知中心 / 登录日志 | 内部 Feign | 服务间内部接口 |
+
+### 2.2 hl-mp-service（在线文档分组「小程序 BFF」）
+
+| 接口分组（tag） | 端 | 说明 |
+|---|---|---|
+| [C端] 投诉 | 小程序 | 投诉提交 / 查询 |
+
+---
+
+## 3. 对前端的影响
+
+| 项目 | 说明 |
+|---|---|
+| 是否需要改代码 | **否**。接口签名、路径、字段、鉴权全部不变 |
+| 需要做什么 | 刷新在线文档页面（Ctrl + F5 强刷），即可在「用户服务」分组看到任务看板等接口；「小程序 BFF」分组看到投诉接口 |
+| 是否影响线上调用 | 否。这些接口此前一直可正常调用，本次仅恢复文档可见性 |
+
+---
+
+## 4. 验证
+
+部署测试服后，直接拉取两个服务的 Swagger JSON 确认（地面真相）：
+
+- `hl-user-service` group「用户服务」：tag 总数 86，已含 `[admin] 任务看板管理`、`[admin] 任务管理` 等。
+- `hl-mp-service` group「小程序 BFF」：tag 总数 51，已含 `[C端] 投诉`。
+- 两服务均双实例 health UP（user 8081/8181，mp 8085/8185）。
+
+---
+
+## 5. 关联 / 联系人
+
+| 项目 | 信息 |
+|---|---|
+| PR | https://git.1814.love:8443/wx/HL/pulls/3597 |
+| Merge Commit | 4976d3c8d |
+| 关联工单 | 无（在线文档展示问题，经排查为后端 Swagger 扫描配置） |
+| 后端负责人 | wx |