hl-api-changelog/changelogs/2026-04/2026-04-21_mp-order-traveler-crud.md

微信小程序 · 订单出行人 CRUD 接口(4 个)

日期:2026-04-21 影响:微信小程序 订单出行人管理(原型 L4xYN 乘坐人员勾选列表、Bf9jC 添加人员弹窗) PR:#1022(Closes #1020)

---

概述

订单维度的出行人管理接口,区别于用户维度的"我的常用出行人":

接口前缀	数据范围	用途
/mp/order/{orderId}/traveler	本接口,order_traveler 表	订单出行人(随订单绑定)
/mp/user/traveler	用户维度user-service	用户常用出行人(跨订单复用)

共 4 个接口:列表、新增、修改、删除。

---

1. 出行人列表

GET /mp/order/{orderId}/traveler

鉴权:Bearer token。

入参

参数	位置	类型	必填
orderId	Path	Long	✅

出参 Result<List<MpOrderTravelerVO>>

MpOrderTravelerVO:

字段	类型	说明
travelerId	Long	出行人ID
name	String	姓名
travelerType	String	出行人类型(字典 traveler_type):ADULT / CHILD / YOUNG_CHILD / BABY
travelerTypeLabel	String	类型中文标签
idCardType	String	证件类型(字典 id_card_type):ID_CARD / PASSPORT / HK_MACAO_PASS / TAIWAN_PASS / OTHER
idCardTypeLabel	String	证件类型中文标签
idCardNo	String	证件号码
gender	String	1=男 / 2=女
birthday	LocalDate	出生日期
phone	String	手机号
nationality	String	国籍
emergencyContact	String	紧急联系人姓名
emergencyPhone	String	紧急联系人电话
email	String	邮箱

响应示例

{
  "code": 200,
  "message": "成功",
  "data": [
    {
      "travelerId": 10001,
      "name": "张三",
      "travelerType": "ADULT",
      "travelerTypeLabel": "成人",
      "idCardType": "ID_CARD",
      "idCardTypeLabel": "身份证",
      "idCardNo": "110101199001011234",
      "gender": "1",
      "birthday": "1990-01-01",
      "phone": "13800000000",
      "nationality": "中国",
      "emergencyContact": "李四",
      "emergencyPhone": "13900000000",
      "email": "zhangsan@example.com"
    }
  ],
  "success": true
}

---

2. 新增出行人

POST /mp/order/{orderId}/traveler

鉴权:Bearer token。 自动解析:idCardType=ID_CARD 时,后端根据 idCardNo 自动解析并回填 birthday + gender。

入参

参数	位置	类型	必填
orderId	Path	Long	✅

Body MpOrderTravelerSaveReqVO:

字段	类型	必填	约束	说明
name	String	✅	≤50	姓名
idCardType	String	否	-	证件类型,默认 ID_CARD;可选 ID_CARD / PASSPORT / HK_MACAO_PASS / TAIWAN_PASS / OTHER
idCardNo	String	✅	-	证件号码
phone	String	否	-	手机号
gender	String	否	-	1=男 / 2=女(身份证时可省略,自动解析)
birthday	LocalDate	否	-	出生日期(身份证时可省略,自动解析)
travelerType	String	否	-	默认 ADULT;可选 ADULT / CHILD / YOUNG_CHILD / BABY
nationality	String	否	-	国籍
emergencyContact	String	否	-	紧急联系人姓名
emergencyPhone	String	否	-	紧急联系人电话
email	String	否	-	邮箱

请求示例

{
  "name": "张三",
  "idCardType": "ID_CARD",
  "idCardNo": "110101199001011234",
  "phone": "13800000000",
  "travelerType": "ADULT",
  "nationality": "中国",
  "emergencyContact": "李四",
  "emergencyPhone": "13900000000",
  "email": "zhangsan@example.com"
}

出参

Result<MpOrderTravelerVO> — 新创建的出行人,结构同第 1 节。birthday 和 gender 已由后端回填。

---

3. 修改出行人

PUT /mp/order/{orderId}/traveler/{travelerId}

鉴权:Bearer token。 字段语义:null 保持原值,只传需要修改的字段即可(部分更新)。

入参

参数	位置	类型	必填
orderId	Path	Long	✅
travelerId	Path	Long	✅

Body:MpOrderTravelerSaveReqVO(同第 2 节,但各字段均可为 null 表示不改)。

出参

Result<MpOrderTravelerVO> — 修改后的完整信息。

---

4. 删除出行人

DELETE /mp/order/{orderId}/traveler/{travelerId}

鉴权:Bearer token。

入参

参数	位置	类型	必填
orderId	Path	Long	✅
travelerId	Path	Long	✅

出参

Result<Void>:

{ "code": 200, "message": "成功", "data": null, "success": true }

---

边界行为

• 订单不存在 / 不属于当前用户:500,message 含 orderId
• 出行人不存在 / 不属于该订单:500,message 含 travelerId
• idCardType=ID_CARD 时 idCardNo 格式不合法:400,message 含错误原因
• 删除出行人时,若该出行人已被某到达批次关联,批次绑定同步软删(不会阻断删除)
• 订单状态为 CANCELLED / REFUNDED 时禁止修改/新增/删除

---

字典依赖

字典类型	可选值
traveler_type	ADULT / CHILD / YOUNG_CHILD / BABY
id_card_type	ID_CARD / PASSPORT / HK_MACAO_PASS / TAIWAN_PASS / OTHER

所有 xxxLabel 字段由 BFF 透传自 order-v2,已经是中文展示值。