---
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
