wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态
hl-api-changelog/changelogs-v2/2026-06/06_3539_补全出行信息聚合接口-新增接口-管理后台.md
yaosutu b3f88c29fa docs(changelog): 修正补全出行信息接口错误码表(实测校准) 
身份证重复 581105->581119，补 581102(订单不存在)/581104(分组超限)/581118(缺必填)/400/401。23 用例真实 HTTP 测试校准。
2026-06-06 13:59:17 +08:00

6.2 KiB
原始文件 Blame 文件历史

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

端类型：管理后台（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 触发
581102 订单不存在，无法编辑出行人 订单 ID 不存在
581108 当前订单状态不允许编辑出行信息（已完成 / 已取消） 订单已完成/已取消
581116 当前订单状态禁止新增出行人 待支付订单提交了新增项
581107 出行人是订单最后 1 位成人，禁止删除 删除后无任何成人
581110 出行人 ID 不属于该订单 更新项 id 不属于该订单
581111 证件号被已签合同冻结 已签合同订单尝试改证件号
581118 新增出行人缺少必填字段（id=null 时 name/idType/idNo 必填，且 travelerType 必填） 新增项缺必填
581119 出行人证件号重复 同次提交出现重复证件号
581104 同住分组号超出订单家庭数上限 roomGroupNo 超过订单家庭数
581112 / 581113 / 581114 证件号 / 手机 / 生日格式错误 字段格式校验不通过
100702 姓名含非法字符 姓名含数字等非法字符
400 出行人列表不能为空 travelers 为空数组
401 缺少有效的 Authorization 头 未携带 token

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

关联