diff --git a/changelogs/2026-05/08_feat_single_room_diff.md b/changelogs/2026-05/08_feat_single_room_diff.md new file mode 100644 index 0000000..0619d1f --- /dev/null +++ b/changelogs/2026-05/08_feat_single_room_diff.md @@ -0,0 +1,252 @@ +# 价格日历加单房差字段:成人=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) |