文档(order-v3/调整记录): 新增 TRAVELER_EDIT 出行人资料修改变更项说明 (#4612 #4614)

2026-06-29 14:09:59 +08:00 · 2026-06-29 14:09:59 +08:00 · dc65788d5d
--- a/changelogs-v2/2026-06/29_4612_调整记录新增TRAVELER_EDIT变更项-修改接口-管理后台.md
+++ b/changelogs-v2/2026-06/29_4612_调整记录新增TRAVELER_EDIT变更项-修改接口-管理后台.md
@ -0,0 +1,229 @@
+# 【修改接口·管理后台】订单调整记录：出参枚举新增 TRAVELER_EDIT（出行人资料修改）(#4614)
+
+> **PR**: #4614 | **服务**: hl-order-service-v3 | **更新时间**: 2026-06-29
+
+## 1. 接口背景
+
+「订单调整记录」接口（`GET /v3/admin/order/{id}/adjustment-record`）返回本订单所有调整操作的逐项变更明细。每条记录含 `items[]` 数组，每个变更项有 `type` 字段表示该项变更的类型。
+
+本次在 `type` 枚举中**新增 `TRAVELER_EDIT`（出行人资料修改）**。此前，定制师在「订单调整」中只修改出行人资料字段（证件类型 / 姓名 / 证件号 / 联系电话），不改人数时，调整记录里**不会产生任何变更项**，导致历史操作看不到「改了什么」。本次修复这一缺口，使每次出行人资料编辑都有迹可查。
+
+同时修复了纯重复提交（出行人字段实际无变化）产生 `changeCount=0` 空记录的问题——现在若字段真的未变，不再产生多余的空记录。
+
+## 2. 变更清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 订单调整记录列表 | GET | `/v3/admin/order/{id}/adjustment-record` | 修改接口 | 出参 `items[].type` 枚举新增 `TRAVELER_EDIT` 取值 |
+
+> 无新增字段、无删除字段、无路径变更，向后兼容。若前端对 `type` 做了穷举 switch / 枚举映射，需补 `TRAVELER_EDIT` 分支。
+
+---
+
+## 3. 接口详情
+
+- **路径**: `GET /v3/admin/order/{id}/adjustment-record`
+- **使用场景**: 管理后台订单详情页「调整记录」Tab，展示历次调整操作的变更明细。
+- **认证**: 需要管理后台 JWT。
+- **幂等性**: GET 只读，无副作用。
+- **限流**: 无特殊限流。
+
+---
+
+## 4. 接口入参
+
+### 4.1 路径参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `id` | Long | ✅ | 订单 ID |
+
+无请求体。
+
+---
+
+## 5. 出参字段
+
+**顶层结构**: `Result<List<AdjustmentRecordVO>>`
+
+**AdjustmentRecordVO**（每条调整记录）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | String | 调整记录 ID |
+| `operatorName` | String | 操作人姓名 |
+| `adjustedAt` | String | 调整时间（ISO 8601） |
+| `changeCount` | Integer | 本次调整的变更项数量 |
+| `balanceBefore` | String | 调整前应付尾款（字符串，如 `"1000.00"`） |
+| `balanceAfter` | String | 调整后应付尾款（字符串） |
+| `items` | Array\<ChangeItemVO\> | 变更项明细列表 |
+
+**ChangeItemVO**（单个变更项）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `type` | String | 变更类型枚举（见第 6 节） |
+| `label` | String | 后端拼好的中文展示名（直接渲染，如 `出行人「张三」资料修改`） |
+| `before` | String | 变更前描述（如 `证件类型 身份证；证件号 110***1234`） |
+| `after` | String | 变更后描述（如 `证件类型 护照；证件号 E12***5678`） |
+| `amountDelta` | String / null | 本项价差（字符串）；`TRAVELER_EDIT` 类型此字段恒为 `null`（资料编辑无价差） |
+
+> `before` / `after` 中的证件号、手机号已由后端脱敏（首 3 末 4，中间全 `*`），前端直接展示即可，无需二次处理。
+> 证件类型显示中文名（身份证 / 护照 / 台胞证 / 回乡证…），由后端查数据字典翻译。
+
+---
+
+## 6. 枚举 / 数据字典
+
+### AdjustChangeType（变更类型枚举）
+
+| 枚举值 | 中文说明 | `amountDelta` | 本次状态 |
+|--------|----------|---------------|----------|
+| `HEADCOUNT` | 人数变更 | 可能有值 | 既有 |
+| `DEPART_DATE` | 出发日期调整 | 可能有值 | 既有 |
+| `TRIP_DAYS` | 行程天数调整 | 可能有值 | 既有 |
+| `EDIT_NODE` | 改项（修改行程节点） | 可能有值 | 既有 |
+| `ADD_NODE` | 增项（新增行程节点） | 可能有值 | 既有 |
+| `REMOVE_NODE` | 删项（删除行程节点） | 可能有值 | 既有 |
+| `HOTEL_REQ` | 酒店需求已调整 | `null` | 既有 |
+| `VEHICLE_REQ` | 车辆需求已调整 | `null` | 既有 |
+| **`TRAVELER_EDIT`** | **出行人资料修改** | **`null`** | **本次新增** |
+
+> 若前端对 `type` 做了穷举渲染（switch / enum map），需补 `TRAVELER_EDIT` 分支，否则该类变更项在列表中可能不显示或落入 default 样式。
+
+---
+
+## 7. 错误码
+
+本接口为只读查询接口，本次变更不引入新错误码。既有错误码（如订单不存在 `581001`）不变。
+
+---
+
+## 8. 示例
+
+### 8.1 典型成功——包含 TRAVELER_EDIT 变更项
+
+**请求**：
+```
+GET /v3/admin/order/1234567890/adjustment-record
+Authorization: Bearer <管理后台 JWT>
+```
+
+**响应**（200，含一条出行人资料修改记录）：
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": [
+    {
+      "id": "9876543210",
+      "operatorName": "李顾问",
+      "adjustedAt": "2026-06-29T10:30:00",
+      "changeCount": 1,
+      "balanceBefore": "6000.00",
+      "balanceAfter": "6000.00",
+      "items": [
+        {
+          "type": "TRAVELER_EDIT",
+          "label": "出行人「张三」资料修改",
+          "before": "证件类型 身份证；证件号 110***1234",
+          "after": "证件类型 护照；证件号 E12***5678",
+          "amountDelta": null
+        }
+      ]
+    }
+  ],
+  "success": true
+}
+```
+
+### 8.2 边界情况——同一次调整多字段同时改变
+
+当出行人同时修改了证件类型、证件号、手机号三个字段，`before` / `after` 以分号拼串展示所有变化字段：
+
+```json
+{
+  "type": "TRAVELER_EDIT",
+  "label": "出行人「李四」资料修改",
+  "before": "证件类型 身份证；证件号 320***5678；手机号 138***0000",
+  "after": "证件类型 台胞证；证件号 TE1***234；手机号 139***9999",
+  "amountDelta": null
+}
+```
+
+> 若出行人只改了一个字段，`before` / `after` 中只出现该字段。
+
+### 8.3 业务失败——订单不存在
+
+**请求**（id 不存在）：
+```
+GET /v3/admin/order/9999999999/adjustment-record
+```
+
+**响应**：
+```json
+{
+  "code": 581001,
+  "message": "订单不存在",
+  "success": false
+}
+```
+
+---
+
+## 9. 业务边界
+
+- ✅ `TRAVELER_EDIT` 仅在「出行人资料字段有实际变化」时才产生变更项（证件类型 / 姓名 / 证件号 / 联系电话四字段任一有变化即记录）。
+- ❌ 出行人字段与原值完全相同（no-op 重复提交）→ 不产生 `TRAVELER_EDIT` 变更项，也不产生 `changeCount=0` 的空记录（本次同步修复）。
+- ❌ 出行人**增减人数**（HEADCOUNT 变更）→ 走 `HEADCOUNT` 类型，不走 `TRAVELER_EDIT`。
+- ⚠️ `TRAVELER_EDIT` 的 `amountDelta` 恒为 `null`（资料编辑不涉及价差），`balanceBefore` 与 `balanceAfter` 在该记录下通常相等。
+- ⚠️ `before` / `after` 已脱敏：前端直接渲染，无需再次脱敏。
+
+---
+
+## 10. 修改前后对比
+
+### 枚举值变化
+
+| 类型 | 变更 |
+|------|------|
+| `TRAVELER_EDIT` | **新增**（此前不存在） |
+| 其余 8 个取值 | 不变 |
+
+### 行为变化
+
+| 场景 | 修改前 | 修改后 |
+|------|--------|--------|
+| 出行人只改资料字段、不改人数 | 调整记录无变更项（看不到操作记录） | 产生 `type=TRAVELER_EDIT` 变更项，可追溯 |
+| 出行人字段提交但无实际变化（no-op） | 产生 `changeCount=0` 的空记录 | 不产生空记录 |
+
+---
+
+## 11. 影响评估 / 回滚
+
+- **是否破坏向后兼容**: 否。纯新增枚举值 + 新增场景下的数据；不影响既有变更项。
+- **前端是否必须同步上线**: 非强制，但**建议尽快补 `TRAVELER_EDIT` 分支**。若前端对 `type` 做穷举渲染而未覆盖此值，出行人资料修改记录会不显示或以 default 样式渲染。
+- **回滚方案**: 本次变更在 Service 层追加枚举分支，后端回滚即恢复旧行为（不产生 `TRAVELER_EDIT` 记录）；已写入 DB 的历史记录不会自动清除，但量极少（仅上线后的操作）。前端无需配合回滚。
+
+---
+
+## 12. 注意事项
+
+1. 若前端调整记录组件对 `items[].type` 做 switch 渲染（如显示图标 / 颜色），需新增 `TRAVELER_EDIT` 分支，建议展示样式与 `HOTEL_REQ` / `VEHICLE_REQ`（无价差的信息类变更）一致。
+2. `before` / `after` 中的多字段拼接格式为「字段名 原值；字段名 原值」，前端按原文展示即可，无需解析内部结构。
+3. 证件号 / 手机号已由后端脱敏，前端**不可**用 `before` / `after` 做业务判断（脱敏后精度已损）。
+
+---
+
+## 13. 关联 / 联系人
+
+### 13.1 链接
+
+- **Issue**: [#4612](https://git.1814.love:8443/wx/HL/issues/4612)
+- **PR**: [#4614](https://git.1814.love:8443/wx/HL/pulls/4614)
+- **Merge commit**: [1744d31b4](https://git.1814.love:8443/wx/HL/commit/1744d31b4875752d5e74cd5c16f7d787c17eeb68)
+
+### 13.2 联系人
+
+- **后端负责人**: @yst
+- **前端对接（管理后台）**: 订单详情·调整记录 Tab