docs: /dict/all 外层 dictType 组新增 remark 字段 (HL PR #2827+#2828, Closes HL#2826)

changelogs/2026-05/21_fix_dict_all_group_level_remark.md

@@ -0,0 +1,87 @@
+# GET /dict/all 外层 dictType 组新增 remark 字段 — 透传 sys_dict_type.remark
+
+> **仓库**: HL (hl-user-service + hl-mp-service BFF)
+> **关联 PR/Issue**: PR #2827 (user) + PR #2828 (mp BFF), Closes #2826
+> **日期**: 2026-05-21
+> **影响范围**: 小程序「字典加载」、管理端字典管理页(任何调 `/dict/all` 或 `/admin/dict/all` 拿字典分组的页面)
+> **接收方**: mmg (小程序前端) / 管理端前端
+> **前端**: **无需改动**(只是新增可空字段,前端可选择展示)
+> **测试服 round-trip**: ✅ 通过(157 groups 全部包含 `remark` key)
+
+---
+
+## 一、修了什么
+
+`GET /dict/all` (公开端,网关路由到 hl-mp-service BFF) 与 `GET /admin/dict/all` (管理端,直连 hl-user-service) 原本只返:
+
+```json
+[
+  {
+    "dictType": "product_category",
+    "dictName": "产品分类",
+    "dataList": [ ... ]
+  }
+]
+```
+
+`sys_dict_type.remark` 这一列(字典类型的整体说明,例如「产品分类」字典本身可以填「面向不同人群的产品定位」)没有暴露给前端。
+
+本次修复让外层 group 新增 `remark` 字段,值取自 `sys_dict_type.remark`。
+
+## 二、返回结构对照
+
+### 改前
+
+```json
+{
+  "dictType": "admin_status",
+  "dictName": "管理员状态",
+  "dataList": [...]
+}
+```
+
+### 改后
+
+```json
+{
+  "dictType": "admin_status",
+  "dictName": "管理员状态",
+  "remark": "管理员账号状态字典(ACTIVE/INACTIVE/LOCKED/DELETED)",
+  "dataList": [...]
+}
+```
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `remark` | String / null | 字典类型整体说明,可为 null(DB 该字段允许 NULL) |
+
+数据项内层 `remark` 已有,本次不动。
+
+## 三、测试服实测
+
+```bash
+curl -sk https://api.test.1814.love:9443/dict/all | jq '.data[] | select(.dictType=="product_category") | keys'
+```
+
+返回:
+
+```json
+["dictType", "dictName", "remark", "dataList"]
+```
+
+`product_category` 当前 type-level remark 为 null(DB 未填),但字段已暴露。后续可在管理后台字典管理页给每个 type 填上 remark,前端会自动拿到。
+
+## 四、不需要前端配合
+
+- ✅ 无字段变更,只新增可空字段
+- ✅ 无网关路由变更
+- ✅ 无 Flyway 数据库迁移
+- ✅ 无业务逻辑变更
+
+如果前端有展示需求(例如字典管理页头部展示该字典是干什么的),可读取外层 `remark` 字段;不读也不影响现有逻辑。
+
+## 五、单测覆盖
+
+- `SysDictServiceTest.getAllDictForPublic_includesGroupLevelRemark` — 外层 remark 填充正确
+- `SysDictServiceTest.getAllDictForPublic_groupRemarkNullWhenTypeRemarkNull` — null 时不抛 NPE
+- `MpDictControllerTest.mpDictGroupVO_deserializesRemark` — Jackson 反序列化契约,防 BFF 字段被改回错位