hl-api-changelog/changelogs-v2/2026-05/18_2517_traveler-list-path.md

出行人列表: 路径迁移 /travelers → /traveler/list

服务: hl-order-service-v3 (端口 8084 / 二期) PR: #2531 Issue: #2517 日期: 2026-05-18 影响范围: 管理后台订单详情概览 Tab 出行人区块 / F27 出行人补全列表读取 存放目录: changelogs-v2/2026-05/(二期 v3 专属,带 -v2 后缀) 部署 commit: dev-v3 68fd00f85 测试服已验证: ✅(/@qa 通过 9443 网关 + 真 admin token round-trip)

---

⚠️ 关键变化（破坏性路径迁移)

接口路径从 v3 早期临时路径 /travelers 改为文档 V5.48 §2.1 正式路径 /traveler/list:

维度	before(老路径,即将下线)	after(本 PR 起生效)
方法	GET	GET
路径	/v3/admin/order/{id}/travelers	/v3/admin/order/{id}/traveler/list

对前端的影响: 调用方需把请求 URL 从 /travelers 替换为 /traveler/list。 响应结构无变化(仍是 Result<List<TravelerVO>> + 16 字段),前端字段映射不需要改。

---

一、背景

V5.48 文档 §2.1 已把出行人列表正式路径定为 /traveler/list(与 add / batch-edit / delete 等 §2.2~§2.4 接口的路径风格统一: 一级名词 traveler + 二级动词)。早期实现用了简短复数形式 /travelers,本 PR 完成对齐。

同时清理了 TravelerConverter 内残留的 Mock 占位注释,补齐 transportPlanIds 字段的真实化(从桥接表 order_transport_plan_traveler LEFT JOIN 取真值,而非占位空数组)。

---

二、变更接口清单

#	接口	方法	老路径	新路径	变更类型
1	订单出行人列表	GET	/v3/admin/order/{id}/travelers	/v3/admin/order/{id}/traveler/list	破坏性路径迁移

---

三、接口详情

1. 订单出行人列表 GET /v3/admin/order/{id}/traveler/list

VO: TravelerVO(16 字段,无 *Label 衍生字段)

入参

字段	位置	类型	必填	说明
id	Path	Long	✅	订单 ID(雪花 ID 字符串安全形式)

出参 Result<List<TravelerVO>>

字段	类型	说明
id	Long	出行人 ID
orderId	Long	订单 ID
travelerType	String	ADULT / CHILD / YOUNG_CHILD / BABY
name	String?	姓名(占位行为 null)
gender	String?	MALE / FEMALE / UNKNOWN
birthday	LocalDate?	出生日期
idType	String?	ID_CARD / PASSPORT / BIRTH_CERT
idNo	String?	证件号(admin 明文,DB 加密)
nationality	String	国籍(默认"中国")
race	String	民族(默认"汉族")
phone	String?	出行人手机(admin 明文)
emergencyContact	String?	紧急联系人姓名
emergencyPhone	String?	紧急联系人电话(admin 明文)
roomGroupNo	Integer?	同住分组号
profileStatus	String	PENDING / COMPLETED
transportPlanIds	List<Long>	关联大交通批次 ID 列表(来自桥接表)

请求示例

GET /v3/admin/order/60123456789012/traveler/list
Authorization: Bearer {admin_jwt}

响应示例

{
  "code": 200,
  "data": [
    {
      "id": 70123456789012,
      "orderId": 60123456789012,
      "travelerType": "ADULT",
      "name": "张三",
      "gender": "MALE",
      "birthday": "1985-08-12",
      "idType": "ID_CARD",
      "idNo": "220103198508121234",
      "nationality": "中国",
      "race": "汉族",
      "phone": "13800002046",
      "emergencyContact": "李四",
      "emergencyPhone": "13900008888",
      "roomGroupNo": 1,
      "profileStatus": "COMPLETED",
      "transportPlanIds": [80012345, 80012346]
    }
  ],
  "msg": "success"
}

空数据响应

{ "code": 200, "data": [], "msg": "success" }

错误响应

错误码	含义
581100	出行人主段位—— 订单 / 出行人不存在(本接口下订单不存在时返回空集合即 200 + data:[],不报错;此码主要给 batch-edit / add / delete 用)

---

四、契约约束

• 仅 admin JWT 可访问,网关层鉴权(无 token → 网关 401);跨公司读取由订单详情上下文接口在更上层校验,本接口本身只看订单 ID。
• 敏感字段(idNo / phone / emergencyPhone)明文返回,前端勿做二次脱敏渲染(B 端定制师业务诉求,后端已通过 EncryptTypeHandler 在 DB 层加密,VO 层明文)。

---

五、数据库行为

只读接口,不产生任何 DB 写入。

读关联表: order_traveler + LEFT JOIN order_transport_plan_traveler(取 transportPlanIds 真值)。

---

六、边界行为

• 未登录 → 401(网关拦截)
• 订单不存在 / 该订单下无出行人 → 200 + data: [](不 404,不抛异常)
• 出行人有未关联任何大交通的 → transportPlanIds: []
• 占位出行人(name=null idNo=null) → 字段为 null,不异常

---

七、不影响范围

• 仅影响: 管理后台调用 /v3/admin/order/{id}/travelers 的请求 URL 拼接
• 零影响:
  • 响应结构 / 字段名 / 字段类型 / 字段值(VO 完全不变)
  • mp 端出行人列表接口(走 /v3/mp/...,独立路径,未涉及)
  • 订单详情主聚合接口 /v3/admin/order/{id} 内 overview.travelers 嵌套数组(已复用同 VO,本次未改)
  • Feign 跨服务 internal 接口 /internal/order/orders/{orderId}/travelers(internal 路径独立,未涉及)

---

八、测试环境已验证

GET https://web.test.1814.love:9443/v3/admin/order/60123456789012/traveler/list
  Authorization: Bearer {admin_jwt}
  → 200 + List<TravelerVO> 16 字段齐全 ✓
  → transportPlanIds 真值(非占位空数组)✓
  → 老路径 /travelers 已无返回(404)✓

---

九、相关历史 PR

PR	Issue	说明	是否仍有效
#2124	#2123	/traveler/list 入参精简 + 敏感字段改明文(早期路径用 /travelers)	部分有效(敏感字段口径保留,路径被本 PR 覆盖)
#2125	-	detail.overview.travelers 复用 TravelerVO 完整字段	✅ 有效
本 PR #2531	#2517	路径正式迁 /traveler/list + transportPlanIds 真实化	✅ 最新

---

十、相关文档

• API SPEC: D:/work2/HL-v3/docs/order-v3/api/API-SPEC-V5.48.html §2.1
• 关联 Issue: wx/HL#2517
• 关联 PR: wx/HL#2531