8.8 KiB
【修改接口·管理后台】订单调整记录：出参枚举新增 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，含一条出行人资料修改记录）：
{
"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 以分号拼串展示所有变化字段：
{
"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
响应：
{
"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. 注意事项
- 若前端调整记录组件对
items[].type做 switch 渲染（如显示图标 / 颜色），需新增TRAVELER_EDIT分支，建议展示样式与HOTEL_REQ/VEHICLE_REQ（无价差的信息类变更）一致。 before/after中的多字段拼接格式为「字段名 原值；字段名 原值」，前端按原文展示即可，无需解析内部结构。- 证件号 / 手机号已由后端脱敏，前端不可用
before/after做业务判断（脱敏后精度已损）。
13. 关联 / 联系人
13.1 链接
13.2 联系人
- 后端负责人: @yst
- 前端对接（管理后台）: 订单详情·调整记录 Tab