From 0b8d673b20950d53c294bdcea69a2835ca0db983 Mon Sep 17 00:00:00 2001 From: yaosutu <770858045@qq.com> Date: Sun, 28 Jun 2026 15:40:31 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=B0=E5=A2=9E=E7=AE=A1=E7=90=86=E5=90=8E?= =?UTF-8?q?=E5=8F=B0=20changelog=EF=BC=9A=E8=AE=A2=E5=8D=95=E8=B0=83?= =?UTF-8?q?=E6=95=B4=E8=AE=B0=E5=BD=95=E6=96=B0=E6=8E=A5=E5=8F=A3=20(#4540?= =?UTF-8?q?/#4556)=20+=20=E9=80=80=E5=BD=B9=E8=A1=8C=E7=A8=8B=E7=BC=96?= =?UTF-8?q?=E8=BE=91=E5=8E=86=E5=8F=B2=E6=8E=A5=E5=8F=A3=20(#4565/#4569)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../28_4540_订单调整记录-新增接口-管理后台.md | 256 +++++++++++++++++ ..._退役行程编辑历史接口-删除接口-管理后台.md | 266 ++++++++++++++++++ 2 files changed, 522 insertions(+) create mode 100644 changelogs-v2/2026-06/28_4540_订单调整记录-新增接口-管理后台.md create mode 100644 changelogs-v2/2026-06/28_4565_退役行程编辑历史接口-删除接口-管理后台.md diff --git a/changelogs-v2/2026-06/28_4540_订单调整记录-新增接口-管理后台.md b/changelogs-v2/2026-06/28_4540_订单调整记录-新增接口-管理后台.md new file mode 100644 index 0000000..e65ca14 --- /dev/null +++ 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> +``` + +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<ChangeItemVO> | 否 | 变更明细列表（至少 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 +``` + +**响应** + +```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 +``` + +**响应** + +```json +{ + "code": 200, + "message": "success", + "data": [] +} +``` + +> 前端渲空态「暂无调整记录」。 + +### 8.3 业务失败——订单不存在 + +**请求** + +```http +GET /v3/admin/order/9999999999999/adjustment-record +Authorization: Bearer +``` + +**响应** + +```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） diff --git a/changelogs-v2/2026-06/28_4565_退役行程编辑历史接口-删除接口-管理后台.md b/changelogs-v2/2026-06/28_4565_退役行程编辑历史接口-删除接口-管理后台.md new file mode 100644 index 0000000..75d5d2d --- /dev/null +++ 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<Long> | ⚠️ **已删除** | + +现有出参字段（`savedDayIds` / `savedNodeIds` / `deletedDayIds` / `deletedNodeIds`）不变。 + +--- + +## ⑥ 枚举 / 数据字典 + +无新增枚举变更。 + +--- + +## ⑦ 错误码 + +| 接口 | code | message | 说明 | +|---|---|---|---| +| 已下线端点 | 404 | 接口不存在 | 调用旧路径返回此错误 | + +--- + +## ⑧ 示例 + +### 8.1 典型成功——新增行程天响应（editLogId 已不存在） + +**请求** + +```http +POST /v3/admin/order/7910000000001/itinerary/days +Authorization: Bearer +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 +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 +``` + +**响应（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<EditLogVO> | **已下线，返回 404** | +| 行程写操作 7 个接口 | 响应含 `editLogId` / `editLogIds` | **响应不含该字段** | + +### 字段级对比 + +#### ItineraryDayRespVO / ItineraryNodeRespVO + +| 字段 | 修改前 | 修改后 | +|---|---|---| +| `editLogId` | String，本次写入的 edit_log 主键 | ⚠️ **已删除，不存在** | + +#### ItinerarySaveRespVO + +| 字段 | 修改前 | 修改后 | +|---|---|---| +| `editLogIds` | List<Long>，本次产生的 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）