diff --git a/changelogs-v2/2026-06/29_4612_调整记录新增TRAVELER_EDIT变更项-修改接口-管理后台.md b/changelogs-v2/2026-06/29_4612_调整记录新增TRAVELER_EDIT变更项-修改接口-管理后台.md new file mode 100644 index 0000000..2a87824 --- /dev/null +++ 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>` + +**AdjustmentRecordVO**(每条调整记录) + +| 字段 | 类型 | 说明 | +|------|------|------| +| `id` | String | 调整记录 ID | +| `operatorName` | String | 操作人姓名 | +| `adjustedAt` | String | 调整时间(ISO 8601) | +| `changeCount` | Integer | 本次调整的变更项数量 | +| `balanceBefore` | String | 调整前应付尾款(字符串,如 `"1000.00"`) | +| `balanceAfter` | String | 调整后应付尾款(字符串) | +| `items` | Array\ | 变更项明细列表 | + +**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