changelog(#5838): 用房需求每晚客户自订标记

changelogs-v2/2026-08/11_5838_用房需求每晚客户自订-修改接口-管理后台.md

@@ -0,0 +1,113 @@
+---
+schema: "hl-changelog/v2"
+ticket: "5838"
+title: "用房需求每晚支持「客户自订」：days[].customerSelfBooked + 错误码 582097/582098"
+consumer: "admin"
+change_type: "修改接口"
+author: "wx(GIT)"
+backend_status: "deployed"
+gateway_status: "not_required"
+frontend_status: "pending"
+frontend_owner: "mmg"
+frontend_ref: ""
+target_release: ""
+verified_at: "2026-08-11"
+status_note: ""
+updated_at: "2026-08-11"
+base: "dev-v3"
+---
+
+# 用房需求每晚支持「客户自订」（#5838）
+
+> **服务**: hl-order-service-v3
+> **PR**: #5872（已合并 dev-v3 并部署测试服）
+> **日期**: 2026-08-11
+> **背景**: 调整订单弹窗「酒店安排」里，某晚不选酒店只显示「未指定酒店」，语义是「留空由房控安排」。客人自己订了酒店的那晚没法表达，房务分不清「等我配」和「不用我配」。
+
+---
+
+## 变更接口
+
+### 1. 提交侧：`days[]` 新增 `customerSelfBooked`
+
+涉及 **提交用房需求** 与 **调整订单（hotelRequirement）** 两个入口（共用同一 `DayHotelReq` 结构）：
+
+```json
+"days": [
+  { "dayNumber": 1, "segments": [ ... ] },
+  { "dayNumber": 2, "customerSelfBooked": true, "segments": [] },   // 客人自己订，房务不用配
+  { "dayNumber": 3, "segments": [ ... ] }
+]
+```
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `customerSelfBooked` | `Boolean` | 整晚级。`true`=该晚客人自己订酒店、房务无需配房；`false`/不传=原有语义（要配） |
+
+**校验变化**：
+- `customerSelfBooked=true` 的晚 **允许 `segments` 为空**（也可只填备注，如「客人自订汉庭，勿重复订」）
+- 非自订晚 **仍必须至少 1 段**，否则返回 **`582098`**「第{N}晚缺少用房需求，请填写房间需求或标记为客户自订」
+
+> 注：该校验原是 bean 层 `@NotEmpty`（HTTP 422），因 bean 校验读不到同级 `customerSelfBooked` 无法条件化，已下沉 Service 改为业务错误码（项目 HTTP 恒 200 + 错误码口径）。**前端原本处理 422 的分支要改为处理 582098。**
+
+### 2. 新增错误码 `582097`：已配房的晚不能改成客户自订
+
+```
+582097  第{N}晚已配房，不能改为客户自订，请先删除该晚配房
+```
+
+**判定含「询房中」**（不只已确认）：询房中同样已占用房务人力、可能已向酒店发出询问。
+
+**为什么 fail closed**：该晚已产生配房行，可能已扣库存、已与酒店确认并产生成本。放行会让配房行变成没有需求对应的孤儿（房务侧看不到、也无从追责），库存也无人释放。要求定制师先显式删配房再改标记，让「谁在什么时候放弃了这间房」留下痕迹。
+
+### 3. 房务侧：`GET /admin/house/orders/{orderId}` 配房行程透出标记
+
+`itinerary[]`（配房行程 Tab）每晚新增：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `customerSelfBooked` | `Boolean` | 该晚是否客户自订 |
+
+同时该晚的 `arrangeLabel` 由「待配房」改为 **「客户自订」**。
+
+> 🔴 **机读字段 `arrange` 仍然是 `pending`，没有新增枚举值**。前端所有按 `arrange` 取值的既有分支**零改动**；要专门呈现自订晚，请读 `customerSelfBooked` 布尔字段。这是刻意为之，避免新增枚举值打挂既有渲染。
+
+### 4. 自订晚被排除出三处房务口径
+
+| 口径 | 变化 |
+|---|---|
+| 配房进度分母 `progress.totalCount` | 排除自订晚。3 晚含 1 晚自订 → 显示 **2/2** 而非 2/3（否则房务永远看到「差一晚」） |
+| `progress.unarrangedDayNumbers`（#5842 新增） | 排除自订晚。否则最终确认的二次确认弹窗会提示「第 2 晚未配房」——而那晚根本不用配 |
+| 配房日历「待配房」桶 | 排除自订晚。否则日历上会挂一个永远做不完的格子 |
+
+`unconfirmedDayNumbers` 由同一集合派生，一并受益。
+
+**抢单池与待办不受影响**（抢单池按需求维度、不迭代 days；带 dayNumber 的待办是「酒店回复超时」，由真实配房行驱动，自订晚没有配房行自然不产生）。
+
+---
+
+## 前端要做
+
+1. **调整订单弹窗「酒店安排」每晚增加「客户自订」开关/按钮**（wx 截图指定位置：该晚「+ 加候选酒店」旁）。打开后该晚的酒店/房型/预算区域可隐藏或置灰，备注仍可填。
+2. 提交时对自订晚传 `customerSelfBooked: true`，`segments` 可为空数组。
+3. **错误码处理**：
+   - `582098` → 提示该晚缺用房需求（原 422 分支改这里）
+   - `582097` → 提示"该晚已配房，请先删除配房再改为客户自订"
+4. **房务侧配房行程 Tab**：`customerSelfBooked=true` 的晚渲染为「客户自订」样式（后端 `arrangeLabel` 已给文案），与「待配房」在视觉上区分开——这是本需求的核心目的。
+
+---
+
+## 验证证据
+
+2026-08-11 测试服（网关 `https://api.test.1814.love:9443`，房务管理员 token）实测订单 26-0543：
+
+```
+itinerary[0].customerSelfBooked = false        ← 字段已贯通
+itinerary[0].arrange            = pending      ← 机读值未变
+itinerary[0].arrangeLabel       = 待配房        ← 非自订晚文案不变
+progress.unarrangedDayNumbers   = [1, 2]       ← 与实际未配房晚一致
+```
+
+单测：**双向变异验证**通过（①进度分母排除退回 `days.size()` → 对应用例失败；②读回侧 carry-through 置 null → 换版存活用例失败）。全量 6383 tests / 0 failures / 0 errors；BUILD FAILURE 系长跑尾部 fork 起不来（内存耗尽）导致 134 个类未跑、**其中含合并门禁 ArchTest**，已按包补跑 **1223 项全绿**（ArchTest 门禁 51 项）。
+
+> 补充：自订晚的端到端写操作（提交带标记的需求）未在真实订单上执行——提交会改动定制师的真实数据。相关行为由单测与变异验证覆盖。