wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 工作流 软件包 项目 发布 百科 活动
文件
chore/6392-api-changelog
hl-api-changelog/changelogs-v2/2026-07/11_4908_调整订单出行人tab紧急联系人-修改接口-管理后台.md
T

12 KiB
原始文件 永久链接 Blame 文件历史

【修改接口·管理后台】调整订单出行人 tab 支持订单级紧急联系人提交 (#4908)

PR: #4909 | 服务: hl-order-service-v3 | 更新时间: 2026-07-11 18:00

1. 接口背景

调整订单弹窗的出行人 tab 已能读取订单级紧急联系人姓名和电话，但提交接口此前只能通过 updates.travelers 提交出行人增删改，无法在同一个 tab 内提交订单级紧急联系人。

本次在统一提交接口中新增 updates.people 结构，前端可以在出行人 tab 一次性提交订单级紧急联系人和出行人增删改。

2. 变更清单

# 接口 方法 路径 变更类型 说明
1 调整订单统一提交 POST /v3/admin/order/{orderId}/adjustment/submit 修改接口 入参新增 updates.people，承载订单级紧急联系人与出行人增删改
2 调整记录变更项 - items[].type 修改枚举 新增 EMERGENCY_CONTACT，用于表示订单级紧急联系人变更

3. 接口详情

3.1 调整订单统一提交

  • 使用场景: 管理后台调整订单弹窗点击提交时调用；本次主要服务出行人 tab。
  • 认证: 管理后台 JWT。
  • 幂等性: 非幂等；每次提交会按请求内容生成调整记录。
  • 路径: POST /v3/admin/order/{orderId}/adjustment/submit

4. 入参

4.1 路径参数

字段 类型 必填 说明
orderId Long/String 是 订单 ID，雪花 ID 建议前端按字符串传递

4.2 请求体总结构

字段 类型 必填 说明 校验规则
updates Object 是 各子域改动容器 不能为 null，且至少包含一个有效子域
updates.people PeopleUpdate 否 出行人 tab 新契约；推荐前端后续使用该字段提交出行人 tab 本字段存在时会走 PEOPLE 编辑窗口校验
updates.travelers TravelerBatch 否 旧版出行人增删改契约 保留兼容；当 updates.people.travelers 同时存在时，优先使用 updates.people.travelers
updates.schedule Object 否 改期子域 本次未变
updates.itinerary Object 否 行程子域 本次未变
updates.hotelRequirement Object 否 房需求子域 本次未变
updates.vehicleRequirement Object 否 车需求子域 本次未变

4.3 PeopleUpdate 字段

字段 类型 必填 说明 校验规则
emergencyContactName String 否 订单级紧急联系人姓名；不传表示不修改姓名 传入时会 trim；trim 后不能为空；姓名格式不合法时返回姓名格式相关错误
emergencyContactPhone String 否 订单级紧急联系人电话；不传表示不修改电话 传入时会 trim；trim 后不能为空；必须为 11 位数字
travelers TravelerBatch 否 出行人增删改分组 与旧 updates.travelers 结构相同

说明：

  • 只修改紧急联系人时，可以传 travelers 为空数组或不传 travelers。
  • 只提交出行人增删改时，可以只传 updates.people.travelers。
  • 同时传 updates.people.travelers 和旧 updates.travelers 时，本次以后服务端优先读取 updates.people.travelers。

4.4 TravelerBatch 字段

字段 类型 必填 说明 校验规则
add Array 否 新增出行人列表 空数组表示本次不新增
update Array 否 更新出行人列表 每项必须带 id 才能定位已有出行人
remove Array<Long/String> 否 删除出行人 ID 列表 空数组表示本次不删除

4.5 TravelerEdit 字段

字段 类型 必填 说明 校验规则
id Long/String 更新时必填 出行人记录 ID 新增时可不传
name String 否 出行人姓名 规则沿用既有出行人编辑逻辑
idType String 否 证件类型 例如 ID_CARD
idNo String 否 证件号 规则沿用既有出行人编辑逻辑
phone String 否 手机号 规则沿用既有出行人编辑逻辑
travelerType String 否 出行人类型 ADULT / CHILD 等既有取值
birthday String 否 出生日期 yyyy-MM-dd
remark String 否 备注 可为空

5. 出参

5.1 响应字段

字段 类型 说明
code Integer 统一响应码，成功为 200
message String 响应消息
success Boolean 统一响应派生字段；code=200 时为 true
data.success Boolean 调整订单提交是否成功

5.2 成功响应结构

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

6. 枚举 / 数据字典

6.1 调整记录变更项类型 items[].type

所属字段：GET /v3/admin/order/{orderId}/adjustment-record 响应里的 items[].type。

值 中文 说明
HEADCOUNT 出行人数变化 成人、儿童、幼童、婴儿数量变化
DEPART_DATE 出发日期调整 改期产生
TRIP_DAYS 行程天数变化 行程增减天产生
EDIT_NODE 编辑行程节点 行程节点价格或数量等变化
ADD_NODE 新增行程节点 行程新增节点产生
REMOVE_NODE 删除行程节点 行程删除节点产生
HOTEL_REQ 酒店需求调整 房需求调整产生
VEHICLE_REQ 车辆需求调整 车需求调整产生
TRAVELER_EDIT 出行人资料修改 已有出行人字段修改产生
EMERGENCY_CONTACT 订单级紧急联系人变更 本次新增；修改 updates.people.emergencyContactName 或 updates.people.emergencyContactPhone 后产生

6.2 证件类型 TravelerEdit.idType

值 中文 说明
ID_CARD 身份证 既有出行人证件类型

6.3 出行人类型 TravelerEdit.travelerType

值 中文 说明
ADULT 成人 既有出行人类型
CHILD 儿童 既有出行人类型

7. 错误码

code 含义 触发场景
581109 紧急联系人姓名和电话必填 本次提交了 emergencyContactName 或 emergencyContactPhone，但对应字段 trim 后为空
581113 手机号格式非法（应为 11 位数字） updates.people.emergencyContactPhone 不是 11 位数字
587002 订单已是终态，不可调整 订单已结算、已取消、已退款等终态时提交调整
587033 未检测到有效变更，无需提交 updates 没有有效改动，或提交值与当前值一致
587034 已出行，出行人不可调整 订单流程已到出行中或之后，提交 people 或 travelers

8. 示例

8.1 典型成功：只修改订单级紧急联系人

请求

POST /v3/admin/order/2075415561948315650/adjustment/submit
Authorization: Bearer <token>
Content-Type: application/json

{
  "updates": {
    "people": {
      "emergencyContactName": "张三",
      "emergencyContactPhone": "13800000000",
      "travelers": {
        "add": [],
        "update": [],
        "remove": []
      }
    }
  }
}

响应

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

8.2 典型成功：同时修改紧急联系人并新增出行人

请求

POST /v3/admin/order/2075415561948315650/adjustment/submit
Authorization: Bearer <token>
Content-Type: application/json

{
  "updates": {
    "people": {
      "emergencyContactName": "李四",
      "emergencyContactPhone": "13900000000",
      "travelers": {
        "add": [
          {
            "name": "王五",
            "idType": "ID_CARD",
            "idNo": "110101199001011234",
            "phone": "13600000000",
            "birthday": "1990-01-01",
            "remark": "新增同行人"
          }
        ],
        "update": [],
        "remove": []
      }
    }
  }
}

响应

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

8.3 边界：只使用新版 people.travelers，不修改紧急联系人

请求

POST /v3/admin/order/2075415561948315650/adjustment/submit
Authorization: Bearer <token>
Content-Type: application/json

{
  "updates": {
    "people": {
      "travelers": {
        "add": [],
        "update": [
          {
            "id": "70001001",
            "phone": "13700000000"
          }
        ],
        "remove": []
      }
    }
  }
}

响应

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

8.4 异常：紧急联系人电话格式非法

请求

POST /v3/admin/order/2075415561948315650/adjustment/submit
Authorization: Bearer <token>
Content-Type: application/json

{
  "updates": {
    "people": {
      "emergencyContactName": "张三",
      "emergencyContactPhone": "138"
    }
  }
}

响应

{
  "code": 581113,
  "message": "手机号格式非法（应为 11 位数字）",
  "success": false,
  "data": null
}

9. 业务边界

  • updates.people.emergencyContactName 和 updates.people.emergencyContactPhone 均为可选字段；不传表示不修改对应字段。
  • 传入紧急联系人字段时，空字符串不表示清空，会被视为非法入参。
  • 仅修改订单级紧急联系人时，不会产生人数差价，也不会触发配房或配车重新配置。
  • updates.people.travelers 复用既有出行人增删改逻辑；新增、更新、删除出行人可能继续触发既有人数差价和后续调整逻辑。
  • 订单流程已到出行中或之后时，people 和旧 travelers 均不可提交。

10. 修改前后对比

10.1 入参字段对比

字段 修改前 修改后
updates.people 不支持 新增，作为出行人 tab 推荐提交结构
updates.people.emergencyContactName 不支持 支持提交订单级紧急联系人姓名
updates.people.emergencyContactPhone 不支持 支持提交订单级紧急联系人电话
updates.people.travelers 不支持 支持提交出行人 add/update/remove
updates.travelers 支持 继续兼容；当与 updates.people.travelers 同时存在时优先使用 updates.people.travelers

10.2 调整记录对比

字段 修改前 修改后
items[].type 无法表达订单级紧急联系人变更 新增 EMERGENCY_CONTACT
items[].label 无对应值 紧急联系人
items[].before / items[].after 无对应值 返回姓名和电话变更摘要，电话脱敏展示

11. 影响评估 / 回滚

11.1 影响评估

  • 是否破坏向后兼容: 否。旧 updates.travelers 仍可用。
  • 前端是否必须同步上线: 否。旧出行人增删改调用可继续工作；需要在出行人 tab 修改订单级紧急联系人时，前端改用 updates.people。
  • 建议前端改造点: 出行人 tab 提交时统一组装到 updates.people，把订单级紧急联系人放在 emergencyContactName/emergencyContactPhone，把出行人增删改放在 travelers。

11.2 回滚方案

  • 如需回滚后端，前端可临时继续使用旧 updates.travelers 完成出行人增删改。
  • 回滚后订单级紧急联系人不能再通过调整订单 submit 接口修改，需要前端隐藏或禁用出行人 tab 的紧急联系人提交入口。

12. 注意事项

  • 新旧契约并存期间，不建议同一次请求同时提交 updates.people.travelers 和 updates.travelers，避免前端误以为两份都会合并执行。
  • updates.people.emergencyContactPhone 必须传 11 位数字，不支持带空格、短横线或区号。
  • 紧急联系人电话在调整记录中脱敏展示，不要用调整记录回填编辑表单；编辑表单仍应以 snapshot 返回的订单级紧急联系人字段为准。

13. 关联 / 联系人

13.1 链接

13.2 联系人

  • 后端负责人: @yst
在新工单中引用 查看 Git Blame 复制永久链接