245 行
10 KiB
Markdown
245 行
10 KiB
Markdown
---
|
||
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
|