feat(faq): 增加 typeCode 字段(字典 mp_faq_type) — 通知 mmg 前端补类型下拉 (PR #1898)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-08 18:43:30 +08:00 · 2026-05-08 18:43:30 +08:00 · ea6e629d52
--- a/changelogs/2026-05/08_feat_faq_add_type_field_with_dict.md
+++ b/changelogs/2026-05/08_feat_faq_add_type_field_with_dict.md
@ -0,0 +1,129 @@
+---
+date: 2026-05-08
+type: backend-feature
+module: hl-user-service/faq
+priority: medium
+notify: ["@mmg"]
+status: tested-passed
+restart_service: hl-user-service
+gitea_pr: 1898
+gitea_issue: [1896]
+---
+
+# FAQ 增加「类型」字段(字典 mp_faq_type) — 管理后台需补类型下拉
+
+## 背景
+
+`sys_faq_item` 表新增 `type_code` 字段,用字典 `mp_faq_type` 管理类型枚举。新增 9 个类型对应「呼籁小程序FAQ_标准对客版_v2.0」9 大类目(产品怎么选/预订与支付/儿童与家庭/行程与交通/住宿与餐饮/体验与安全/行前准备/退改与售后/投诉与权益保障)。
+
+后续会按 docx 内容清空+重建正式环境 FAQ 数据,届时每条问题都会带 `typeCode`。
+
+## API 字段变化
+
+### 管理端 (admin)
+
+**1. 列表/详情/创建/更新响应** `FaqItemRespVO` 新增字段:
+
+```json
+{
+  "id": "...",
+  "categoryId": "...",
+  "categoryName": "...",
+  "question": "...",
+  "answer": "...",
+  "sortOrder": 1,
+  "status": "ACTIVE",
+  "statusLabel": "启用",
+  "typeCode": "PRODUCT_SELECT",       // 新增,可能为 null
+  "typeLabel": "产品怎么选",            // 新增,后端从字典回填,可能为 null
+  "createTime": "...",
+  "updateTime": "..."
+}
+```
+
+**2. 创建/更新请求** `FaqItemSaveReqVO` 新增字段(可选,允许 null):
+
+```json
+POST /admin/faq/items
+PUT  /admin/faq/items/{id}
+{
+  "categoryId": 1,
+  "question": "...",
+  "answer": "...",
+  "sortOrder": 1,
+  "typeCode": "PRODUCT_SELECT"   // 新增,字典 mp_faq_type 的 dict_value
+}
+```
+
+**3. 列表查询** `GET /admin/faq/items` 新增筛选参数:
+
+```
+GET /admin/faq/items?page=1&pageSize=20&typeCode=PRODUCT_SELECT
+```
+
+支持按 `typeCode` 等值筛选(可选,不传不过滤)。
+
+### 小程序端 (mp)
+
+`MpFaqItemRespVO` 同步增加 `typeCode` + `typeLabel` 字段。小程序端如有需要可基于 typeCode 做分类展示/分组。
+
+## 前端工作清单(mmg 关注)
+
+### 1. 字典数据源
+
+字典已通过 Flyway 自动初始化,前端调字典查询接口取数:
+
+```
+GET /admin/dict/data/by-type/mp_faq_type
+```
+
+(具体接口路径请前端按现有字典调用方式自查;本 PR 字典 9 项 sort_order 1-9 已就位)
+
+字典 9 项:
+| dict_value | dict_label |
+|---|---|
+| PRODUCT_SELECT | 产品怎么选 |
+| BOOKING_PAY | 预订与支付 |
+| KIDS_FAMILY | 儿童与家庭 |
+| ITINERARY_TRANSPORT | 行程与交通 |
+| STAY_DINING | 住宿与餐饮 |
+| EXPERIENCE_SAFETY | 体验与安全 |
+| PRE_TRIP_PREP | 行前准备 |
+| REFUND_AFTERSALE | 退改与售后 |
+| COMPLAINT_RIGHTS | 投诉与权益保障 |
+
+### 2. 「编辑/新增问题」对话框
+
+在现有「问题/回答/排序号/状态」基础上,**增加「类型」下拉框**:
+
+- label:`类型`
+- 必填性:**不强制必填**(后端允许 null,但建议默认必填以保证数据完整,具体由前端按 UX 决定)
+- 数据源:上述字典接口
+- 提交时附带 `typeCode` 字段
+
+### 3. 问题列表页
+
+建议在列表展示一列「类型」(取 `typeLabel`),老数据 typeLabel 为 null 时显示「-」。
+
+### 4. (可选) 列表筛选
+
+列表上方增加「类型」筛选下拉,选中后调用 `GET /admin/faq/items?typeCode=XXX`。
+
+## 兼容性
+
+- **完全向后兼容**:老数据 `typeCode` 默认 NULL,API 仍正常返回(typeLabel 也为 null),前端如不立即接入也不影响现有功能
+- 现有「问题分类(FaqCategory)」侧栏不受影响,继续作为分类组织 UI 保留
+
+## 部署后注意
+
+后端部署完后需手动清字典 Redis 缓存(Flyway 直接 INSERT 字典不会触发应用层缓存失效):
+
+```bash
+redis-cli -n 0 DEL cache:dict:data:list cache:dict:data:by-type "cache:dict:data:mp_faq_type"
+```
+
+## 关联
+
+- Gitea PR: #1898
+- Gitea Issue: #1896 (已关闭)
+- merge commit: 4d14816c44