From 5d97e1acb8cab0081aa65872a6b712735ea1dbe7 Mon Sep 17 00:00:00 2001 From: jw Date: Wed, 16 Sep 2026 17:03:29 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20#7816=20=E9=9C=80=E6=B1=82?= =?UTF-8?q?=E5=AE=A1=E6=A0=B8=E7=8A=B6=E6=80=81=E4=B8=AD=E6=96=87=E5=90=8D?= =?UTF-8?q?=E6=88=BF=E8=BD=A6=E5=90=84=E4=B8=80=E5=A5=97=20+=20#7817=20?= =?UTF-8?q?=E5=87=BA=E8=A1=8C=E4=BA=BA=E5=9B=9B=E6=A1=A3=E7=BB=9F=E4=B8=80?= =?UTF-8?q?=E4=B8=BA=E6=88=90=E4=BA=BA/=E5=84=BF=E7=AB=A5/=E5=B9=BC?= =?UTF-8?q?=E7=AB=A5/=E5=A9=B4=E5=84=BF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5 (1M context) --- ...状态中文名修复房车各一套文案-修改接口-管理后台.md | 231 +++++++++++++++++ ...文名统一为成人儿童幼童婴儿-修改接口-管理后台.md | 244 ++++++++++++++++++ 2 files changed, 475 insertions(+) create mode 100644 changelogs-v2/2026-09/16_7816_团期子订单需求审核状态中文名修复房车各一套文案-修改接口-管理后台.md create mode 100644 changelogs-v2/2026-09/16_7817_出行人四档中文名统一为成人儿童幼童婴儿-修改接口-管理后台.md diff --git a/changelogs-v2/2026-09/16_7816_团期子订单需求审核状态中文名修复房车各一套文案-修改接口-管理后台.md b/changelogs-v2/2026-09/16_7816_团期子订单需求审核状态中文名修复房车各一套文案-修改接口-管理后台.md new file mode 100644 index 00000000..c0aa653a --- /dev/null +++ b/changelogs-v2/2026-09/16_7816_团期子订单需求审核状态中文名修复房车各一套文案-修改接口-管理后台.md @@ -0,0 +1,231 @@ +--- +schema: "hl-changelog/v2" +ticket: "7816" +title: "团期子订单需求审核状态中文名修复房车各一套文案" +consumer: "admin" +author: "wx(GIT)" +change_type: "修改接口" +backend_status: "deployed" +gateway_status: "not_required" +frontend_status: "pending" +frontend_owner: "mmg" +frontend_ref: "" +target_release: "" +verified_at: "2026-09-16" +status_note: "GB-ADM-003 出参 hotelRequirementStatusName / vehicleRequirementStatusName 的取值修正：改前 6 个枚举值中有 5 个翻不出、原样吐英文码（TEST 取样 47 条子订单有 43 条），改后补全 6 值且房车各一套文案。字段名与结构不变，仅取值可观测变化。PR #7823（合并提交 18cfe3e21）已部署 TEST 并逐条取证；字段注释补丁 PR #7826（1e57d7437）为纯文档。" +updated_at: "2026-09-16" +base: "dev-v3" +--- + +# 团期子订单需求审核状态中文名修复房车各一套文案（修改接口） + +> **服务**: hl-order-service-v3 +> **PR**: #7823、#7826（注释补丁） +> **Issue**: #7816 +> **日期**: 2026-09-16 +> **影响范围**: 一个既有 GET 读接口的两个出参字段取值修正；字段名与结构不变、无新端点、无路由变化、无 DDL、无新增错误码 + +--- + +## ⚠️ 关键变化 + +🔴 **改前这两个字段在现网大量取值上原样返回英文码。** 前端「需求审核」列会直接显示 `DONE`、`PENDING_REVIEW`、`PROCESSING`。 + +改后 6 个枚举值全部翻出中文，且**房需求与车需求各一套文案**——车需求不再显示「配房完成」这类房务侧措辞。 + +--- + +## 二、变更接口清单 + +| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | +|---|---|---|---|---|---| +| 1 | 团期下子订单列表 | GET | `/v3/admin/order/group-batch/{groupBatchId}/orders` | 修改接口 | 出参 `hotelRequirementStatusName` / `vehicleRequirementStatusName` 取值修正 | + +--- + +## 三、接口详情 + +### 1. 团期下子订单列表 `GET /v3/admin/order/group-batch/{groupBatchId}/orders` + +**VO**: `GroupBatchOrderItemRespVO` + +#### 使用场景 + +团期列表页展开子订单、团期详情页「整团名单速览」与「子订单」页签。本次修正的两个字段供「需求审核」列展示。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|---|---|---|---|---|---| +| groupBatchId | path | string | 是 | 雪花 ID | 团期 ID | +| page | query | integer | 否 | ≥1，缺省 1 | 页码 | +| pageSize | query | integer | 否 | 缺省 20，>200 截断 | 每页条数 | +| includeNeeds | query | boolean | 否 | 缺省 true | 是否附房数/房型/特殊需求 | +| includeCancelled | query | boolean | 否 | 缺省 false | 是否含已取消子订单 | + +> 入参本次**无任何变化**。 + +#### 出参 + +| 字段 | 类型 | 说明 | +|---|---|---| +| hotelRequirementStatusName | string | **取值修正**。房需求状态中文名；`hotelRequirementStatus` 为 null 时为 null | +| vehicleRequirementStatusName | string | **取值修正**。车需求状态中文名；接单/处理/完成三态措辞与房需求不同 | + +完整取值对照： + +| 状态码 | 房需求 Name | 车需求 Name | +|---|---|---| +| `PENDING` | 待房务配 | 待车队配 | +| `PROCESSING` | 配房中 | 配车中 | +| `DONE` | 配房完成 | 配车完成 | +| `PENDING_REVIEW` | 待审核 | 待审核 | +| `REJECTED_TO_CONSULTANT` | 已驳回定制师 | 已驳回定制师 | +| `REJECTED_TO_ADMIN` | 已驳回管理员 | 已驳回管理员 | + +#### 请求示例 + +```http +GET /v3/admin/order/group-batch/2100132795706691585/orders?pageSize=200 +Authorization: Bearer +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "data": { + "records": [ + { + "orderNo": "HL20260916160051664", + "hotelRequirementStatus": "DONE", + "hotelRequirementStatusName": "配房完成", + "vehicleRequirementStatus": "DONE", + "vehicleRequirementStatusName": "配车完成" + } + ], + "total": 1 + }, + "success": true +} +``` + +#### 空数据 / 降级响应 + +团期无子订单时返回空列表，两个字段不出现在任何行上。 + +```json +{ "code": 200, "message": "成功", "data": { "records": [], "total": 0 }, "success": true } +``` + +#### 错误响应 + +```json +{ "code": 401, "message": "Token 无效", "data": null, "success": false } +``` + +#### 业务边界 + +- 状态码为 null 时 Name 同样为 null，**不兜底成空串**。 +- 枚举外的未知码**回落原 code**，与本接口其它 `*Name` 字段一致；前端直显即可，不要自建映射。 +- 缺需求行时服务端把状态回落为 `PENDING`，故房显「待房务配」、车显「待车队配」。 +- 房、车共用同一套状态码，但**展示文案按资源域分开**，前端不要把两个字段当同一套文案处理。 + +--- + +## 四、契约约束与正确调用方式 + +- 字段名、类型、是否可空**均未变化**，只是取值从「部分英文码」变为「全中文」。 +- 前端若此前为绕开英文码自建了映射表，现在应**删除**，直显后端 `*Name`。 +- 判断逻辑一律用 `*Status` 原码，不要用 `*StatusName`。 + +--- + +## 六、边界行为 + +- `null` → `null`；未知码 → 原样回落（如历史脏值 `SUBMITTED`、`REJECTED`）。 +- 同一条子订单的房、车两个字段相互独立，可一个有值一个为 null。 + +--- + +## 六.6、修改前后对比 + +TEST 同一批数据（20 个团期 / 47 条子订单）改动前后对照： + +| 状态码 | 改前 Name | 改后 Name（房 / 车） | 改前未翻译条数 | 改后重扫条数（房+车） | +|---|---|---|---|---| +| `PENDING` | 未提报 | 待房务配 / 待车队配 | 0 | 18 + 32 | +| `DONE` | **`DONE`**（英文码） | 配房完成 / 配车完成 | 25 | 19 + 6 | +| `PENDING_REVIEW` | **`PENDING_REVIEW`**（英文码） | 待审核 / 待审核 | 14 | 10 + 4 | +| `PROCESSING` | **`PROCESSING`**（英文码） | 配房中 / 配车中 | 4 | 0 + 5 | + +改前 **43 条**原样吐英文，改后 **0 条**。`PROCESSING` 改前 4、改后 5：两次采集之间有子订单推进了状态，不影响结论。`PENDING` 的文案也变了（「未提报」→「待房务配 / 待车队配」），因为改前那个词与枚举语义不对应。 + +--- + +## 六.7、影响评估 + +- **前端**：需求审核列可直接接入；若已有绕开英文码的临时映射应删除。 +- **后端**：纯映射方法改造，无新查询、无新远程调用。 +- **数据**：无表变更、无 Flyway、无写链路。 +- **兼容性**：字段名/类型/可空性零变化；仅 `*Name` 取值变化，属可观测契约变更故以「修改接口」声明。 + +--- + +## 七、不影响范围 + +- `hotelRequirementStatus` / `vehicleRequirementStatus` 两个**原码字段取值完全不变**。 +- 本接口其余字段（`tierName`、`paidAmount`、`orderStatusName` 等）均未改动。 +- 团期列表 GB-ADM-001、详情 GB-ADM-002、统计条 GB-ADM-009 未改动。 +- 小程序端零影响。 + +--- + +## 八、测试环境已验证 + +**部署**：dev-v3 @ `18cfe3e21`（PR #7823 合并提交），2026-09-16 16:34:03~16:35:03 滚动部署双实例成功。注释补丁 #7826 为纯文档，未单独部署。 + +**验证方式**：部署前先采集改动前基线（20 个团期 / 47 条子订单），部署后用同一批 `groupBatchId` + `orderNo` 逐条回核。 + +### 5 条可复现样本前后对照 + +| 域 | 状态码 | groupBatchId | orderNo | 改前 Name | 改后 Name | +|---|---|---|---|---|---| +| 房 | `DONE` | 2100132795706691585 | HL20260916160051664 | `DONE` | 配房完成 ✅ | +| 房 | `PENDING_REVIEW` | 2100128616850317313 | HL20260916154415355 | `PENDING_REVIEW` | 待审核 ✅ | +| 车 | `DONE` | 2100132795706691585 | HL20260916160051664 | `DONE` | 配车完成 ✅ | +| 车 | `PENDING_REVIEW` | 2100126874498703362 | HL20260916153719950 | `PENDING_REVIEW` | 待审核 ✅ | +| 车 | `PROCESSING` | 2100129334617362434 | HL20260916154706861 | `PROCESSING` | 配车中 ✅ | + +**5/5 全部由英文码变为中文。** + +### 全量重扫 + +20 个团期 / **47 条子订单**，`Name == code`（未翻译）的字段数：**0** ✅ + +``` +房需求: DONE→配房完成 x19 | PENDING→待房务配 x18 | PENDING_REVIEW→待审核 x10 +车需求: PENDING→待车队配 x32 | DONE→配车完成 x6 | PROCESSING→配车中 x5 | PENDING_REVIEW→待审核 x4 +``` + +车需求的 `PROCESSING` 显示「配车中」而非「配房中」，验证了房车分措辞的必要性。 + +### 单测与全量 + +- 定向单测 `GroupBatchConverterTest*`：**104 / 0 / 0 / 0**（新增 5 例：房 6 值、车 6 值、房车三态措辞不同、null 与未知码回落、现网高频码回归守卫） +- order-v3 全量 `com.hulalv.order.**`：**Tests run: 7560, Failures: 0, Errors: 0, Skipped: 0，BUILD SUCCESS**，0 次 OOM、0 次容器启动失败 +- #7826 注释补丁：相关三个测试类 181 / 0 / 0 / 0 + +--- + +## 十、相关文档 + +- 差异来源：`需求分析/团期测试.md`「前台问题 团期-整团总览」 +- 枚举定义：`hl-order-service-v3/.../requirement/enums/RequirementStatus.java` + +## 关联 / 联系人 + +- 后端：wx +- 前端：mmg diff --git a/changelogs-v2/2026-09/16_7817_出行人四档中文名统一为成人儿童幼童婴儿-修改接口-管理后台.md b/changelogs-v2/2026-09/16_7817_出行人四档中文名统一为成人儿童幼童婴儿-修改接口-管理后台.md new file mode 100644 index 00000000..a1c3dbd3 --- /dev/null +++ b/changelogs-v2/2026-09/16_7817_出行人四档中文名统一为成人儿童幼童婴儿-修改接口-管理后台.md @@ -0,0 +1,244 @@ +--- +schema: "hl-changelog/v2" +ticket: "7817" +title: "出行人四档中文名统一为成人儿童幼童婴儿" +consumer: "admin" +author: "wx(GIT)" +change_type: "修改接口" +backend_status: "deployed" +gateway_status: "not_required" +frontend_status: "pending" +frontend_owner: "mmg" +frontend_ref: "" +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 执行成功，字典接口与端到端录入均已核对。" +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 +``` + +#### 响应示例 + +```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