---
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 修复,前端零改动)