hl-api-changelog/changelogs-v2/2026-06/18_3951_出行人类型枚举化+类型中文走数据字典-修改接口-管理后台.md

【修改接口·管理后台】✨ 出行人类型中文名 travelerTypeName 新增字段 (#3951)

PR: #3954 | 服务: hl-order-service-v3 | 更新时间: 2026-06-18

1. 接口背景

出行人列表、添加出行人、订单详情等接口原先只返回 travelerType 英文枚举值（ADULT / CHILD / YOUNG_CHILD / BABY），前端需要自行维护一套映射表才能展示中文。本次新增 travelerTypeName 字段，由后端查数据字典 traveler_type 派生中文名后直接下发，前端可零配置展示类型标签。原 travelerType 字段保留不变，属纯新增、非破坏性变更。

2. 变更清单

#	接口	方法	路径	变更类型	说明
1	订单出行人列表	GET	/v3/admin/order/{id}/traveler/list	新增出参字段	每个出行人元素新增 travelerTypeName
2	添加出行人	POST	/v3/admin/order/{id}/traveler/add	新增出参字段	返回的 TravelerVO 新增 travelerTypeName
3	订单详情	GET	/v3/admin/order/{id}	新增出参字段	overview.customerInfo.travelers[] 元素新增 travelerTypeName

3. 接口详情

3.1 订单出行人列表

• 使用场景：订单详情页「出行人」Tab 加载出行人清单时调用。
• 认证：需要 JWT（管理员角色）。
• 幂等性：是（只读）。
• 限流：无。

入参无变化。出参 List<TravelerVO> 每个元素新增 travelerTypeName 字段（String）。

3.2 添加出行人

• 使用场景：在订单详情页为订单添加一位出行人后，接口直接返回包含完整信息的 TravelerVO。
• 认证：需要 JWT（管理员角色）。
• 幂等性：否（写入操作）。
• 限流：无。

入参无变化。出参 TravelerVO 新增 travelerTypeName 字段（String）。

3.3 订单详情

• 使用场景：订单详情页首次加载，获取订单全量信息。
• 认证：需要 JWT（管理员角色）。
• 幂等性：是（只读）。
• 限流：无。

入参无变化。出参 overview.customerInfo.travelers[] 数组中每个 TravelerPlainVO 元素新增 travelerTypeName 字段（String）。

4. 接口入参

4.1 路径参数 / Query 参数

接口	字段	类型	必填	说明
GET /v3/admin/order/{id}/traveler/list	id	String（Long）	是	路径参数，订单 ID
POST /v3/admin/order/{id}/traveler/add	id	String（Long）	是	路径参数，订单 ID
GET /v3/admin/order/{id}	id	String（Long）	是	路径参数，订单 ID

4.2 请求体字段

三个接口入参均无变化。POST /v3/admin/order/{id}/traveler/add 的请求体字段与原契约相同，本次未改动。

5. 出参（响应）

5.1 TravelerVO 字段（接口 1、2 出参元素）

字段	类型	变更	说明
id	String	不变	出行人记录 ID
orderId	String	不变	所属订单 ID
name	String	不变	出行人姓名（脱敏后）
phone	String	不变	手机号（脱敏后）
idCard	String	不变	身份证号（脱敏后）
travelerType	String	不变	出行人类型枚举值，见 §6
travelerTypeName	String	新增	出行人类型中文名，由数据字典 traveler_type 派生
gender	String	不变	性别字典码
nationality	String	不变	国籍

5.2 TravelerPlainVO 字段（接口 3 订单详情 overview.customerInfo.travelers[] 元素）

字段	类型	变更	说明
name	String	不变	出行人姓名（脱敏后）
phone	String	不变	手机号（脱敏后）
travelerType	String	不变	出行人类型枚举值，见 §6
travelerTypeName	String	新增	出行人类型中文名，由数据字典 traveler_type 派生

6. 枚举 / 数据字典

6.1 travelerType（数据字典：traveler_type）

所属字段：travelerType（出参，保留不变）与 travelerTypeName（出参，新增中文名） | 类型：String

枚举值	中文名（travelerTypeName）	说明
ADULT	成人	成年旅客
CHILD	儿童	儿童旅客（含独立占位）
YOUNG_CHILD	小童	小童旅客（不占位或半占位）
BABY	幼童	婴幼儿（不占位）

字典降级说明：若数据字典 traveler_type 中对应 key 缺失，后端使用枚举内置 label 兜底，前端无需处理。

7. 错误码

本次为纯新增字段，无新增错误码。原有错误码不变。

code	含义	触发场景
581201	订单不存在	orderId 无效
581211	出行人不存在	指定出行人 ID 不属于该订单
401	未认证	未携带或 JWT 过期
403	无权限	当前角色无此操作权限

8. 示例（3 组：典型 / 边界 / 异常）

8.1 典型成功 — 查询出行人列表（含新字段）

请求：

GET /v3/admin/order/2067178767255560193/traveler/list
Authorization: Bearer <token>

响应：

{
  "code": 200,
  "data": [
    {
      "id": "2067178767255560201",
      "orderId": "2067178767255560193",
      "name": "张*明",
      "phone": "138****8888",
      "idCard": "110101********1234",
      "travelerType": "ADULT",
      "travelerTypeName": "成人",
      "gender": "MALE",
      "nationality": "中国"
    },
    {
      "id": "2067178767255560202",
      "orderId": "2067178767255560193",
      "name": "张*",
      "phone": "",
      "idCard": "",
      "travelerType": "YOUNG_CHILD",
      "travelerTypeName": "小童",
      "gender": "FEMALE",
      "nationality": "中国"
    }
  ],
  "message": "ok",
  "success": true
}

8.2 边界情况 — 全类型出行人（BABY 幼童）

请求：

GET /v3/admin/order/2067178767255560194/traveler/list
Authorization: Bearer <token>

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

{
  "code": 200,
  "data": [
    {
      "id": "2067178767255560211",
      "orderId": "2067178767255560194",
      "name": "李*强",
      "travelerType": "ADULT",
      "travelerTypeName": "成人",
      "gender": "MALE",
      "nationality": "中国"
    },
    {
      "id": "2067178767255560212",
      "orderId": "2067178767255560194",
      "name": "李*",
      "travelerType": "CHILD",
      "travelerTypeName": "儿童",
      "gender": "MALE",
      "nationality": "中国"
    },
    {
      "id": "2067178767255560213",
      "orderId": "2067178767255560194",
      "name": "李小宝",
      "travelerType": "BABY",
      "travelerTypeName": "幼童",
      "gender": "FEMALE",
      "nationality": "中国"
    }
  ],
  "message": "ok",
  "success": true
}

8.3 业务失败 — 订单 ID 不存在

请求：

GET /v3/admin/order/9999999999999999999/traveler/list
Authorization: Bearer <token>

响应：

{
  "code": 581201,
  "data": null,
  "message": "订单不存在",
  "success": false
}

9. 业务边界

• 适用：订单处于任何状态均可查询出行人列表（只读接口）。
• 适用：出行人类型覆盖 ADULT / CHILD / YOUNG_CHILD / BABY 四种，每种均有对应中文名。
• 特殊边界：若数据字典维护缺失某枚举值，travelerTypeName 降级返回枚举内置中文名（不会返回 null），前端无需做 null 保护。
• 特殊边界：travelerType 原字段值不变，前端若已有本地映射逻辑，可继续保留或切换为直接展示 travelerTypeName，两者语义等价。

10. 修改前后对比

10.1 字段级对比

VO	字段	改前	改后
TravelerVO	travelerTypeName	不存在	新增 String，出行人类型中文名
TravelerPlainVO	travelerTypeName	不存在	新增 String，出行人类型中文名
TravelerVO	travelerType	原样返回英文枚举值	保留不变

10.2 行为级对比

行为	改前	改后
类型中文展示	前端自行维护 ADULT→成人 等映射表	后端直接下发 travelerTypeName，前端可直接渲染
数据字典缺失	无此逻辑	降级用枚举内置 label 兜底，前端无感知

11. 影响评估 / 回滚

11.1 影响评估

• 是否破坏向后兼容：否，纯新增字段，原字段不变、原结构不变。
• 前端是否必须同步上线：否，旧前端代码不读新字段也不会出错，可按需对接。

11.2 回滚方案

• 回滚方式：revert PR #3954 并重新部署 hl-order-service-v3，返回字段恢复为无 travelerTypeName 的旧结构。

12. 注意事项

• 前端 workaround 清理点：若前端已有本地 travelerType → 中文 映射对象/函数，上线后可切换为直接读取 travelerTypeName，原映射逻辑可清理。
• travelerTypeName 由后端数据字典派生，字典修改后立即生效（无需前端发版），字典当前值为：ADULT=成人 / CHILD=儿童 / YOUNG_CHILD=小童 / BABY=幼童。

13. 关联 / 联系人

13.1 链接

• Issue: #3951
• PR: #3954
• Merge commit: 16d77c9a5

13.2 联系人

• 后端负责人: @yaosutu