diff --git 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 new file mode 100644 index 0000000..04d2e64 --- /dev/null +++ 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