新增 2026-04-23 order-v2 费用增加项/折扣 VO 加 source 字段,ROOM_UPGRADE 条目前端隐藏删除/修改按钮

changelogs/2026-04/2026-04-23_order-v2_surcharge-discount-source-hide-delete.md

@@ -0,0 +1,68 @@
+---
+date: 2026-04-23
+type: feat
+scope: order-service-v2
+pr: "#1262"
+issue: "#1257"
+breaking: false
+audience: [hl-ui]
+---
+
+# 费用增加项 / 折扣列表 VO 新增 source 字段;ROOM_UPGRADE 条目需隐藏删除/修改按钮
+
+## 需求背景
+
+配房「差价确认」弹窗确认提交后,后端自动按总差价符号分流写入:
+- 正差价 → `order_surcharge` 新增 1 条 `name="升级房型"`
+- 负差价 → `order_discount` 新增 1 条 `name="房间优惠"`
+
+这些**自动生成的条目**用户不能手动删除/修改,**必须通过重新配房**自动清除。因此前端需要在列表渲染时识别并隐藏这些条目的操作按钮。
+
+## 契约变更(增量,非 breaking)
+
+### `AdminOrderSurchargeVO`(费用增加项)
+新增字段:
+```json
+{
+  "source": "MANUAL | ROOM_UPGRADE"
+}
+```
+- `MANUAL`: 手动添加,照旧显示「删除」「修改」按钮
+- `ROOM_UPGRADE`: 配房差价自动生成,**隐藏**「删除」「修改」按钮
+
+### `AdminOrderDiscountVO`(订单折扣)
+同上,新增 `source` 字段,枚举值与规则同。
+
+### 历史数据
+- 历史手动添加的条目 `source=MANUAL`(DB 默认值),前端行为与旧版一致
+- 新的 `ROOM_UPGRADE` 条目只在本次 PR 部署后、用户触发配房 execute 后才会出现
+
+## 相关接口路径(无签名变化)
+
+- `GET /admin/order/{orderId}/surcharge` — 费用增加项列表(返回的 VO 列表里每条多 `source` 字段)
+- `GET /admin/order/{orderId}/discount` — 订单折扣列表(同上)
+- `POST /admin/order/{orderId}/surcharge` / `PUT .../{id}` / `DELETE .../{id}` — 手动 CRUD 保持不变(后端不拦截,前端自行根据 source 隐藏入口)
+- 配房执行 `PUT /admin/order/{orderId}/hotel-assignment` — 无前端契约变化,但调用成功后下次列表查询会自动带上 ROOM_UPGRADE 条目
+
+## 前端改动建议
+
+```js
+// 渲染按钮前先判 source
+{row.source !== 'ROOM_UPGRADE' && <DeleteButton ... />}
+{row.source !== 'ROOM_UPGRADE' && <EditButton ... />}
+
+// 可选:给 ROOM_UPGRADE 条目加个小标签提示"系统自动生成,重新配房后自动更新"
+{row.source === 'ROOM_UPGRADE' && <Tag color="blue">自动</Tag>}
+```
+
+## 验证
+
+- 后端 `PR #1262` 本地 curl + 测试服网关 curl 已验证三路径(正/负/零差价)
+- 前端可用测试服订单 `2046864526866886657` 走配房流程验证
+
+## 相关
+
+- 工单: Gitea #1257
+- 后端 PR: #1262
+- 后端 changelog: `hl-backend-changelog/2026-04/2026-04-23_order-v2_room-diff-sync-surcharge-discount.md`(含 DDL + 同事务内分流逻辑)
+- 前置: PR #1250(配房差价预览 3 连环 BUG 修复,前端零改动)