hl-api-changelog/changelogs-v2/2026-06/06_3539_补全出行信息聚合接口-新增接口-管理后台.md

补全出行信息聚合接口（管理后台）

端类型：管理后台（v3）｜变更类型：新增接口｜服务：hl-order-service-v3 Issue #3539 ｜ PR #3547 ｜日期：2026-06-06

接口地址

PUT /v3/admin/order/{id}/traveler-info

接口介绍

订单详情「补全出行信息」弹窗专用接口。一次提交完成：出行人全量同步（增/改/删）+ 订单紧急联系人 + 客户备注更新，单事务原子。

替代原先"前端编排 batch-edit + 多次 delete + PUT 订单"的多接口方案。弹窗打开时先调 GET /v3/admin/order/{id}/traveler/list 回填，编辑（含前端本地删除）后整体提交本接口。

本次修改点

新增接口。配套新错误码 581108。不影响现有 traveler/batch-edit traveler/add traveler/{tid}/delete PUT /v3/admin/order/{id} 及小程序端接口。

入参

路径参数：id（Long，订单 ID，必填）

请求体 TravelerInfoSaveReqVO：

字段	类型	必填	含义
travelers	List<TravelerItem>	是	出行人全集（≤30），见下表。提交即该订单完整出行人列表
emergencyContactName	String	否	紧急联系人姓名（null=保留原值）
emergencyContactPhone	String	否	紧急联系人电话（null=保留原值）
customerRemark	String	否	客户备注（null=保留原值）

TravelerItem（travelers 数组元素）：

字段	类型	必填	含义
id	String	否	出行人 ID。有值=更新该人，null=新增；DB 中存在但本次未提交的 → 删除
name	String	条件	姓名（新增时 name/idType/idNo 至少 1 个非空；不可含数字等非法字符）
gender	String	否	性别 1=男 / 2=女 / 0=未知
birthday	LocalDate	否	出生日期 yyyy-MM-dd
idType	String	否	证件类型 ID_CARD / PASSPORT / BIRTH_CERT
idNo	String	否	证件号（明文传，DB 加密；与 birthday 需一致）
nationality	String	否	国籍（默认中国）
race	String	否	民族（默认汉族）
phone	String	否	出行人手机（明文传，DB 加密）
emergencyContact	String	否	该出行人紧急联系人姓名
emergencyPhone	String	否	该出行人紧急联系人电话
roomGroupNo	Integer	否	同住分组号
travelerType	String	条件	ADULT / CHILD / YOUNG_CHILD / BABY（新增时必填，更新时 null 保留原值）

入参示例

{
  "travelers": [
    {"id": "2062826419733336066", "name": "张大人", "gender": "1", "birthday": "1990-03-07",
     "idType": "ID_CARD", "idNo": "110101199003078531", "phone": "13800138001", "travelerType": "ADULT"},
    {"id": null, "name": "张小孩", "gender": "2", "birthday": "2018-05-12",
     "idType": "ID_CARD", "idNo": "110101201805129524", "phone": "13800138002", "travelerType": "CHILD"}
  ],
  "emergencyContactName": "紧急王",
  "emergencyContactPhone": "13900139000",
  "customerRemark": "客户希望安排素食"
}

出参

Result<TravelerInfoSaveRespVO>

字段	类型	含义
createdCount	Integer	本次新增出行人数
updatedCount	Integer	本次更新出行人数
deletedCount	Integer	本次删除出行人数
completedCount	Integer	当前资料完整(COMPLETED)的出行人数
pendingCount	Integer	当前资料待完善(PENDING)的出行人数
allCompleted	Boolean	是否全部补全（人数=声明数 且 全部 COMPLETED）

出参示例

{
  "code": 200, "message": "成功", "success": true,
  "data": {
    "createdCount": 1, "updatedCount": 1, "deletedCount": 0,
    "completedCount": 2, "pendingCount": 0, "allCompleted": false
  }
}

状态规则（调用约束）

接口行为随订单状态变化，前端需按返回错误码处理：

订单状态	新增	删除/更新	副作用
待支付	❌ 581116	✅	无
定制中（待补全/资源准备/待确认）	✅	✅	无
待出行 / 出行中	✅	✅	后端自动作废旧合同重签 + 退旧保单重投（前端无需额外调用）
已完成 / 已取消	❌ 581108	❌ 581108	整单拒绝编辑

• 通用：订单至少保留 1 位成人，删除最后 1 位成人返回 581107。
• 紧急联系人/备注：传 null 保留原值；传值则更新。
• 出行人全部补全后，订单流程自动从「待补全信息」推进到「资源准备」。

枚举

枚举	取值	含义
travelerType	ADULT / CHILD / YOUNG_CHILD / BABY	成人 / 儿童 / 小童 / 婴儿
idType	ID_CARD / PASSPORT / BIRTH_CERT	身份证 / 护照 / 出生证
gender	1 / 2 / 0	男 / 女 / 未知

错误码

code	message	触发
581108	当前订单状态不允许编辑出行信息（已完成/已取消）	订单已完成/已取消
581116	当前订单状态禁止新增出行人	待支付订单提交了新增项
581107	出行人是订单最后 1 位成人，禁止删除	删除后无任何成人
581110	出行人不属于该订单	更新项 id 不属于该订单
581111	证件号被已签合同冻结	已签合同订单尝试改证件号
581105	证件号重复	同次提交出现重复证件号
581112 / 581113 / 581114	证件号/手机/生日格式错误	字段格式校验不通过
100702	姓名含非法字符	姓名含数字等非法字符

幂等：同一订单 3 秒内重复提交会被拒绝（防重复点击/网络重试），前端避免短时间重复提交。

关联

• Issue：wx/HL#3539
• PR：wx/HL#3547
• 后端负责人：腰苏图（订单 v3）