hl-api-changelog/changelogs-v2-mp/2026-06/18_3951_到达计划出行人类型中文-修改接口-小程序端.md

【修改接口·小程序端】✨ 到达计划出行人类型中文名 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 <mp-token>

响应：

{
  "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 <mp-token>

响应（含 BABY 类型，travelerTypeName 正常返回）：

{
  "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 <mp-token>

响应：

{
  "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
• PR: #3954
• Merge commit: 16d77c9a5

13.2 联系人

• 后端负责人: @yaosutu