# 在线接口文档恢复显示任务看板等接口分组 — 文档修复 — 管理后台兼小程序 > 变更类型：📄 文档修复（接口契约零变化，仅在线文档可见性恢复） > 端类型：管理后台（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 |