docs: 补充新建订单单房差算价口径

changelogs-v2/2026-07/58_新建订单预估价改用产品报价接口-前端待处理-管理后台.md

@@ -8,14 +8,14 @@
 
 ## 1. 结论
 
-新建订单的预估总价必须在用户选择出发日期后，通过产品服务报价接口计算。禁止继续使用产品起价 `startPrice` 或 `儿童数 * 0.7` 在前端估算。
+新建订单的预估总价必须在用户选择出发日期后，通过产品服务报价接口计算。禁止继续使用产品起价 `startPrice` 或 `儿童数 * 0.7` 在前端估算。总价还必须包含后端按当日配置和成人数奇偶计算出的实际单房差。
 
 两个接口职责不同：
 
 | 接口 | 职责 |
 |---|---|
 | `GET /admin/product/item/{productId}/pricing-calendar` | 获取可售日期；日期选择器按 `sellable` 禁用不可售日期，同时保留该日价格/班期信息。 |
-| `POST /admin/product/item/{productId}/quote` | 按已选出发日期、档位及四类人数执行权威算价；预估总价直接展示响应 `grandTotal`。 |
+| `POST /admin/product/item/{productId}/quote` | 按已选出发日期、档位及四类人数执行权威算价，并处理单房差；预估总价直接展示响应 `grandTotal`。 |
 
 `quote` 后端会按产品类型读取正确价格源：CORE/CUSTOM 读取所选日期的 `product_price_calendar`，GROUP 读取所选日期的 `group_tour_batch`。前端不要复制价格日历计算规则。
 
@@ -25,7 +25,7 @@
 
 | 位置 | 当前行为 | 问题 |
 |---|---|---|
-| `src/views/order-v2/new/components/Step2Info.vue` | `startPrice * (adultCount + childCount * 0.7)` | 起价不是所选日期价格，儿童价也不是成人价的固定比例。 |
+| `src/views/order-v2/new/components/Step2Info.vue` | `startPrice * (adultCount + childCount * 0.7)` | 起价不是所选日期价格，儿童价也不是成人价的固定比例，且完全漏算单房差。 |
 | `src/views/order-v2/new/components/Step3Confirm.vue` | 再次使用相同本地公式 | 确认页会重复展示错误金额。 |
 | `src/api/product/pricing.js` | 已有统一价格日历方法，无管理端报价方法 | 新建订单流程没有调用现有报价接口。 |
 
@@ -92,21 +92,43 @@
 
 金额字段按字符串处理和展示，禁止先转 JS `Number` 后再长期保存。预估总价使用 `data.grandTotal`，不要由各单价在前端重新相加。
 
+### 单房差口径
+
+| 字段/条件 | 口径 |
+|---|---|
+| `singleRoomDiff` | 所选出发日期价格日历或 GROUP 班期配置的单房差原值。 |
+| `singleRoomSurcharge` | 本次报价实际收取的单房差。成人数为奇数（1、3、5……）且配置了单房差时，收取一份 `singleRoomDiff`；成人数为偶数时为 0。 |
+| `grandTotal` | 已包含 `singleRoomSurcharge`，前端禁止再把单房差加一次。 |
+| 人数范围 | 仅 `adultCount` 参与奇偶判断；儿童、小童、幼童不参与。 |
+
+测试环境同一产品、同一日期的实测结果：
+
+| 出发日期 | 人数 | 成人单价 | 单房差配置 | 实际单房差 | `grandTotal` |
+|---|---:|---:|---:|---:|---:|
+| `2026-06-30` | 1 成人 | `4000.00` | `1000.00` | `1000.00` | `5000.00` |
+| `2026-06-30` | 2 成人 | `4000.00` | `1000.00` | `0` | `8000.00` |
+
+前端预估价卡片和确认页都直接展示 `grandTotal`。当 `singleRoomSurcharge > 0` 时，增加一行金额明细“单房差 +¥xxx”；为 0 时可隐藏该行。该明细只用于解释总价，不能参与二次计算。
+
 ## 4. 前端处理要求
 
 1. 未选择出发日期时，预估总价显示“请选择出发日期”或“待计算”，不得展示基于起价的金额。
-2. 选择出发日期后调用 `quote`；产品、档位、出发日期、成人数、儿童数、小童数、幼童数任一变化，都要重新报价。
+2. 选择出发日期后调用 `quote`；产品、档位、出发日期、成人数、儿童数、小童数、幼童数任一变化，都要重新报价。成人数变化时必须重新获取 `singleRoomSurcharge`，不得仅在前端切换奇偶。
 3. 请求期间展示明确加载态；连续修改人数时做短防抖，并用请求序号或取消旧请求防止旧响应覆盖新结果。
 4. 报价失败时清空旧报价，不允许退回 `startPrice`/`0.7` 本地估算；展示后端错误信息并阻止带着过期报价进入确认页。
 5. 第 4 步确认页复用与当前输入完全匹配的最新报价；若报价依赖项已变化或无有效报价，进入确认页前重新调用一次。
 6. 删除 `Step2Info.vue` 和 `Step3Confirm.vue` 中 `childCount * 0.7` 及 `startPrice` 预估总价逻辑。
-7. `pricing-calendar` 仍用于可售日期限制，不要删除；`quote` 是其后的权威算价步骤。
+7. `grandTotal` 已含单房差；前端不得重复相加。`singleRoomSurcharge > 0` 时仅展示单房差明细。
+8. `pricing-calendar` 仍用于可售日期限制，不要删除；`quote` 是其后的权威算价步骤。
 
 ## 5. 验收清单
 
 - [ ] 未选出发日期时不展示金额，也不调用报价接口。
 - [ ] 选择 `2026-07-14`、`tierSeq=1`、2 成人 1 儿童后，样本产品预估总价显示 `11000.00`，不再显示 `10800.00`。
 - [ ] 成人/儿童/小童/幼童任一人数变化均重新报价，页面结果与最后一次请求一致。
+- [ ] 单房差配置为 `1000.00` 时，1 成人返回并显示 `singleRoomSurcharge=1000.00`、`grandTotal=5000.00`；2 成人返回 `singleRoomSurcharge=0`、`grandTotal=8000.00`。
+- [ ] 单房差只按成人数奇偶判断；儿童、小童、幼童数量变化不会被前端错误用于单房差判断。
+- [ ] 第 3 步和第 4 步在实际单房差大于 0 时显示单房差明细，但不会在 `grandTotal` 上再次累加。
 - [ ] 切换产品、档位或日期后，旧报价立即失效并重新获取。
 - [ ] CORE/CUSTOM 按所选日期价格日历算价；GROUP 携带所选班期 `batchId` 后报价正确。
 - [ ] 报价接口失败时不展示旧金额、不使用本地比例兜底。
@@ -117,4 +139,5 @@
 - 当前源码已确认 `POST /admin/product/item/{id}/quote` 为管理端正式报价接口。
 - Knife4j 测试环境聚合文档已确认该接口存在。
 - 2026-07-13 经测试环境网关实调：价格日历与报价接口均返回 `code=200`；上述样本 `grandTotal=11000.00`。
+- 2026-07-13 经测试环境网关补测单房差：`2026-06-30` 配置单房差 `1000.00`，1 成人报价 `singleRoomSurcharge=1000.00`、`grandTotal=5000.00`；2 成人报价 `singleRoomSurcharge=0`、`grandTotal=8000.00`。
 - 本通知只修改 `hl-api-changelog`，未修改 `hl-ui` 或后端业务代码。