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

2026-06-28 15:40:31 +08:00 · 2026-06-28 15:40:31 +08:00 · 0b8d673b20
--- a/changelogs-v2/2026-06/28_4540_订单调整记录-新增接口-管理后台.md
+++ b/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）
--- a/changelogs-v2/2026-06/28_4565_退役行程编辑历史接口-删除接口-管理后台.md
+++ b/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）