---
schema: "hl-changelog/v2"
ticket: "7817"
title: "出行人四档中文名统一为成人儿童幼童婴儿"
consumer: "admin"
author: "wx(GIT)"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "not_required"
frontend_status: "verified"
frontend_owner: "mmg"
frontend_ref: "63f655ee1e1ab692c293a42d5a3911af36b4b34d"
target_release: ""
verified_at: "2026-09-16"
status_note: "字典 traveler_type 的 YOUNG_CHILD 与 BABY 两行 label 修正（小童→幼童、幼童→婴儿），使录入端与展示端口径一致。GB-ADM-003 的 tierName 取值不变（本就输出幼童/婴儿），变的是字典接口返回与创建页显示文案。PR #7821 已合入 dev-v3（合并提交 8c12f15b5），user-service 已部署 TEST，Flyway 执行成功，字典接口与端到端录入均已核对。前端(2026-09-16 mmg):硬编码对齐 7 处(Step2Info 兜底/Step3Confirm 摘要/v3Adapter TYPE_LABEL/TravelerInfoEditor 反查表增「幼童」键留「小童」兼容/老 OrderEditModal 表单标签/api docstring/invoice passengerText 误标修正),product 定价域不动;定向 87/87+checkpoint 13 项绿,commit 63f655ee。"
updated_at: "2026-09-16"
base: "dev-v3"
---

# 出行人四档中文名统一为成人儿童幼童婴儿（修改接口）

> **服务**: hl-user-service（字典数据）、hl-order-service-v3（注释与文档口径）
> **PR**: #7821
> **Issue**: #7817
> **日期**: 2026-09-16
> **影响范围**: 字典 `traveler_type` 两行 label；无端点变化、无出入参结构变化、无新增错误码

---

## ⚠️ 关键变化

🔴 **改前运营在创建页录入的档位，到团期名单里会显示成另一个档位。**

创建页第四框「幼童数」录入 → 存进 `baby_count` → 名单 `tierName` 显示「婴儿」；
第三框「小童数」录入 → 存进 `young_child_count` → 名单显示「幼童」。**整体错开一档。**

根因是字典 `traveler_type` 与后端渲染用词不一致，**字段绑定本身没错**。

---

## 二、变更接口清单

| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|---|---|---|---|---|
| 1 | 字典全量查询 | GET | `/dict/all` | 修改接口 | `traveler_type` 的 `YOUNG_CHILD` / `BABY` 两行 `dictLabel` 取值修正 |

---

## 三、接口详情

### 1. 字典全量查询 `GET /dict/all`

**VO**: `SysDictData`

#### 使用场景

前端 `dictStore` 启动时拉全量字典（`src/api/dict.js` 的 `getAllDictData()` → `http.get('/dict/all')`；该公共端点**不挂 `/v3` 前缀**，网关上就是 `/dict/all`）。`getDictLabel('traveler_type', value)` 供创建页四个档位输入框的标签及各处出行人类型展示使用。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| — | — | — | — | — | 本接口无入参，返回全量字典 |

#### 出参

| 字段 | 类型 | 说明 |
|---|---|---|
| dictType | string | 字典类型，本次涉及 `traveler_type` |
| dataList | array | 该类型下的字典项 |
| dataList[].dictValue | string | 字典值，**不变**：ADULT / CHILD / YOUNG_CHILD / BABY |
| dataList[].dictLabel | string | **取值修正**：`YOUNG_CHILD` 小童→**幼童**，`BABY` 幼童→**婴儿**；ADULT/CHILD 不变 |

#### 请求示例

```http
GET /dict/all
Authorization: Bearer <admin token>
```

#### 响应示例

```json
{
  "code": 200,
  "message": "成功",
  "data": [
    {
      "dictType": "traveler_type",
      "dictName": "出行人类型",
      "dataList": [
        { "dictValue": "ADULT", "dictLabel": "成人", "sort": 1 },
        { "dictValue": "CHILD", "dictLabel": "儿童", "sort": 2 },
        { "dictValue": "YOUNG_CHILD", "dictLabel": "幼童", "sort": 3 },
        { "dictValue": "BABY", "dictLabel": "婴儿", "sort": 4 }
      ]
    }
  ],
  "success": true
}
```

#### 空数据 / 降级响应

字典服务不可达时前端 `getDictLabel` 回落 `dictValue` 本身（显示英文码），不阻断页面。

```json
{ "code": 200, "message": "成功", "data": [], "success": true }
```

#### 错误响应

```json
{ "code": 401, "message": "Token 无效", "data": null, "success": false }
```

#### 业务边界

- `dictValue` 与 `dict_data_id` **均未变化**，只改 `dictLabel`，历史数据无需回刷。
- 四档以**年龄段**为锚点：成人｜儿童 6-12 岁｜幼童 2-5 岁（占座不占床）｜婴儿 0-1 岁（不占座不占床）。
- 字典有 Redis 缓存（TTL 300 秒）；本次经 Flyway 直接改库，绕过了 Service 层的缓存失效，改后最长 5 分钟内可能读到旧 label。
- 前端 `dictList` 持久化但 `loaded` 不持久化，**刷新页面**即拉到新 label。
- **团期（GROUP）产品不收婴儿**：`GroupOrderStrategy.calculatePrice` 强制 `babyCount=0`，故团期名单的 `tierName` 按设计不会出现「婴儿」。

---

## 四、契约约束与正确调用方式

- 判断逻辑一律用 `dictValue`，**不要用 `dictLabel` 做条件**。
- 前端多处硬编码的档位中文名（`utils/orderEnums.js`、`v3Adapter.js`、`OrderEditModal.vue` 等）应统一收敛到字典，避免再次分叉。
- 展示四档时建议同时给出年龄段提示。

---

## 五、数据库行为

| 项 | 说明 |
|---|---|
| Flyway | `hl-user-service` 新增 `V20260916_003__fix_traveler_type_tier_labels.sql` |
| 变更对象 | `sys_dict_data` 两行 `dict_label`（id 9000000000000013 / 9000000000000014），顺带补三档 `remark` 的年龄段 |
| 幂等 | PROCEDURE 内按 `dict_data_id` + `dict_value` 双锚定 UPDATE，重复执行结果一致 |
| 前置校验 | 两个 `dict_data_id` 须仍绑定预期的 `dict_type` + `dict_value`，否则 `SIGNAL SQLSTATE '45000'` 中止 |
| 回滚 | 反向 UPDATE 两行 label；无结构变更 |

---

## 六、边界行为

- 字典查不到对应 `dictValue` 时，前端 `getDictLabel` 返回 `dictValue` 原值，不抛错。
- `tierName`（GB-ADM-003）不读字典，走后端 `resolveTier` 的固定映射；两侧用词现已对齐，**改任一侧都必须同步改另一侧**。

---

## 六.6、修改前后对比

| dictValue | 改前 dictLabel | 改后 dictLabel | 年龄段 |
|---|---|---|---|
| `ADULT` | 成人 | 成人（不变） | — |
| `CHILD` | 儿童 | 儿童（不变） | 6-12 岁 |
| `YOUNG_CHILD` | **小童** | **幼童** | 2-5 岁，占座不占床 |
| `BABY` | **幼童** | **婴儿** | 0-1 岁，不占座不占床 |

**两行必须同改**：只改 `BABY` 会在「小童」与「婴儿」之间空出「幼童」，错位只是换个位置；只改 `YOUNG_CHILD` 则两档同叫「幼童」直接撞名。

GB-ADM-003 的 `tierName` **取值不变**，本次是让字典向它对齐。

---

## 六.7、影响评估

- **前端**：创建页第三、四框标签由「小童数 / 幼童数」变为「幼童数 / 婴儿数」，运营需适应。
- **后端**：`resolveTier` 用词未变，仅改写 javadoc 记录定案；`OrderCreateReqVO` 三档注释补年龄段。
- **数据**：`sys_dict_data` 两行 `dict_label` UPDATE，其余列不动；无表结构变更。
- **兼容性**：无字段增删改名，无枚举值变化；仅 label 取值变化，属可观测契约变更故以「修改接口」声明。

---

## 七、不影响范围

- `dictValue`、`dict_data_id`、`sort_order`、`status` 均未变化。
- `order_main` 四列的数据与列注释均未改动（列注释本就是「幼童数 / 婴儿数」）。
- GB-ADM-003 的 `tierCode` / `tierName` 取值不变。
- 创建订单接口的入参字段名与校验规则不变。
- 小程序端零影响。

---

## 八、测试环境已验证

**部署**：dev-v3 @ `18cfe3e21`，`hl-user-service` 于 2026-09-16 16:35:09~16:35:55 滚动部署双实例成功（字典 migration 在 user-service，只部署 order-v3 不会执行）。

### Flyway 执行确认

```
version        description                     success  installed_on
20260916.003   fix traveler type tier labels   1        2026-09-16 16:35:32
```

### 字典接口实测 `GET /dict/all`

`traveler_type.dataList` 返回：

| dictValue | dictLabel | 判定 |
|---|---|---|
| ADULT | 成人 | ✅ |
| CHILD | 儿童 | ✅ |
| YOUNG_CHILD | **幼童** | ✅ |
| BABY | **婴儿** | ✅ |

库侧 `sys_dict_data` 四行与接口返回一致，`remark` 已补年龄段。

### 端到端：真实下单 → 落库 → 团期名单

造数（自签 admin token 走网关，未用线下占位字段）：班期 `2100147435660591107`「#7817-四档端到端」，订单 `HL20260916165902231`，入参四档各填 1。

| 录入框标签（来自 `/dict/all`） | 落库列 | 值 | 团期名单 `tierName` 含 | 判定 |
|---|---|---|---|---|
| 成人数 | `adult_count` | 1 | 1成人 | ✅ |
| 儿童数 | `child_count` | 1 | 1儿童 | ✅ |
| 幼童数 | `young_child_count` | 1 | 1幼童 | ✅ |
| 婴儿数 | `baby_count` | **0** | —（零值不渲染） | 见下 |

团期 `2100147436776300545` 返回：`tierCode=1A1C1Y`、`tierName=1成人1儿童1幼童`、`participantCount=3`。**录入框标签与名单用词逐字一致。**

> ⚠️ 婴儿档：入参传了 `babyCount=1`，落库为 0。原因是**团期产品按设计不收婴儿**——`GroupOrderStrategy.calculatePrice` 强制 `setBabyCount(0)`，报价也写死传 0。所以团期名单上「婴儿」这一档无法端到端出现；该档用词由上面的字典接口实测 + 单测 `listSubOrders_tier_babyOnlyRendersYingEr` 覆盖。

此外全库另一条含幼童的存量订单 `HL20260906094528368`（a=1 c=1 y=1）渲染为 `1成人1儿童1幼童`，同样一致。

### 单测与全量

- 定向单测 `GroupBatchQueryServiceTest*`：**69 / 0 / 0 / 0**（新增 3 例：四档全非零 `1A1C1Y1B`、仅幼童、仅婴儿，后两例带「不串档」双向守卫）
- order-v3 全量 `com.hulalv.order.**`：**Tests run: 7558, Failures: 0, Errors: 0, Skipped: 0，BUILD SUCCESS**，0 次 OOM、0 次容器启动失败

---

## 十、相关文档

- 差异来源：`需求分析/团期测试.md`「档位（几个大人 几个小孩 几个儿童，几个幼童）」
- 生成处：`hl-order-service-v3/.../groupbatch/service/GroupBatchQueryService.java` `resolveTier`

## 关联 / 联系人

- 后端：wx
- 前端：mmg