hl-api-changelog/changelogs/2026-04/2026-04-20_order-v2_mp-order-traveler.md

订单出行人 MP 端 CRUD 接口新增 — 2026-04-20

服务 hl-order-service-v2（端口 8094）· 类型 feat · 关联 Issue #1020 / PR #1022 前端调用路径: 网关(8080) → hl-mp-service(8085) → hl-order-service-v2(8094) 前端实际请求前缀: /mp/order/{orderId}/traveler（4 个接口）

---

一、能力概述

给小程序端补齐订单出行人 CRUD 能力，对应原型 L4xYN 乘坐人员勾选列表、Bf9jC 添加人员弹窗。

原型节点	功能	主要接口
L4xYN pplList	乘坐人员勾选列表	GET /mp/order/{orderId}/traveler
Bf9jC	添加人员弹窗	POST /mp/order/{orderId}/traveler
Bf9jC（编辑）	修改出行人	PUT /mp/order/{orderId}/traveler/{travelerId}
Bf9jC（删除）	删除出行人	DELETE /mp/order/{orderId}/traveler/{travelerId}

注意区分两套"出行人"模型：

维度	路径	说明
用户常用出行人	/mp/user/traveler/*	user-service 管，已有
订单出行人（本次新增）	/mp/order/{orderId}/traveler/*	order-v2 的 order_traveler 表

---

二、接口清单

鉴权：user token（登录态）

方法	路径	用途
GET	/mp/order/{orderId}/traveler	查某订单的出行人列表
POST	/mp/order/{orderId}/traveler	新增出行人到某订单
PUT	/mp/order/{orderId}/traveler/{travelerId}	修改出行人（字段为 null 保持原值不变）
DELETE	/mp/order/{orderId}/traveler/{travelerId}	删除出行人

---

三、请求体（MpOrderTravelerSaveReqVO）

{
  "name":             "张三",               // 必填，≤50 字
  "idCardType":       "ID_CARD",            // 字典 id_card_type
  "idCardNo":         "110101199001011234", // 必填
  "phone":            "13800000000",
  "gender":           "1",                  // 1=男 2=女
  "birthday":         "1990-01-01",
  "travelerType":     "ADULT",              // 默认 ADULT，字典 traveler_type
  "nationality":      "中国",
  "emergencyContact": "李四",
  "emergencyPhone":   "13900000000",
  "email":            "zhangsan@example.com"
}

字典取值：

• idCardType: ID_CARD 身份证 / PASSPORT 护照 / HK_MACAO_PASS 港澳通行证 / TAIWAN_PASS 台湾通行证 / OTHER 其他
• travelerType: ADULT 成人 / CHILD 儿童 / YOUNG_CHILD 幼儿 / BABY 婴儿

后端自动处理：

• 身份证（18 位）自动解析 birthday + gender（前端可不传）
• 同订单证件号重复检查（重复抛业务错误）

---

四、响应体

列表 GET 响应

{
  "code": 200,
  "data": [
    {
      "travelerId":       10001,             // Long，注：未强制 String（现有约定）
      "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"
    }
  ]
}

新增/修改返回

返回单个对象（同列表元素结构）。

删除返回

{ "code": 200, "data": null }

约定

• 所有枚举字段都配 xxxLabel 中文标签
• 空数据返回 []，不是 null
• 时间格式统一 yyyy-MM-dd（出生日期）/ yyyy-MM-dd HH:mm:ss（含时间字段）

---

五、前端接入建议

L4xYN 乘坐人员勾选列表：

1. 打开页面 → GET /mp/order/{orderId}/traveler 拉取订单已有出行人
2. 用户勾选 → 把 travelerId 传给到达信息接口的 travelerIds 字段

Bf9jC 添加人员弹窗：

1. 可选：先调 GET /mp/user/traveler（已有）让用户从常用库选一个 → 填到表单里
2. 用户补全/修改字段（含 OCR 扫描身份证填入，OCR 用小程序原生插件前端做）
3. 提交 POST /mp/order/{orderId}/traveler

---

六、关联

• Issue: wx/HL#1020
• PR: wx/HL#1022（已合并到 dev）