wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 Actions 软件包 项目 版本发布 百科 动态

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

浏览代码
这个提交包含在：
yaosutu 2026-06-29 14:09:59 +08:00
父节点 6ccdd10866
当前提交 dc65788d5d
共有 1 个文件被更改，包括 229 次插入 和 0 次删除
显示统计 下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件

229
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