# 管理端优惠/附加费接口字段修复 — 2026-04-21

> **服务** hl-order-service-v2（端口 8094）· **类型** fix · **关联** Issue #1100 / PR #1101
> **场景**：管理端订单详情 · 财务 Tab · 添加/修改 优惠项 / 费用增加项

---

## 一、问题现象

在管理端订单详情财务 Tab 的「添加优惠项」/「添加费用增加项」窗口中填入名称和金额后提交，接口返回：

```
name: 优惠名称不能为空; amount: 优惠金额不能为空
```

## 二、根因

后端请求 DTO 的字段名与早期发布的接口契约不一致：

| 接口 | 契约字段（前端用） | 之前后端 DTO |
| --- | --- | --- |
| `POST/PUT /admin/order/{orderId}/discount` | `discountName` / `discountAmount` | `name` / `amount` ❌ |
| `POST/PUT /admin/order/{orderId}/surcharge` | `surchargeName` / `surchargeAmount` | `name` / `amount` ❌ |

前端按契约发请求 → 字段对不上 → `@NotBlank` / `@NotNull` 同时命中空值，一并报错。

## 三、修复内容

### 1. 字段名对齐契约

**`DiscountRequest`**：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `discountName` | `String` | ✅ | 优惠名称 |
| `discountAmount` | `BigDecimal` | ✅ `>= 0.01` | 优惠金额（必须大于0） |

**`SurchargeRequest`**：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `surchargeName` | `String` | ✅ | 费用名称 |
| `surchargeAmount` | `BigDecimal` | ✅ `>= 0.01` | 费用金额（必须大于0） |

### 2. 移除死字段

前端无需再传的字段，传了也会被忽略：

- `DiscountRequest.discountType` — Service 强制写入 `MANUAL`，前端传值被丢弃
- `DiscountRequest.remark` — Entity/DB 均无此列
- `SurchargeRequest.remark` — Entity/DB 均无此列

### 3. 新增金额正数校验

| 校验 | 提示 |
| --- | --- |
| `discountAmount < 0.01` | `优惠金额必须大于0` |
| `surchargeAmount < 0.01` | `费用金额必须大于0` |

防止负数优惠 = 变相加钱；负数附加费 = 变相减钱。

---

## 四、正确请求示例

```json
POST /admin/order/700001/discount
{
  "discountName": "老客户优惠",
  "discountAmount": 100.00
}
```

```json
POST /admin/order/700001/surcharge
{
  "surchargeName": "升级房型补差价",
  "surchargeAmount": 200.00
}
```

响应结构（`OrderDiscountVO` / `OrderSurchargeVO`）未变。

---

## 五、错误码

HTTP 始终返回 200，错误码在 `Result.code` 中。

| code | 触发 | 说明 |
| --- | --- | --- |
| 200 | 正常 | 成功 |
| 400 | 字段缺失 | `优惠名称不能为空` / `优惠金额不能为空` / `费用名称不能为空` / `费用金额不能为空` |
| 400 | 金额非正 | `优惠金额必须大于0` / `费用金额必须大于0` |

---

## 六、前端影响

**无需改动**。前端本来就在按 `discountName`/`discountAmount`、`surchargeName`/`surchargeAmount` 发请求，本次修复让后端与契约一致，提交即可成功。

---

## 七、关联

- Issue: [wx/HL#1100](https://git.1814.love:8443/wx/HL/issues/1100)
- PR: [wx/HL#1101](https://git.1814.love:8443/wx/HL/pulls/1101)（已合并到 dev）
- 原始契约：`2026-03-20_order_surcharge.md`
