From cee040f8143b3e13a5bb2c84a09357f68079151a Mon Sep 17 00:00:00 2001 From: yaosutu <770858045@qq.com> Date: Thu, 18 Jun 2026 10:05:48 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=B0=E5=A2=9E=20changelog=EF=BC=9A?= =?UTF-8?q?=E5=88=B0=E8=BE=BE=E8=AE=A1=E5=88=92=E5=87=BA=E8=A1=8C=E4=BA=BA?= =?UTF-8?q?=E7=B1=BB=E5=9E=8B=E4=B8=AD=E6=96=87=E5=90=8D=E6=96=B0=E5=A2=9E?= =?UTF-8?q?=E5=AD=97=E6=AE=B5=EF=BC=88=E5=B0=8F=E7=A8=8B=E5=BA=8F=E7=AB=AF?= =?UTF-8?q?=EF=BC=8CPR=20#3954=EF=BC=8CIssue=20#3951=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...达计划出行人类型中文-修改接口-小程序端.md | 227 ++++++++++++++++++ 1 file changed, 227 insertions(+) create mode 100644 changelogs-v2-mp/2026-06/18_3951_到达计划出行人类型中文-修改接口-小程序端.md diff --git a/changelogs-v2-mp/2026-06/18_3951_到达计划出行人类型中文-修改接口-小程序端.md b/changelogs-v2-mp/2026-06/18_3951_到达计划出行人类型中文-修改接口-小程序端.md new file mode 100644 index 0000000..da1584f --- /dev/null +++ b/changelogs-v2-mp/2026-06/18_3951_到达计划出行人类型中文-修改接口-小程序端.md @@ -0,0 +1,227 @@ +# 【修改接口·小程序端】✨ 到达计划出行人类型中文名 travelerTypeName 新增字段 (#3951) + +> **PR**: #3954 | **服务**: hl-order-service-v3 / hl-mp-service | **更新时间**: 2026-06-18 + +## 1. 接口背景 + +小程序到达计划接口返回的出行人对象（ArrivalPlanTravelerSimpleVO）原先只包含 `travelerType` 英文枚举值，前端展示出行人类型标签时需自行维护一套映射表。本次新增 `travelerTypeName` 字段，由后端查数据字典 `traveler_type` 派生中文名直接下发，小程序侧可零配置展示类型标签。原 `travelerType` 字段保留不变，属纯新增、非破坏性变更。 + +## 2. 变更清单 + +| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | +|---|------|------|------|----------|------| +| 1 | 获取到达计划（一期路径） | GET | /mp/order/{orderId}/arrival | 新增出参字段 | 出行人对象新增 `travelerTypeName` | +| 2 | 获取到达计划（v3 路径） | GET | /mp/v3/order/arrival/{orderId} | 新增出参字段 | 出行人对象新增 `travelerTypeName` | + +> 以上两个路径均经网关路由至 hl-mp-service，数据源为 order-v3 侧透传。 + +## 3. 接口详情 + +### 3.1 获取到达计划（一期路径） + +- **使用场景**：小程序出行人填写或出行信息确认页，加载出行人到达计划详情。 +- **认证**：需要微信登录态 JWT（C 端 token）。 +- **幂等性**：是（只读）。 +- **限流**：无。 + +入参无变化。出参中 `travelers[]` 数组每个 `ArrivalPlanTravelerSimpleVO` 元素新增 `travelerTypeName` 字段（String）。 + +### 3.2 获取到达计划（v3 路径） + +- **使用场景**：同上，v3 版本接口路径，功能与 3.1 等价。 +- **认证**：需要微信登录态 JWT（C 端 token）。 +- **幂等性**：是（只读）。 +- **限流**：无。 + +入参无变化。出参中 `travelers[]` 数组每个 `ArrivalPlanTravelerSimpleVO` 元素新增 `travelerTypeName` 字段（String）。 + +## 4. 接口入参 + +### 4.1 路径参数 / Query 参数 + +| 接口 | 字段 | 类型 | 必填 | 说明 | +|------|------|------|------|------| +| GET /mp/order/{orderId}/arrival | orderId | String（Long） | 是 | 路径参数，订单 ID | +| GET /mp/v3/order/arrival/{orderId} | orderId | String（Long） | 是 | 路径参数，订单 ID | + +### 4.2 请求体字段 + +均为 GET 接口，无请求体。入参无变化。 + +## 5. 出参（响应） + +### 5.1 ArrivalPlanTravelerSimpleVO 字段 + +| 字段 | 类型 | 变更 | 说明 | +|------|------|------|------| +| id | String | 不变 | 出行人记录 ID | +| name | String | 不变 | 出行人姓名（脱敏后） | +| travelerType | String | 不变 | 出行人类型枚举值，见 §6 | +| travelerTypeName | String | **新增** | 出行人类型中文名，由数据字典 `traveler_type` 派生 | + +> 其余字段视接口版本可能含到达信息、证件信息等，本次仅新增 `travelerTypeName`，其余字段不变。 + +## 6. 枚举 / 数据字典 + +### 6.1 travelerType（数据字典：traveler_type） + +**所属字段**：`travelerType`（出参，保留不变）与 `travelerTypeName`（出参，新增中文名） | **类型**：`String` + +| 枚举值 | 中文名（travelerTypeName） | 说明 | +|--------|--------------------------|------| +| `ADULT` | 成人 | 成年旅客 | +| `CHILD` | 儿童 | 儿童旅客（含独立占位） | +| `YOUNG_CHILD` | 小童 | 小童旅客（不占位或半占位） | +| `BABY` | 幼童 | 婴幼儿（不占位） | + +> 字典降级说明：若数据字典 `traveler_type` 中对应 key 缺失，后端使用枚举内置 label 兜底，小程序侧无需处理。 + +## 7. 错误码 + +本次为纯新增字段，无新增错误码。原有错误码不变。 + +| code | 含义 | 触发场景 | +|------|------|----------| +| 581201 | 订单不存在 | orderId 无效 | +| 401 | 未认证 | 未携带或微信 JWT 过期 | +| 403 | 无权限 | 当前用户无权查看该订单的到达计划 | + +## 8. 示例（3 组：典型 / 边界 / 异常） + +### 8.1 典型成功 — 获取到达计划（含新字段） + +请求： +``` +GET /mp/v3/order/arrival/2067178767255560193 +Authorization: Bearer +``` + +响应： +```json +{ + "code": 200, + "data": { + "orderId": "2067178767255560193", + "travelers": [ + { + "id": "2067178767255560201", + "name": "张*明", + "travelerType": "ADULT", + "travelerTypeName": "成人" + }, + { + "id": "2067178767255560202", + "name": "张*", + "travelerType": "YOUNG_CHILD", + "travelerTypeName": "小童" + } + ] + }, + "message": "ok", + "success": true +} +``` + +### 8.2 边界情况 — 仅含 BABY 类型出行人 + +请求： +``` +GET /mp/order/2067178767255560194/arrival +Authorization: Bearer +``` + +响应（含 BABY 类型，travelerTypeName 正常返回）： +```json +{ + "code": 200, + "data": { + "orderId": "2067178767255560194", + "travelers": [ + { + "id": "2067178767255560211", + "name": "李*强", + "travelerType": "ADULT", + "travelerTypeName": "成人" + }, + { + "id": "2067178767255560212", + "name": "李小宝", + "travelerType": "BABY", + "travelerTypeName": "幼童" + } + ] + }, + "message": "ok", + "success": true +} +``` + +### 8.3 业务失败 — 订单不存在 + +请求： +``` +GET /mp/v3/order/arrival/9999999999999999999 +Authorization: Bearer +``` + +响应： +```json +{ + "code": 581201, + "data": null, + "message": "订单不存在", + "success": false +} +``` + +## 9. 业务边界 + +- 适用：用户已登录且有权限访问该订单，处于任何订单状态均可查询到达计划（只读接口）。 +- 适用：四种出行人类型（ADULT / CHILD / YOUNG_CHILD / BABY）均有对应 `travelerTypeName` 中文名。 +- 特殊边界：若数据字典维护缺失某枚举值，`travelerTypeName` 降级返回枚举内置中文名，不会返回 null，小程序无需做 null 保护。 +- 特殊边界：`travelerType` 原字段值不变，若小程序已有本地映射逻辑，可继续保留或切换为直接展示 `travelerTypeName`，两者等价。 + +## 10. 修改前后对比 + +### 10.1 字段级对比 + +| VO | 字段 | 改前 | 改后 | +|----|------|------|------| +| ArrivalPlanTravelerSimpleVO | travelerTypeName | 不存在 | **新增** String，出行人类型中文名 | +| ArrivalPlanTravelerSimpleVO | travelerType | 原样返回英文枚举值 | 保留不变 | + +### 10.2 行为级对比 + +| 行为 | 改前 | 改后 | +|------|------|------| +| 出行人类型展示 | 小程序自行维护 ADULT→成人 等映射表 | 后端直接下发 travelerTypeName，小程序可直接渲染 | +| 字典缺失兜底 | 无 | 降级用枚举内置 label，小程序无感知 | + +## 11. 影响评估 / 回滚 + +### 11.1 影响评估 + +- **是否破坏向后兼容**：**否**，纯新增字段，原字段不变、原结构不变。 +- **前端是否必须同步上线**：**否**，旧小程序代码不读新字段也不会出错，可按需对接。 + +### 11.2 回滚方案 + +- **回滚方式**：revert PR #3954 并重新部署 hl-order-service-v3 及 hl-mp-service，返回字段恢复为无 travelerTypeName 的旧结构。 + +## 12. 注意事项 + +- 前端 workaround 清理点：若小程序已有本地 `travelerType → 中文` 映射对象/函数，上线后可切换为直接读取 `travelerTypeName`，原映射逻辑可清理。 +- `travelerTypeName` 由后端数据字典派生，字典修改后立即生效（无需小程序发版），字典当前值为：ADULT=成人 / CHILD=儿童 / YOUNG_CHILD=小童 / BABY=幼童。 +- `/mp/order/{orderId}/arrival`（一期路径）与 `/mp/v3/order/arrival/{orderId}`（v3 路径）行为一致，都已包含新字段，小程序按当前接入的路径对接即可。 + +## 13. 关联 / 联系人 + +### 13.1 链接 + +- **Issue**: [#3951](https://git.1814.love:8443/wx/HL/issues/3951) +- **PR**: [#3954](https://git.1814.love:8443/wx/HL/pulls/3954) +- **Merge commit**: [16d77c9a5](https://git.1814.love:8443/wx/HL/commit/16d77c9a5) + +### 13.2 联系人 + +- **后端负责人**: @yaosutu