From 7d133e42768049f0e60632fd96e094315430c50b Mon Sep 17 00:00:00 2001
From: yaosutu <770858045@qq.com>
Date: Sat, 6 Jun 2026 12:22:07 +0800
Subject: [PATCH] =?UTF-8?q?docs(changelog):=20=E6=96=B0=E5=A2=9E=E8=A1=A5?=
 =?UTF-8?q?=E5=85=A8=E5=87=BA=E8=A1=8C=E4=BF=A1=E6=81=AF=E8=81=9A=E5=90=88?=
 =?UTF-8?q?=E6=8E=A5=E5=8F=A3(=E7=AE=A1=E7=90=86=E5=90=8E=E5=8F=B0)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

PUT /v3/admin/order/{id}/traveler-info —— 订单详情补全出行信息弹窗专用，全量同步出行人(增/改/删)+紧急联系人+备注。含入参 TravelerInfoSaveReqVO/TravelerItem、出参 RespVO、状态规则、JSON 示例、错误码(581108/581116/581107等)。Issue #3539 / PR #3547。
---
 ..._补全出行信息聚合接口-新增接口-管理后台.md | 132 ++++++++++++++++++
 1 file changed, 132 insertions(+)
 create mode 100644 changelogs-v2/2026-06/06_3539_补全出行信息聚合接口-新增接口-管理后台.md

diff --git a/changelogs-v2/2026-06/06_3539_补全出行信息聚合接口-新增接口-管理后台.md b/changelogs-v2/2026-06/06_3539_补全出行信息聚合接口-新增接口-管理后台.md
new file mode 100644
index 0000000..d71e961
--- /dev/null
+++ b/changelogs-v2/2026-06/06_3539_补全出行信息聚合接口-新增接口-管理后台.md
@@ -0,0 +1,132 @@
+# 补全出行信息聚合接口（管理后台）
+
+> 端类型：**管理后台**（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 保留原值） |
+
+**入参示例**
+```json
+{
+  "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） |
+
+**出参示例**
+```json
+{
+  "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：https://git.1814.love:8443/wx/HL/issues/3539
+- PR：https://git.1814.love:8443/wx/HL/pulls/3547
+- 后端负责人：腰苏图（订单 v3）