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

新增管理后台 changelog：订单调整记录新接口 (#4540/#4556) + 退役行程编辑历史接口 (#4565/#4569)

浏览代码
这个提交包含在：
yaosutu 2026-06-28 15:40:31 +08:00
父节点 884d6a42b9
当前提交 0b8d673b20
共有 2 个文件被更改，包括 522 次插入 和 0 次删除
显示统计 下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件

256
changelogs-v2/2026-06/28_4540_订单调整记录-新增接口-管理后台.md 普通文件
查看文件

@ -0,0 +1,256 @@
# 订单调整记录——新增「调整记录」列表接口，按次展示每次 submit 改了什么
> 端类型：管理后台
> 变更类型：新增接口
> 涉及接口：
> - `GET /v3/admin/order/{id}/adjustment-record`（查询订单调整记录列表）
---
## ① 接口背景
订单调整（submit）原来只在时间线追加一条「订单调整」无明细说明。前端调整弹窗无法向操作人展示「本次调整改了哪些项」。
本期新建独立「调整记录」：每次 submit 成功后在 `order_adjustment_record` 表落一条记录（含每项变更的类型、文案、前值、后值、金额差），后台订单详情「调整记录」弹窗调用本接口逐条渲染。
---
## ② 变更清单
| 编号 | 类型 | 说明 |
|---|---|---|
| 1 | ✨ 新增接口 | `GET /v3/admin/order/{id}/adjustment-record`，返回本订单全部调整记录（按时间倒序） |
| 2 | ✨ 新增 VO | `AdjustmentRecordVO`（记录主体）/ `ChangeItemVO`（单项变更）/ `StatusNoteVO`（状态摘要） |
| 3 | ✨ 新增枚举 | `AdjustChangeType`，定义 8 个变更类型（见§⑥） |
---
## ③ 接口详情
| 项目 | 说明 |
|---|---|
| 方法 | GET |
| 路径 | `/v3/admin/order/{id}/adjustment-record` |
| 接口名 | 查询调整记录列表 |
| 认证 | 需要 JWT（管理后台 Token） |
| 幂等性 | 只读，天然幂等 |
| 限流 | 无特殊限流 |
| 分页 | 不分页（全量返回；单订单调整次数预期 < 50 条） |
---
## ④ 接口入参
### 4.1 路径参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|:---:|---|
| `id` | Long（String） | 是 | 订单 ID（雪花 ID，JS 请当字符串处理） |
### 4.2 请求体
无请求体。
---
## ⑤ 出参字段
### 顶层结构
```
Result<List<AdjustmentRecordVO>>
```
data 为 `AdjustmentRecordVO` 数组，按 `occurredAt` 降序（最新调整在前）。无调整记录时 `data: []`。
### AdjustmentRecordVO（调整记录主体）
| 字段 | 类型 | 可空 | 说明 |
|---|---|:---:|---|
| `id` | String | 否 | 调整记录 ID（雪花 ID 序列化为字符串，防 JS 精度丢失） |
| `occurredAt` | String | 否 | 调整发生时间，格式 `yyyy-MM-dd HH:mm:ss` |
| `operatorName` | String | 否 | 操作人姓名（定制师真名） |
| `changeCount` | Integer | 否 | 本次变更项总数，渲「N 项变更」 |
| `items` | List&lt;ChangeItemVO&gt; | 否 | 变更明细列表（至少 1 项） |
| `statusNote` | StatusNoteVO | 是 | 本次调整引发的状态摘要；无状态变化时为 `null` |
| `balanceBefore` | Number | 否 | 调整前待付尾款（BigDecimal，无精度丢失风险，保留两位小数） |
| `balanceAfter` | Number | 否 | 调整后待付尾款（BigDecimal，保留两位小数） |
> `balanceBefore` / `balanceAfter` 是权威尾款，不要用 `Σ(items[].amountDelta)` 推算（两者不同轴）。
### ChangeItemVO（单项变更明细）
| 字段 | 类型 | 可空 | 说明 |
|---|---|:---:|---|
| `type` | String | 否 | 变更类型枚举值（见§⑥ AdjustChangeType） |
| `label` | String | 否 | 前端直显文案，后端已拼好（含资源名/翻译），**前端零拼接** |
| `before` | String | 是 | 变更前值（新增类为 null） |
| `after` | String | 是 | 变更后值（删除类为 null） |
| `amountDelta` | Number | 是 | 本项声明价差（正=加费/负=减费；仅行程节点类有值，其余 null） |
> `before` / `after` 都非空时渲「before → after」；`amountDelta` 非 null 时渲金额差（>0 渲 `+¥X`，<0 渲 `-¥X`，=0 渲 `+¥0`）。
### StatusNoteVO（状态变化摘要，可空）
| 字段 | 类型 | 可空 | 说明 |
|---|---|:---:|---|
| `title` | String | 否 | 摘要标题，如「状态回滚」 |
| `content` | String | 否 | 摘要内容，如「房型与车辆已退回准备中，等待房控/车控复核」 |
---
## ⑥ 枚举 / 数据字典
### AdjustChangeType（items[].type 取值）
| 枚举值 | 含义 |
|---|---|
| `HEADCOUNT` | 出行人数量变化（成人/儿童/小童/婴儿各档分别一条） |
| `DEPART_DATE` | 出发日期调整 |
| `TRIP_DAYS` | 行程天数变化（汇总一行，不逐天刷屏） |
| `EDIT_NODE` | 编辑已有行程节点（单价/数量改价） |
| `ADD_NODE` | 新增行程节点（增项） |
| `REMOVE_NODE` | 删除行程节点（删项） |
| `HOTEL_REQ` | 酒店需求已调整（粒度：本期只记「已调整」一句） |
| `VEHICLE_REQ` | 车辆需求已调整（粒度：本期只记「已调整」一句） |
---
## ⑦ 错误码
| code | message | 含义 | 前端处理建议 |
|---|---|---|---|
| 586001 | 订单不存在 | 订单 ID 无效或已删除 | toast 错误 |
| 200 + data:[] | （正常） | 本订单暂无调整记录 | 渲空态「暂无调整记录」 |
---
## ⑧ 示例
### 8.1 典型成功——7 项变更（含状态回滚）
**请求**
```http
GET /v3/admin/order/7910000000001/adjustment-record
Authorization: Bearer <token>
```
**响应**
```json
{
"code": 200,
"message": "success",
"data": [
{
"id": "7920000000001",
"occurredAt": "2026-06-28 14:35:18",
"operatorName": "李雯",
"changeCount": 7,
"items": [
{ "type": "ADD_NODE", "label": "增项「敖鲁古雅驯鹿园」", "before": null, "after": null, "amountDelta": 200.00 },
{ "type": "ADD_NODE", "label": "增项「莫尔道嘎国家森林公园」", "before": null, "after": null, "amountDelta": 150.00 },
{ "type": "ADD_NODE", "label": "增项「室韦俄罗斯族民族乡」", "before": null, "after": null, "amountDelta": 0.00 },
{ "type": "ADD_NODE", "label": "增项「额尔古纳湿地公园」", "before": null, "after": null, "amountDelta": 120.00 },
{ "type": "ADD_NODE", "label": "增项「黑山头古城遗址」", "before": null, "after": null, "amountDelta": 0.00 },
{ "type": "TRIP_DAYS", "label": "行程天数调整", "before": "7天6晚", "after": "8天7晚", "amountDelta": null },
{ "type": "HEADCOUNT", "label": "成人人数调整", "before": "2", "after": "4", "amountDelta": null }
],
"statusNote": {
"title": "状态回滚",
"content": "请核对补充新增旅客信息·房型与车辆已退回准备中，等待房控/车控复核"
},
"balanceBefore": 0.00,
"balanceAfter": 0.00
}
]
}
```
### 8.2 边界情况——无调整记录
**请求**
```http
GET /v3/admin/order/7910000000002/adjustment-record
Authorization: Bearer <token>
```
**响应**
```json
{
"code": 200,
"message": "success",
"data": []
}
```
> 前端渲空态「暂无调整记录」。
### 8.3 业务失败——订单不存在
**请求**
```http
GET /v3/admin/order/9999999999999/adjustment-record
Authorization: Bearer <token>
```
**响应**
```json
{
"code": 586001,
"message": "订单不存在",
"data": null
}
```
---
## ⑨ 业务边界
**适用：**
- 任意状态的订单均可调用（含已取消、已完成），用于查阅历史。
- 每次调整弹窗 submit 成功后落一条记录；无 submit 历史则返空数组。
**不适用：**
- 本接口不展示行程点编辑历史（行程节点单点增删改不走 adjustment-record，走时间线）。
- 不展示状态变更日志（时间线接口覆盖）。
**特殊边界：**
- `statusNote` 只在本次调整引发订单子流程状态回滚（如改期/增减天导致配房配车退回准备中）时有值，否则为 `null`，前端需做空值保护。
- `amountDelta` 是每项操作的「声明价差」，与后端算价引擎算出的实际尾款差（`balanceAfter - balanceBefore`）可能不等，**尾款以 `balanceBefore` / `balanceAfter` 为准**。
---
## ⑩ 修改前后对比
本次为新增接口，无修改前后对比。
---
## ⑪ 影响评估 / 回滚
本次为新增接口，不影响任何现有接口；回滚只需停止调用本端点。
---
## ⑫ 注意事项
1. `id` 字段是雪花 ID 序列化为字符串，JS 请勿转 Number（精度丢失）。
2. `occurredAt` 格式为 `yyyy-MM-dd HH:mm:ss`（后端 Jackson 序列化），非 ISO 8601。
3. `items[].label` 已由后端拼好（含资源中文名），前端直接渲染，**不要尝试自己拼接**。
4. `before` / `after` 双非空才渲箭头；`statusNote` 为 null 时整块不渲（无需占位符）。
5. 本接口不分页，全量返回；若某订单调整次数异常多（> 50），前端可加折叠「展开更多」做 UX 保护（后端不限制）。
---
## ⑬ 关联 / 联系人
- Issue：[#4540](https://git.1814.love:8443/wx/HL/issues/4540)
- PR：[#4556](https://git.1814.love:8443/wx/HL/pulls/4556)
- Commit：[34e921b9e](https://git.1814.love:8443/wx/HL/commit/34e921b9ef3b77f6707fc5b720187e876ec5581f)
- 后端负责人：腰苏图（yst）

266
changelogs-v2/2026-06/28_4565_退役行程编辑历史接口-删除接口-管理后台.md 普通文件
查看文件

@ -0,0 +1,266 @@
# 退役行程编辑历史接口——删除 edit-log/page 端点 + 7 个写接口响应删 editLogId 字段
> 端类型：管理后台
> 变更类型：删除接口（⚠️ 破坏性，前端需清理依赖）
> 涉及接口：
> - `GET /v3/admin/order/{orderId}/itinerary/edit-log/page`（已下线，调用返 404）
> - `POST /v3/admin/order/{orderId}/itinerary/days`（响应删 `editLogId`）
> - `PUT /v3/admin/order/{orderId}/itinerary/days/{dayId}`（响应删 `editLogId`）
> - `DELETE /v3/admin/order/{orderId}/itinerary/days/{dayId}`（响应删 `editLogId`）
> - `POST /v3/admin/order/{orderId}/itinerary/nodes`（响应删 `editLogId`）
> - `PUT /v3/admin/order/{orderId}/itinerary/nodes/{nodeId}`（响应删 `editLogId`）
> - `DELETE /v3/admin/order/{orderId}/itinerary/nodes/{nodeId}`（响应删 `editLogId`）
> - `POST /v3/admin/order/{orderId}/itinerary/save`（响应删 `editLogIds` 数组）
---
## ① 接口背景
搭建期行程节点的单点编辑历史（`order_itinerary_edit_log` 表）已退役：搭建阶段的编辑操作不再留痕，后续调整记录改由「调整记录」（`order_adjustment_record`）承接（见 PR #4556）。本次退役操作包含：
1. 下线「行程编辑历史分页」查询端点。
2. 7 个行程写操作的响应 VO 删除 `editLogId` / `editLogIds` 字段（原用于记录 Tab 跳转定位，不再有意义）。
---
## ② 变更清单
| 编号 | 类型 | 说明 |
|---|---|---|
| 1 | ⚠️ 删除接口 | `GET /v3/admin/order/{orderId}/itinerary/edit-log/page` **已下线，调用返 404** |
| 2 | ⚠️ 删除字段 | `ItineraryDayRespVO` 删除 `editLogId`（Long/String）字段 |
| 3 | ⚠️ 删除字段 | `ItineraryNodeRespVO` 删除 `editLogId`（Long/String）字段 |
| 4 | ⚠️ 删除字段 | `ItinerarySaveRespVO` 删除 `editLogIds`（Long 数组）字段 |
| 5 | 保留入参 | `editReason` 入参字段**保留**（后端接受但不再审计落库，不影响前端调用） |
---
## ③ 接口详情
### 已下线接口：GET /v3/admin/order/{orderId}/itinerary/edit-log/page
⚠️ **本接口已永久下线。调用时网关/服务返回 404 Not Found，不再响应任何请求。**
| 项目 | 说明 |
|---|---|
| 方法 | GET（已下线） |
| 路径 | `/v3/admin/order/{orderId}/itinerary/edit-log/page` |
| 状态 | **已删除，请勿调用** |
### 保留接口（响应字段有变）：行程写操作接口群
以下 7 个接口**路径和方法不变**，仅出参删字段：
| 方法 | 路径 | 接口名 | 删除字段 |
|---|---|---|---|
| POST | `/v3/admin/order/{orderId}/itinerary/days` | 新增行程天 | `editLogId` |
| PUT | `/v3/admin/order/{orderId}/itinerary/days/{dayId}` | 修改行程天 | `editLogId` |
| DELETE | `/v3/admin/order/{orderId}/itinerary/days/{dayId}` | 删除行程天 | `editLogId` |
| POST | `/v3/admin/order/{orderId}/itinerary/nodes` | 新增行程节点 | `editLogId` |
| PUT | `/v3/admin/order/{orderId}/itinerary/nodes/{nodeId}` | 修改行程节点 | `editLogId` |
| DELETE | `/v3/admin/order/{orderId}/itinerary/nodes/{nodeId}` | 删除行程节点 | `editLogId` |
| POST | `/v3/admin/order/{orderId}/itinerary/save` | 批量保存行程 | `editLogIds`（数组） |
---
## ④ 接口入参
7 个保留接口的入参**无变化**。`editReason` 字段仍可传（接受但不落库）。
---
## ⑤ 出参字段
### ItineraryDayRespVO（删 editLogId）
以下字段已从新增/修改/删除行程天的响应中移除：
| 字段 | 原类型 | 变更 |
|---|---|---|
| `editLogId` | String（Long 序列化） | ⚠️ **已删除** |
其余字段（`id` / `dayNumber` / `dayDate` / `theme` / `description` / `nodes[]` / `adjustmentId` / `createTime` 等）不变。
### ItineraryNodeRespVO（删 editLogId）
| 字段 | 原类型 | 变更 |
|---|---|---|
| `editLogId` | String（Long 序列化） | ⚠️ **已删除** |
其余字段不变。
### ItinerarySaveRespVO（删 editLogIds）
| 字段 | 原类型 | 变更 |
|---|---|---|
| `editLogIds` | List&lt;Long&gt; | ⚠️ **已删除** |
现有出参字段（`savedDayIds` / `savedNodeIds` / `deletedDayIds` / `deletedNodeIds`）不变。
---
## ⑥ 枚举 / 数据字典
无新增枚举变更。
---
## ⑦ 错误码
| 接口 | code | message | 说明 |
|---|---|---|---|
| 已下线端点 | 404 | 接口不存在 | 调用旧路径返回此错误 |
---
## ⑧ 示例
### 8.1 典型成功——新增行程天响应（editLogId 已不存在）
**请求**
```http
POST /v3/admin/order/7910000000001/itinerary/days
Authorization: Bearer <token>
Content-Type: application/json
{
"theme": "天池徒步",
"description": "长白山天池观景台",
"editReason": "补充行程细节"
}
```
**响应（editLogId 字段已删除）**
```json
{
"code": 200,
"message": "success",
"data": {
"id": "8801234567890",
"dayNumber": 3,
"dayDate": "2026-08-03",
"theme": "天池徒步",
"description": "长白山天池观景台",
"nodes": [],
"adjustmentId": null,
"createTime": "2026-06-28T15:30:00"
}
}
```
> 注意：响应中**不含 `editLogId` 字段**，原来前端读取的 `data.editLogId` 现在为 `undefined`，请清理相关依赖。
### 8.2 边界情况——批量保存响应（editLogIds 已不存在）
**请求**
```http
POST /v3/admin/order/7910000000001/itinerary/save
Authorization: Bearer <token>
Content-Type: application/json
{
"days": [ ... ]
}
```
**响应（editLogIds 数组已删除）**
```json
{
"code": 200,
"message": "success",
"data": {
"savedDayIds": ["8801234567890"],
"savedNodeIds": ["8811234567890", "8811234567891"],
"deletedDayIds": [],
"deletedNodeIds": []
}
}
```
### 8.3 业务失败——调用已下线的旧路径
**请求**
```http
GET /v3/admin/order/7910000000001/itinerary/edit-log/page
Authorization: Bearer <token>
```
**响应（404，旧路径已删）**
```json
{
"code": 404,
"message": "接口不存在: GET /v3/admin/order/{id}/itinerary/edit-log/page",
"data": null
}
```
---
## ⑨ 业务边界
**不适用：**
- 旧的「行程编辑历史」分页功能已永久下线，无法通过任何方式恢复调用。
- 搭建期单点编辑操作不再审计留痕（若需调整记录，使用调整弹窗 submit，走「调整记录」接口 PR #4556）。
**特殊边界：**
- `editReason` 入参字段可以继续传（后端不报错），但值被忽略，不再写入任何审计表。前端无需改传参代码，但继续传入对服务端无实际效果。
---
## ⑩ 修改前后对比
### 接口变更
| 接口 | 修改前 | 修改后 |
|---|---|---|
| `GET .../itinerary/edit-log/page` | 正常返回 PageResult&lt;EditLogVO&gt; | **已下线，返回 404** |
| 行程写操作 7 个接口 | 响应含 `editLogId` / `editLogIds` | **响应不含该字段** |
### 字段级对比
#### ItineraryDayRespVO / ItineraryNodeRespVO
| 字段 | 修改前 | 修改后 |
|---|---|---|
| `editLogId` | String，本次写入的 edit_log 主键 | ⚠️ **已删除，不存在** |
#### ItinerarySaveRespVO
| 字段 | 修改前 | 修改后 |
|---|---|---|
| `editLogIds` | List&lt;Long&gt;，本次产生的 edit_log id 列表 | ⚠️ **已删除，不存在** |
---
## ⑪ 影响评估 / 回滚
**前端需做的改造：**
1. 删除对 `GET .../itinerary/edit-log/page` 的调用及相关 UI（行程编辑历史列表）。
2. 删除读取 `data.editLogId` 的代码（行程天/节点写操作响应）。
3. 删除读取 `data.editLogIds` 的代码（批量保存行程响应）。
**回滚方案：**
本次是纯删除，字段/端点已从代码移除。若需回滚，需后端重新发版恢复，前端无单独回滚方案。**建议前端同步本次上线部署后立即清理依赖，避免读 undefined 字段引发运行时错误。**
---
## ⑫ 注意事项
1. **旧路径 404**：`edit-log/page` 已彻底下线，务必在本次联调前删除调用代码，否则页面会出现 404 请求错误。
2. **editLogId 变 undefined**：行程写操作响应不再包含 `editLogId`，若前端曾用此值做「记录 Tab 跳转定位」，该功能需同步下线或改用时间线接口。
3. **editLogIds 变 undefined**：批量保存响应中 `editLogIds` 数组已删，若前端有读取逻辑需一并清理。
4. **editReason 入参可保留**：入参字段 `editReason` 仍可传（后端不报错），不强制移除，但其值不再产生任何审计记录。
---
## ⑬ 关联 / 联系人
- Issue：[#4565](https://git.1814.love:8443/wx/HL/issues/4565)
- PR：[#4569](https://git.1814.love:8443/wx/HL/pulls/4569)
- Commit：[a5a321ebe](https://git.1814.love:8443/wx/HL/commit/a5a321ebecb58b0b656d2889b00612ee28ef3862)
- 后端负责人：腰苏图（yst）