# admin 订单详情接口暴露单房差金额字段

> **服务**: hl-order-service-v2(8094)
> **PR**: #1904 (Refs #1900)
> **日期**: 2026-05-09
> **影响范围**: 管理端订单详情页

---

## ⚠️ 关键变化

**admin 订单详情接口** `GET /admin/order/{orderId}` **新增**响应字段 `singleRoomSurcharge`(`BigDecimal`,`@Nullable`)。

PR #1901 实现单房差功能后,只有 mp 端订单详情(`MpOrderDetailVO.priceBreakdown.items`)展示了"单房差"行,**管理端订单详情**(`OrderDetailVO`)看不到单房差金额(只读 totalPrice/surchargeAmount/discountAmount 汇总)。本 PR 补上 admin 端字段。

---

## 一、变更接口

| # | 接口 | 方法 | 路径 | 变更 |
|---|------|------|------|------|
| 1 | 管理端订单详情 | GET | `/admin/order/{orderId}` | 响应 +1 字段 `singleRoomSurcharge: BigDecimal` |

## 二、字段语义

| 场景 | `singleRoomSurcharge` 值 |
|------|---------|
| 下单时 `adultCount==1` 且产品/班期配了单房差 | 该单房差金额(>0,如 `200.00`) |
| 下单时 `adultCount>=2` 不触发单房差 | `null` |
| 老订单(PR #1901 上线前下的)`priceBreakdown` JSON 缺字段 | `null` |
| 老订单 `priceBreakdown=null` | `null` |
| `priceBreakdown` JSON 含字段但值为 0 | `null`(零值不展示,与 mp 端口径对齐) |

**口径**:与 mp 端 `MpOrderDetailVO.priceBreakdown.items` 中"单房差"行的展示口径完全对齐(>0 才视为有效),通过 `MpOrderDetailAssembler.parseSingleRoomSurcharge` 复用解析能力,**单一来源**。

## 三、响应示例

**有单房差订单**:

```json
{
  "code": 200,
  "data": {
    "orderId": "2052xxxxxxxxxxxxx",
    "totalPrice": 4180.00,
    "surchargeAmount": null,
    "singleRoomSurcharge": 200.00,
    "depositAmount": 398.00,
    ...
  }
}
```

**老订单 / 不触发场景**:

```json
{
  "code": 200,
  "data": {
    "orderId": "2052xxxxxxxxxxxxx",
    "totalPrice": 1500.00,
    "surchargeAmount": null,
    "singleRoomSurcharge": null,
    ...
  }
}
```

## 四、前端改动建议(mmg 管理端)

订单详情页**金额构成区域**(目前展示总价 / 优惠 / 附加费 / 订金)新增一行:

```
单房差: ¥200.00     (仅当 singleRoomSurcharge > 0 / 非 null 时展示)
```

- `null` → 整行隐藏(老订单 / 不触发场景)
- `>0` → 展示,金额格式 `¥XXX.XX`

文案/位置可参考既有"附加费"行(`surchargeAmount`)样式,但二者**不互通**(单房差不进 surchargeAmount,语义独立)。

## 五、向后兼容

- 老 admin 前端不读 `singleRoomSurcharge` → 字段被忽略,不报错
- 老订单 `priceBreakdown` JSON 缺字段 → 接口返 `null`,前端按 `null` 隐藏
- mp 端订单详情**完全不变**(本 PR 不动 mp 端)

## 六、测试覆盖

- `OrderDetailQueryServiceTest` +3 用例(JSON 含字段 / 缺字段 / null)
- `MpOrderDetailAssemblerTest` +4 用例(parseSingleRoomSurcharge: null/空/缺字段/=0/>0)
- 测试服已部署 dev:`GET /admin/order/{老订单id}` 返 `singleRoomSurcharge: null` 验证字段路径打通(图省略,字段已在 RespVO keys 里)

## 七、@mmg 关注点

1. 管理端订单详情页金额区加"单房差"行(条件展示)
2. 字段命名与 mp 端 `priceBreakdown.items` 中 label="单房差" 行的 amount 对齐
3. 老订单字段为 null 时整行隐藏
