推送调整订单出行人tab紧急联系人接口通知

2026-07-11 17:42:28 +08:00 · 2026-07-11 17:42:28 +08:00 · 037748dcd2
--- a/changelogs-v2/2026-07/11_4908_调整订单出行人tab紧急联系人-修改接口-管理后台.md
+++ b/changelogs-v2/2026-07/11_4908_调整订单出行人tab紧急联系人-修改接口-管理后台.md
@ -0,0 +1,367 @@
+# 【修改接口·管理后台】调整订单出行人 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<TravelerEdit> | 否 | 新增出行人列表 | 空数组表示本次不新增 |
+| `update` | Array<TravelerEdit> | 否 | 更新出行人列表 | 每项必须带 `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 成功响应结构
+
+```json
+{
+  "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 典型成功：只修改订单级紧急联系人
+
+**请求**
+
+```http
+POST /v3/admin/order/2075415561948315650/adjustment/submit
+Authorization: Bearer <token>
+Content-Type: application/json
+```
+
+```json
+{
+  "updates": {
+    "people": {
+      "emergencyContactName": "张三",
+      "emergencyContactPhone": "13800000000",
+      "travelers": {
+        "add": [],
+        "update": [],
+        "remove": []
+      }
+    }
+  }
+}
+```
+
+**响应**
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "success": true,
+  "data": {
+    "success": true
+  }
+}
+```
+
+### 8.2 典型成功：同时修改紧急联系人并新增出行人
+
+**请求**
+
+```http
+POST /v3/admin/order/2075415561948315650/adjustment/submit
+Authorization: Bearer <token>
+Content-Type: application/json
+```
+
+```json
+{
+  "updates": {
+    "people": {
+      "emergencyContactName": "李四",
+      "emergencyContactPhone": "13900000000",
+      "travelers": {
+        "add": [
+          {
+            "name": "王五",
+            "idType": "ID_CARD",
+            "idNo": "110101199001011234",
+            "phone": "13600000000",
+            "birthday": "1990-01-01",
+            "remark": "新增同行人"
+          }
+        ],
+        "update": [],
+        "remove": []
+      }
+    }
+  }
+}
+```
+
+**响应**
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "success": true,
+  "data": {
+    "success": true
+  }
+}
+```
+
+### 8.3 边界：只使用新版 people.travelers，不修改紧急联系人
+
+**请求**
+
+```http
+POST /v3/admin/order/2075415561948315650/adjustment/submit
+Authorization: Bearer <token>
+Content-Type: application/json
+```
+
+```json
+{
+  "updates": {
+    "people": {
+      "travelers": {
+        "add": [],
+        "update": [
+          {
+            "id": "70001001",
+            "phone": "13700000000"
+          }
+        ],
+        "remove": []
+      }
+    }
+  }
+}
+```
+
+**响应**
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "success": true,
+  "data": {
+    "success": true
+  }
+}
+```
+
+### 8.4 异常：紧急联系人电话格式非法
+
+**请求**
+
+```http
+POST /v3/admin/order/2075415561948315650/adjustment/submit
+Authorization: Bearer <token>
+Content-Type: application/json
+```
+
+```json
+{
+  "updates": {
+    "people": {
+      "emergencyContactName": "张三",
+      "emergencyContactPhone": "138"
+    }
+  }
+}
+```
+
+**响应**
+
+```json
+{
+  "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 链接
+
+- **Issue**: [#4908](https://git.1814.love:8443/wx/HL/issues/4908)
+- **PR**: [#4909](https://git.1814.love:8443/wx/HL/pulls/4909)
+- **Merge commit**: [85969df64](https://git.1814.love:8443/wx/HL/commit/85969df64b7d534f5ff93fbe1c7c562f0d79c6e2)
+
+### 13.2 联系人
+
+- **后端负责人**: @yst