# 价格日历加单房差字段:成人=1 时计入总价

> **服务**: hl-product-service-v2(8093)+ hl-order-service-v2(8094)
> **PR**: #1901
> **Issue**: #1900
> **日期**: 2026-05-08
> **影响范围**: 管理端价格日历(所有产品类型)+ GROUP 班期编辑器 + 小程序订单确认页价格 / 明细面板 + 管理端订单详情明细面板

---

## ⚠️ 关键变化(管理端 + 小程序必读)

**价格日历 / 班期新增 `singleRoomDiff` 必填字段(单房差)**:

- 管理端"编辑价格区间"弹窗 + GROUP"班期编辑"弹窗:**4 个价格输入框旁加一列"单房差 ¥xxx"必填输入框**(0 = 不收)
- 小程序订单确认页:**`adultCount == 1` 触发**(严格 == 1,与儿童/小童/幼童数量无关),后端把 `singleRoomDiff` 累加到 `totalPrice`
- 订单详情明细面板:`singleRoomSurcharge > 0` 时多出一行"单房差 ¥xxx",= 0 或老订单缺字段时不展示
- **定金不变**:比例定金按 `baseTotal`(不含单房差)算;固定/人定金不动

---

## 一、背景

1 个成人单住一房时,实际成本高于双人均摊 — 管理员需要为此场景配置单房差。本期实现:

1. 价格日历(`product_price_calendar`)+ 班期表(`group_tour_batch`)各加 `single_room_diff DECIMAL(12,2) NOT NULL DEFAULT 0`
2. 算价时**严格** `adultCount == 1` 触发,累加到 `totalPrice` + 写入 `priceBreakdown` JSON
3. 订单明细多一行展示
4. 定金算法不变(具体见下文 D2/D3)

---

## 二、变更接口清单

| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|------|------|------|----------|------|
| 1 | 管理端批量保存价格日历 | POST | `/admin/product/{id}/price-calendar/batch` | 请求体加必填字段 | `singleRoomDiff` 必填(@NotNull @DecimalMin("0.00")) |
| 2 | 管理端查询价格日历 | GET | `/admin/product/{id}/price-calendar` | 响应加字段 | 每条记录回传 `singleRoomDiff` |
| 3 | 管理端 GROUP 班期保存 | POST/PUT | (Schedule 系列) | 请求体加必填字段 | `singleRoomDiff` 必填 |
| 4 | 管理端 GROUP 班期查询 | GET | (Schedule 系列) | 响应加字段 | 回传 `singleRoomDiff` |
| 5 | 内部简单报价 | GET | `/internal/product/{productId}/simple-quote` | 响应加 2 字段 | `singleRoomDiff`(配置值)+ `singleRoomSurcharge`(本次实际加价,0 或 = diff) |
| 6 | 内部 GROUP 报价 | GET | `/internal/product/{productId}/group-quote` | 响应加 2 字段 | 同上 |
| 7 | 小程序订单详情 | GET | `/mp/order/{id}` | **行为变更** | `priceBreakdown.items[]` 当 `singleRoomSurcharge > 0` 时多出一行 "单房差" |
| 8 | 管理端订单详情 | GET | `/admin/order/{id}` | 无变化 | admin 端不读 priceBreakdown,只读汇总字段 |
| 9 | 创建订单(C 端 / admin) | POST | `/mp/order/create` 等 | **行为变更** | `OrderInfo.totalPrice` 已包含单房差;`OrderInfo.priceBreakdown` JSON 包含 `singleRoomDiff` + `singleRoomSurcharge` 字段 |

---

## 三、决策点

### D1 触发条件(严格)

```
if (adultCount == 1) {
    singleRoomSurcharge = singleRoomDiff;
} else {
    singleRoomSurcharge = 0;
}
```

**只看 adultCount 是否严格等于 1**,与儿童 / 小童 / 幼童数量无关。`adultCount == 0` 不触发(下单本来就要求至少 1 成人,@Min(1));`adultCount >= 2` 不触发。

### D2 比例定金基数(不含单房差)

```
比例定金 = baseTotal × ratio / 100
其中 baseTotal = totalPrice - singleRoomSurcharge
```

**保证"定金计算逻辑不变"**:不含单房差的基础价 × 比例 = 定金;尾款 = totalPrice - 定金(自然就含了单房差)。

### D3 固定/人定金不动

```
固定定金 = depositAmount/人 × 定金人头(成人 + 儿童 + 小童)
```

与单房差完全解耦。

### D7 落库归属(不进 surcharge_amount)

| 字段 / 表 | 是否含单房差 |
|---|---|
| `order_info.total_price` | **是**(含单房差) |
| `order_info.price_breakdown` JSON | **是**(`singleRoomSurcharge` 字段) |
| `order_info.surcharge_amount` | **否**(语义=后期附加费,与单房差解耦) |
| `order_surcharge` 表 | **否**(不写单房差行) |

### D9 修订单 `adminEditOrder` 改 4 count **不重算**单房差

⚠ **管理端"编辑订单"弹窗改成人/儿童/小童/幼童数后,后端不会重新计算 totalPrice / depositAmount / 单房差**(维持现有契约,Line 140 的 manualPrice 注释已说明:"调价统一走加优惠/加附加费接口")。

**影响场景**:
- 用户原下单成人=1 → 含单房差 200,定制师改为成人=2 → totalPrice 仍含 200(应不含),客户多付 200
- 反之改为成人=1,totalPrice 缺 200(应含),少收 200

**应对**:定制师改人数后,如需调整单房差,**通过"加附加费"接口**手动落 `order_surcharge` 一笔(正负皆可)。本期不开发自动重算路径,后续单独工单再做。

---

## 四、接口详情

### 1. 管理端批量保存价格日历 `POST /admin/product/{id}/price-calendar/batch`

**VO**: `PriceCalendarBatchReqVO`

#### 入参变化

新增字段:

```json
{
  "startDate": "2026-04-01",
  "endDate": "2026-04-30",
  "tierSeq": 1,
  "priceType": "NORMAL",
  "adultSellPrice": 4105,
  "childSellPrice": 1865,
  "toddlerDiscount": -500,
  "infantPrice": 0,
  "singleRoomDiff": 200,
  "dailyStock": null
}
```

| 字段 | 必填 | 校验 | 说明 |
|---|---|---|---|
| `singleRoomDiff` | **必填** | @NotNull @DecimalMin("0.00") | 不传 → 400;< 0 → 400 |

### 5. 内部简单报价 `GET /internal/product/{productId}/simple-quote`

**响应 VO 新增字段**:

```json
{
  "adultPrice": 4105,
  "childPrice": 1865,
  ...,
  "adultTotal": 4105,
  ...,
  "singleRoomDiff": 200,
  "singleRoomSurcharge": 200,
  "totalPrice": 4305,
  "depositAmount": 100,
  "stock": 99
}
```

- `singleRoomDiff` — 价格日历配置的单房差(无论 adultCount 是多少都返回)
- `singleRoomSurcharge` — 本次报价**实际加价金额**:`adultCount == 1 ? singleRoomDiff : 0`
- `totalPrice` 已经包含 `singleRoomSurcharge`
- `depositAmount`(比例定金时)按 `(totalPrice - singleRoomSurcharge) × ratio` 算

### 7. 小程序订单详情 `GET /mp/order/{id}` 价格明细行为变更

**`priceBreakdown.items[]` 数组结构**:

```json
{
  "items": [
    {"label": "成人", "unitPrice": 4105, "quantity": 1, "amount": 4105},
    {"label": "儿童", "unitPrice": 1865, "quantity": 0, "amount": 0},
    {"label": "小童", "unitPrice": 1365, "quantity": 0, "amount": 0},
    {"label": "幼童", "unitPrice": 0, "quantity": 0, "amount": 0},
    {"label": "单房差", "unitPrice": null, "quantity": null, "amount": 200}
  ]
}
```

**单房差行的特殊处理**:
- `unitPrice` / `quantity` 为 `null`(整笔费用,不按人头)
- `amount` 即为本次单房差金额
- **仅当 `singleRoomSurcharge > 0` 时才出现此行**;= 0 或老订单缺字段时不展示

---

## 五、前端改动建议(mmg)

### 管理端

#### 价格日历 - "编辑价格区间"弹窗

参考用户截图布局,在"幼童"输入框右侧加一列必填输入框:

```
[成人 *] [儿童 *] [小童优惠额] [幼童] [单房差 *]
```

- placeholder: `¥ 必填,0=不收`
- 提示文案 / hover tip:"成人=1 人下单时叠加到总价"
- 校验:必填 + 不能为负数

#### GROUP 班期编辑

同上,在班期价格区域加"单房差"必填输入框。

### 小程序

#### 订单确认页

- 总价 / 定金:**直接展示后端返回的 `totalPrice` / `depositAmount`**,前端**不要自己加单房差**(防止双计)
- 明细面板:从后端返回的 `priceBreakdown.items[]` 直接渲染,如有 `label === "单房差"` 一行,展示 `amount`,无 `unitPrice` / `quantity` 列

#### 不需要改造

- 选择人数控件:不需要改(adultCount = 1 时由后端自动加单房差,前端无感)
- 定金 / 尾款显示:无变化

### 管理端订单详情

- 不读 `priceBreakdown`,只读 `totalPrice` 汇总字段,无需改造

---

## 六、向后兼容

- **老 calendar / batch 数据**:`single_room_diff` 列 DEFAULT 0,行为=关闭单房差,与原逻辑一致
- **老订单**:`priceBreakdown` JSON 缺 `singleRoomSurcharge` 字段时,解析端 `isMissingNode()` 跳过,不报错不展示空行
- **老 App 仍传 `singleRoomDiff` 不会**(本来就没此字段)
- **新建/编辑必填**:管理员每次保存价格区间或班期都得显式填(@NotNull),不允许默认 0

---

## 七、@mmg 关注点

1. 管理端价格日历"编辑价格区间"弹窗加单房差必填输入框
2. 管理端 GROUP 班期编辑器加同款输入框
3. 小程序订单确认页明细面板渲染"单房差"行(条件出现)
4. **D9 注意**:管理端"编辑订单"弹窗改成人/儿童/小童/幼童数后,后端**不会**重算单房差。建议在该弹窗加文案提示:"如改人数导致单房差变化,请通过『加附加费』接口手动调整"(可选,本期不强制)

---

## 八、错误码

无新增错误码。校验失败统一走 Spring Validation 默认 400 message。

---

## 九、影响范围(经核确认无影响)

| 系统 | 是否影响 | 说明 |
|---|---|---|
| 早鸟优惠 | 否 | 落 `order_discount` 表减尾款,与定金无关;`min(totalPrice)` 上限保护 |
| 微信支付 | 否 | 公式 `totalPrice - discount + surcharge` 自洽 |
| 退款 | 否 | refundAmount 是 admin 手输入,代码层不依赖 totalPrice 拆分 |
| 起步价 / 列表"¥xxx 起" | 否 | 不算单房差(展示用) |
| 保险费 | 否 | 按人头 × 保单单价 |
| 12301 上报 | 否 | 团费按 totalPrice 上报,自洽 |
| 合同 PDF | 否 | 团费金额 = totalPrice |
| C 端价格日历视图 | 否 | 只展示成人/儿童/小童/幼童 4 价 |
| 兜底对账 | 否 | `totalPrice - discount + surcharge` 公式自洽 |
| `order_surcharge` 表 / 后期附加费 | 否 | 单房差不进此表(D7) |