From 1c59fb716a431caa938ebbd5eb53571de3b3b5b3 Mon Sep 17 00:00:00 2001
From: API Changelog Bot <changelog@hulalv.com>
Date: Fri, 2 Oct 2026 21:13:15 +0800
Subject: [PATCH] =?UTF-8?q?docs(changelog):=20#8735=20=E6=95=B4=E5=9B=A2?=
 =?UTF-8?q?=E7=A1=AE=E8=AE=A4=E8=AE=A2=E6=88=BF=E6=97=A0=E9=9C=80=E6=88=BF?=
 =?UTF-8?q?=E6=88=B7=E4=BD=86=E6=9C=89=E6=AE=8B=E7=95=99=E8=AE=A2=E6=88=BF?=
 =?UTF-8?q?=E8=AE=A1=E5=88=92=E6=94=B9=E4=B8=BA=E6=8B=92=E7=BB=9D=EF=BC=88?=
 =?UTF-8?q?808607=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 ...€æˆ¿æˆ·ä½†æœ‰æ®‹ç•™è®¢æˆ¿è®¡åˆ’改为拒ç»�-修改接å�£-管ç�†å�Žå�°.md | 208 ++++++++++++++++++
 1 file changed, 208 insertions(+)
 create mode 100644 changelogs-v2/2026-10/02_8735_整团确认订房无需房户但有残留订房计划改为拒�-修改接�-管���.md

diff --git a/changelogs-v2/2026-10/02_8735_整团确认订房无需房户但有残留订房计划改为拒�-修改接�-管���.md b/changelogs-v2/2026-10/02_8735_整团确认订房无需房户但有残留订房计划改为拒�-修改接�-管���.md
new file mode 100644
index 00000000..232cb357
--- /dev/null
+++ b/changelogs-v2/2026-10/02_8735_整团确认订房无需房户但有残留订房计划改为拒�-修改接�-管���.md
@@ -0,0 +1,208 @@
+---
+schema: hl-changelog/v2
+ticket: "8735"
+title: "整团确认订房：无需房户但有残留订房计划改为拒�，返回 808607"
+consumer: admin
+author: wx(GIT)
+change_type: 修改接�
+backend_status: deployed
+gateway_status: not_required
+frontend_status: pending
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: ""
+updated_at: "2026-10-02"
+base: dev-v3
+---
+
+# 整团确认订房：无需房户但有残留订房计划改为拒�，返回 808607
+
+## ⚠� 关键�化
+
+- **改�**：团期需房户数为 0 时，整团确认（`POST .../room-plans/confirm`）直接走「本团无需订房���，返回 200�`emptyDemand=true`�`hotelReady=true`。这一步**�检查**本团是�还有有效订房计划行。最常�的情形是唯一��酒店的户退团了，他那几晚已订的房还挂在团上。��之�，�没有任何环节会检查这些房。
+- **改�**：需房户数为 0�**且**本团�有有效订房计划行时，����，返回 `808607`（订房与需求�等），零写入。示例文案：`2028-03-05 的 STANDARD 订房 1 间 / 已确认需求 0 间（共 1 项�等，详�预检）`。
+- **出路**：对退团产生的转房行办�「退给酒店�（`cancel-hotel`），或删除该团残留的订房计划行。计划行清空��点整团确认，返回 200�`emptyDemand=true`。
+- **��**：
+  - 需房户数 > 0 时的�日等�校验；
+  - 全员客人自订（�户�晚都自订）的��；
+  - 既无需房户�也无订房计划行的团，照旧 200 放行。
+- **字段零�更**：请求��应结构都没改，�是多了一�会返回 `808607` 的情形。
+
+## 二��更接�清�
+
+| # | 接� | 方法 | 路径 | �更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 整团确认订房 | POST | `/v3/admin/house/group-batches/{groupBatchId}/room-plans/confirm` | 错误�触��件扩展 | 无需房户但�有订房计划行时返回 808607，����放行 |
+
+## 三�接�详情
+
+### 1. 整团确认订房 `POST /v3/admin/house/group-batches/{groupBatchId}/room-plans/confirm`
+
+**VO**: `GroupBatchRoomConfirmAllRespVO`
+
+#### 使用场景
+
+房务把一个团期�晚的订房计划填好�，点「整团确认�。接�先对整团�一次零写入预检：�个入�日按房型大类核对订房间数与已确认需求是�相等，并检查�晚订房�超过�期最大房间数。预检通过�，�日确认订房；全部完��置团期的�房完�标志。
+
+本次�改了一个情形：需房户数为 0 的团，过去一律按「无需订房�放行，现在先看它还有没有订房计划行。
+
+#### 入�
+
+本接�无请求体。
+
+| 字段 | �置 | 类型 | 必填 | 约� | 说明 |
+|------|------|------|------|------|------|
+| groupBatchId | Path | Long | 是 | 团期须存在且处于�确认阶段 | 团期主订� ID |
+
+#### 出�
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| groupBatchId | Long（�列化为字符串） | 团期主订� ID |
+| confirmedDates | `List<String>` | 本次确认的入�日 |
+| skippedDates | `List<String>` | 本次之�已全部确认�本次跳过的入�日 |
+| emptyDemand | Boolean | `true` 表示全团无需订房（无需房户且无订房计划行，或�户�晚都自订），已直接置�房完� |
+| doneOrderIds | `List<Long>`（元素�列化为字符串） | 本次累计被置为�房完�的�订� |
+| hotelReady | Boolean | 本次结��团期的�房完�标志 |
+| warnings | `List<GroupBatchRoomConfirmWarningVO>` | �日告警的并集，本次未改 |
+
+#### 请求示例
+
+```http
+POST /v3/admin/house/group-batches/2105995952810815490/room-plans/confirm
+```
+
+#### �应示例
+
+残留订房已�退给酒店�计划行清空之��确认（测试�实测）：
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "data": {
+    "groupBatchId": "2105995952810815490",
+    "confirmedDates": [],
+    "skippedDates": [],
+    "emptyDemand": true,
+    "doneOrderIds": [],
+    "hotelReady": true,
+    "warnings": []
+  },
+  "traceId": null,
+  "success": true
+}
+```
+
+#### 空数� / �级�应
+
+既无需房户�也无订房计划行的团（例如两户都�需��宿），返回与上例相�的结构：`emptyDemand=true`�`confirmedDates` 和 `skippedDates` 都为空数组�`hotelReady=true`。这一点与改�一致。
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "data": {
+    "groupBatchId": "2105996666916270081",
+    "confirmedDates": [],
+    "skippedDates": [],
+    "emptyDemand": true,
+    "doneOrderIds": [],
+    "hotelReady": true,
+    "warnings": []
+  },
+  "traceId": null,
+  "success": true
+}
+```
+
+#### 错误�应
+
+需房户为 0�但�有订房计划行（本次新增的触�情形，测试�实测）：
+
+```json
+{
+  "code": 808607,
+  "message": "2028-03-05 的 STANDARD 订房 1 间 / 已确认需求 0 间（共 1 项�等，详�预检）",
+  "data": null,
+  "traceId": null,
+  "success": false
+}
+```
+
+| code | 文案模� | 何时出现 | 本次�化 |
+|------|----------|----------|----------|
+| 808607 | `{入�日} 的 {房型大类} 订房 {N} 间 / 已确认需求 {M} 间（共 {K} 项�等，详�预检）` | �入�日订房与已确认需求�等，报第一个有差�的入�日 | **新增情形**：需房户为 0 且有订房计划行。需房户 > 0 时的原有情形�� |
+| 808610 | `入�日 {日期} 订房 {N} 间，超过�期最大房间数 {上�}` | �晚订房超过�期最大房间数，在�一天的等�校验之�检查 | 需房户为 0 的团过去直接���碰�到这�；现在残留订房超上�时会先报它 |
+| 808631 | `本团�有 {N} 户�宿需求未填全或未�在团期区间内，�能按「无需订房�置�房完�` | 预检判定「无需订房���写库�的�核：期间有户新增了需求 | �� |
+
+预检放�到写库之间存在一个窗�。如果这段时间里有人给这个团新建了订房计划行，写库�的�核�样返回 `808607`，�会放行。其余错误�（如团期阶段��许确认�无已确认基线）与改�相�，本次没改。
+
+#### 业务边界
+
+- �拒�「需房户为 0 且有有效订房计划行�这一�情形。需房户 > 0�全员自订�无需房户且无计划行，这三�情形的行为都与改�相�。
+- 拒�时零写入：�改计划行状�，�置�订��房完�，也�动团期的 `hotelReady`。
+- 想知�差在哪，先调预检 `GET /v3/admin/house/group-batches/{groupBatchId}/room-plans/confirm-check`。在这�团上，它返回 `ready=false`；对应入�日的 `days[].plannedTotal > 0`�`days[].demandedTotal = 0`；`days[].mismatch[]` �房型给出 `planned` / `demanded` / `diff`（`diff = 订房 − 需求`，正数表示多订）。
+- ⚠� **���凭预检的 `ready=false` �用「整团确认�按钮**。对既无需房户�也无计划行的团，预检返回 `ready=false`（`baselineExists=false`�`days=[]`），整团确认�会 200 放行（�上文「空数��）。这是两接�原有的�径差异，本次未改，测试�已实测。
+- 返回 `808607` 时 `data` 为 `null`，错误�应里没有 `confirmedDates` / `skippedDates` �读。�展示差�，以预检接�为准。
+
+## 四�契约约�与正确调用方�
+
+1. 点「整团确认��，�以先调 `confirm-check` 拿到 `days[].mismatch`。对需房户为 0 的团，若�天 `plannedTotal > 0`，就�示房务「该团已无需�宿的户，但�订有 N 间房，请先退给酒店或删除订房计划�。
+2. 收到 `808607` 时，原样展示 `message`，并引导房务回到预检看差�。这次拒��需��端回滚任何状�。
+3. 退给酒店走房务控制�已有接� `POST /v3/admin/order/house-console/room-transfers/{id}/cancel-hotel`，入� `proofFileIds` / `cancelFee` / `remark`，本次未改。
+
+## 五�数�库行为
+
+- 拒�（`808607` / `808610` / `808631`）时零写入：订房计划行��订��房完�状��团期�房完�标志都��调用�的值。
+- 放行时的写入与改�相�：�日确认订房计划，置�订�与团期的�房完�。
+
+## 六�边界行为
+
+- 判断「有没有订房计划行��看有效行。已�退给酒店�被整行收回的计划行�算。测试�实测：两�转房行��退给酒店之�，计划行被收回，�确认� 200。
+- 预检放�到写库之间新建的计划行，会在写库�的�核里被拦下（`808607`）。
+
+## 六.6�修改��对比
+
+| 情形 | 改� | 改� |
+|------|------|------|
+| 需房户 0，无订房计划行 | 200，`emptyDemand=true` | 200，`emptyDemand=true`（��） |
+| 需房户 0，有订房计划行 | 200，`emptyDemand=true`，残留订房无人检查 | `808607`（超�期上�时 `808610`），零写入 |
+| 需房户 > 0，订房与需求�等 | `808607` | `808607`（��） |
+| �户�晚都自订 | 200，`emptyDemand=true` | 200，`emptyDemand=true`（��） |
+
+## 六.7�影�评估
+
+- �端：�有当�端把「需房户为 0�的团一律当作�确认�并�此�示「确认�功�时��影�。按上文第四节处� `808607` ��；字段零�更，�改�会报错。
+- 数�：本次��移��回溯。改�已�按��放行��房完�为真的团，��原样。
+- 房务�作：残留订房必须先退给酒店或删除，�能整团确认。这一步是本次有�加上的。
+
+## 七��影�范围
+
+- 预检 `confirm-check` 的字段与判定未改。
+- �日确认�订房计划增删改�转房「退给酒店�等接�未改。
+- 无数�库结构�更，无网关路由�更。
+
+## 八�测试环境已验�
+
+测试� order-v3 已部署本次�交（`fac70310f7`），2026-10-02 走网关实测，数��为自建测试团：
+
+| 场景 | 结果 |
+|------|------|
+| 唯一需房户退团，留下 2 晚订房计划，整团确认 | `808607`「2028-03-05 的 STANDARD 订房 1 间 / 已确认需求 0 间（共 1 项�等，详�预检）�；预检 `ready=false`，两天都是 `plannedTotal=1`�`demandedTotal=0` |
+| 两户需房��一户确认了需求，订房 2 间 | `808607`「2028-03-19 的 STANDARD 订房 2 间 / 已确认需求 1 间（共 1 项�等，详�预检）�（原有情形，回归��） |
+| 上�第一个团的两�转房行��退给酒店之�，�整团确认 | 200，`emptyDemand=true`，`hotelReady=true` |
+| 两户从未�交�宿需求，无订房计划行 | 200，`emptyDemand=true`，`hotelReady=true`；预检 `ready=false`，`days=[]` |
+| 一户两晚全部自订��一户�需�宿 | 200，`emptyDemand=true`，`doneOrderIds` �自订户�订� |
+
+## ��相关文档
+
+- 预检接�：`GET /v3/admin/house/group-batches/{groupBatchId}/room-plans/confirm-check`（�应 `GroupBatchRoomConfirmCheckRespVO`），本次未改。
+
+## 关� / �系人
+
+- 工�：wx/HL#8735
+- �端 PR：wx/HL#8736（已�入 dev-v3）
+- �端�系人：wx