diff --git a/changelogs-v2/2026-09/11_7325_团期房务按日订房确认H7-H8-预检-新增接口-管理后台.md b/changelogs-v2/2026-09/11_7325_团期房务按日订房确认H7-H8-预检-新增接口-管理后台.md new file mode 100644 index 00000000..51c45c46 --- /dev/null +++ b/changelogs-v2/2026-09/11_7325_团期房务按日订房确认H7-H8-预检-新增接口-管理后台.md @@ -0,0 +1,633 @@ +--- +schema: "hl-changelog/v2" +ticket: "7325" +title: "团期房务按日订房确认:3 个新端点(H7·H8·confirm-check);8 个新错误码;808616 删除;808602 日期上限改为 endDate-1" +consumer: "admin" +author: "wx(GIT)" +change_type: "新增接口" +backend_status: "deployed" +gateway_status: "verified" +frontend_status: "pending" +frontend_owner: "mmg" +frontend_ref: "" +target_release: "" +verified_at: "2026-09-11" +status_note: "2026-09-11 已部署测试服并经网关实测(squash dfd5a8f6f,PR #7497)。部署面只有 hl-order-service-v3 一个服务(两条独立路径核过:53 个改动文件全在该模块;对 hl-common / hl-gateway / 其它服务的命中数 = 0),未改 hl-common-*,无消费方需连带滚。Flyway V20260910_302 在测试库执行成功(flyway_schema_history 版本 20260910.302 success=1)。⚠️ 本篇起草时写错过一条并已更正:原写「GET /confirm-check 任何后台角色都能调」——不成立。读端点虽然不标 @HouseWriteGuarded、不走拦截器,但在编排层入口直接调 HouseReadGuard.assertHouseReadPermission()(GroupBatchRoomDayConfirmManager.java:489),非房务角色同样 808090。错因是只枚举了「注解+拦截器」一条机制就下了否定结论;2026-09-11 测试服实测(test_admin/CUSTOMIZER 打 GET 得 808090)与源码调用点双向坐实后已在「关键变化 1」更正。网关零改动:hl-gateway 自 2026-09-07 21:53 起未重启(jar mtime 与进程 lstart 两条路径核过),三个新端点均返回业务层响应而非路由未命中,证明既有 /v3/admin/** 通配已覆盖。⚠️ 尚未验证:H7/H8 真实确认业务逻辑未跑通——取证用的团期处于未认领态,POST 先撞 808612,需先造「整团抢单→提交需求→确认基线」数据链才能触达,本轮未做,如实标为未验证而不写「正常」。" +updated_at: "2026-09-11" +base: "dev-v3" +--- + +# 团期房务按日订房确认(H7·H8 + 只读预检) + +> **服务**: `hl-order-service-v3` +> **PR**: #7497 +> **Issue**: #7325 +> **日期**: 2026-09-11 +> **影响范围**: 管理后台房务团期页面新增「按日确认」与「整团确认」功能,及确认前的零副作用预检 + +--- + +## ⚠️ 关键变化 + +**#7325 是 #7324 房务团期看板(H1-H6)的后续交付,新增三个确认端点。三处易漏内容:** + +### 1. 三个端点都有角色门,`GET /confirm-check` 也不例外 + +两条门是**两套不同机制**,别只看注解: + +- 两个 POST:注解 `@HouseWriteGuarded` + 拦截器,在 `@Idempotent` 与 `@Lock4j` **之前**执行,非房务角色根本进不了幂等窗口; +- `GET /confirm-check`:**不走拦截器**,但在编排层入口直接调 + `HouseReadGuard.assertHouseReadPermission()`(`GroupBatchRoomDayConfirmManager.java:489`)——**一样会拒**。 + +| 角色 | 两个 POST 写口 | `GET /confirm-check` | +|---|---|---| +| `ROOM_MANAGER`(房务管理员)| 放行 | 放行 | +| `SUPER_ADMIN`(超管) | 放行 | 放行 | +| `house_keeper_lead`(房务组长) | **808091**(只读监督,不可写) | **放行** | +| 其它后台角色(定制师 / 运营 / 客服 / 财务 / 素材管理员) | **808090** | **808090** | + +🔴 **前端两个要点:** + +1. **房务组长看得到预检、点不了确认。** 按「能看见就能点」渲染,组长点确认会拿到 808091;该文案可直接展示。 +2. **非房务角色连预检都调不到**,返回的是 808090(业务码,HTTP 仍 200),**不是空数据**。别把 808090 渲染成「暂无差额」——那会让定制师以为团期没问题。 + +> ⚠️ **本条曾写错,2026-09-11 更正。** 起草时写的是「GET 任何后台角色都能调(不标 `@HouseWriteGuarded`)」。 +> 错因是**只枚举了「注解 + 拦截器」一条机制**就下了否定结论,没查到读门是**编排层直接调用**的第二套机制。 +> 测试服实测(`test_admin` / `CUSTOMIZER` 打 GET 得 808090)与源码调用点双向坐实后更正。 +> 读写两套门分开的理由写在 `HouseReadGuard` 的 javadoc 里:组长写门必须拒(808091)、读门必须放行, +> 否则组长连看板都打不开,监督无从谈起。 + +### 2. 808616 已删除,前端可移除兜底分支 + +`GB_ROOM_PLAN_CONFIRMED_REVISION_UNAVAILABLE`(808616)是 #7324 为「已确认行改删连锁尚未接入」留的占位码。#7325 实现了连锁能力,该码零调用、按 CODE_RULES「0 调用即删」随实现消失。前端若有该码兜底分支可以移除——它不会再返回。 + +### 3. 808602 日期上限改为 `endDate - 1`(右端开区间) + +入住日合法性校验:` stayDate ∈ [departDate, endDate)`。结束日是离店日、不产生间夜,所以 `stayDate == endDate` 判越界。前端日期选择器的可选上限应是 `endDate - 1`。 + +--- + +## 一、背景 + +`#7325` 交付两块能力补齐团期房务确认链路: + +1. **预检(零写入)**:`GET /confirm-check` 逐日展示订房间数 vs 已确认需求的差额表、阻塞名单(越界户/无基线户)、整团能否确认的判定。 +2. **按日确认**:`POST /days/{stayDate}/confirm` 单日确认订房,触发库存扣减、计划行翻已确认、分房重算、子订单完成标记。 +3. **整团确认**:`POST /confirm` 先整团预检(零写入),通过后按日期升序逐日执行,支持幂等重跑(已处理日跳过)。 + +三个端点都标 `@HouseWriteGuarded` 进行角色门控(H7·H8,#7324 的 H4-H6 已标)。只读预检额外不标该注解,让组长也能看到差额表做监督。 + +新增错误码 8 个落在 `HouseGroupBatchErrorCode` 的 808604-808610 / 808630 / 808631 / 808643 九段(注:先占号后实现,有占位有真实)。同时删除 808616,更新既有 589560 的参数含义。 + +--- + +## 二、变更接口清单 + +| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | +|---|---|---|---|---|---| +| 1 | 按日确认订房 | POST | `/v3/admin/house/group-batches/{groupBatchId}/room-plans/days/{stayDate}/confirm` | 新增接口 | 逐日执行,扣库存 + 翻态 + 重算分房 + 完成标记,返 3 个 ID 列表 + 警告 | +| 2 | 整团确认订房 | POST | `/v3/admin/house/group-batches/{groupBatchId}/room-plans/confirm` | 新增接口 | 先整团预检,再按日期升序逐日执行;支持幂等重跑与部分成功 | +| 3 | 订房确认预检 | GET | `/v3/admin/house/group-batches/{groupBatchId}/room-plans/confirm-check` | 新增接口 | 零副作用,返回逐日差额表、阻塞名单、整团能否确认;可选按单日过滤 | + +--- + +## 三、接口详情 + +### 1. 按日确认订房 `POST /v3/admin/house/group-batches/{groupBatchId}/room-plans/days/{stayDate}/confirm` + +**VO**: `无请求体 → GroupBatchRoomDayConfirmRespVO` + +#### 使用场景 + +房务在日历上逐日打开某日的确认弹窗,点击「确认本日订房」后调用该端点。服务端原子性地扣库存、翻计划行状态、重算该日分房并检查子订单完成标记,返回处理细节(本次确认了哪些行、之前就确认的哪些行、真正扣了库存的哪些行)与告警。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|---|---|---|---|---|---| +| `groupBatchId` | Path | Long | 是 | 雪花 ID | 团期主订单 ID | +| `stayDate` | Path | LocalDate(ISO) | 是 | yyyy-MM-dd 格式 | 入住日,须落在团期 `[departDate, endDate)` 内 | + +#### 出参字段表 `Result` + +| 字段 | 类型 | 说明 | +|---|---|---| +| `groupBatchId` | String(雪花 ID,`ToStringSerializer`) | 团期主订单 ID | +| `stayDate` | String | 入住日(yyyy-MM-dd) | +| `confirmedPlanIds` | `List`(元素 `ToStringSerializer`) | 本次由待确认(PENDING)翻成已确认(CONFIRMED)的计划行 ID | +| `skippedPlanIds` | `List` | 本次之前已确认的计划行 ID(未重复扣库存,已确认状态无变化) | +| `deductedPlanIds` | `List` | 本次真实扣减了库存的计划行 ID(`deduct_inventory=true` 且非幂等短路) | +| `allocationCount` | Integer | 本日 diff-apply 之后的 active 分房行数 | +| `doneOrderIds` | `List` | 本次被置为已完成(DONE)的子订单 ID | +| `hotelReady` | Boolean | 本次结束后团期的配房完成标志(全日全户已分房 ∧ 无阻塞) | +| `warnings` | `List` | 告警清单(确认已成功,但有事实需关注) | + +**GroupBatchRoomConfirmWarningVO** 结构: + +| 字段 | 类型 | 说明 | +|---|---|---| +| `code` | String | 告警码,可能值:`BASELINE_INACTIVE`(该户待新版需求确认)、`DAY_OUT_OF_RANGE`(该户某晚越界)、`MANUAL_OVERFLOW`(人工分房超出边界)、`ALLOC_SHORTAGE`(该户该房型缺房)、`ALLOC_LEFTOVER`(计划行有房未分)、`ALLOC_SPLIT_HOTEL`(该户被分到多家酒店) | +| `orderId` | Long(可空,`ToStringSerializer`) | 相关子订单 ID,无具体户时为空 | +| `message` | String | 面向房务的说明文案 | + +#### 请求示例 + +```http +POST /v3/admin/house/group-batches/20260610001/room-plans/days/2026-06-12/confirm +``` + +#### 响应示例 + +```json +{ + "code": 200, + "success": true, + "data": { + "groupBatchId": "20260610001", + "stayDate": "2026-06-12", + "confirmedPlanIds": ["500001", "500002"], + "skippedPlanIds": [], + "deductedPlanIds": ["500001", "500002"], + "allocationCount": 3, + "doneOrderIds": ["900001"], + "hotelReady": false, + "warnings": [ + { + "code": "BASELINE_INACTIVE", + "orderId": "900002", + "message": "订单900002有新版本需求待管理员确认,该户未置为已完成" + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +- 无空态:入参是团期 ID + 日期,必有对应团期则有响应。若该日零计划行或全已确认(幂等重跑),三个 ID 列表可能为空。 + +#### 错误响应 + +```json +{ "code": 808602, "message": "入住日 2026-06-15 不在团期出行区间内", "success": false } +{ "code": 808604, "message": "订房计划行已被确认或版本已变化,请刷新后重试", "success": false } +{ "code": 808605, "message": "酒店 示例酒店 房型 标间 库存不足(需 5 间),请调整订房计划或更换房型", "success": false } +{ "code": 808607, "message": "示例酒店 的 标间 订房 3 间 / 已确认需求 5 间(共 2 项不等,详见预检)", "success": false } +{ "code": 808609, "message": "入住日 2026-06-12 没有可确认的订房计划", "success": false } +{ "code": 808610, "message": "入住日 2026-06-12 订房 35 间,超过班期最大房间数 30", "success": false } +{ "code": 808630, "message": "团期确认采用预占失败(酒店 示例酒店 房型 标间),请稍后重试或等待对账任务收口", "success": false } +{ "code": 808643, "message": "该团有 2 户的分房已过时(首个订单 ORD202606120001),请先重算分房后再确认", "success": false } +{ "code": 808090, "message": "无权操作(仅房务角色可操作)", "success": false } +{ "code": 808091, "message": "无权操作(仅房务管理员或超管可操作)", "success": false } +``` + +#### 业务边界 + +- **幂等窗口**:按「团期 ID + 入住日」组合,3 秒租约。同日多次提交返回「处理中」。 +- **已发生间夜冻结**:该日入住日早于操作当日且计划行状态已为 CONFIRMED 时,整个团期状态必须是 `TRAVELLING`/`TRIP_FINISHED`/`REVIEWING`/`CANCELLED` 之一,否则 808690。 +- **部分成功回滚**:若某行扣库存失败(808605),本次已扣成功的行必须逐条归还,整事务回滚、零副作用。 + + +--- + +### 2. 整团确认订房 `POST /v3/admin/house/group-batches/{groupBatchId}/room-plans/confirm` + +**VO**: `无请求体 → GroupBatchRoomConfirmAllRespVO` + +#### 使用场景 + +房务打开整团视图,点击「整团确认订房」,服务端先做整团预检(零写入),检查所有可执行日(非越界日)是否等量 + 不超班期 + 有基线;预检通过后按日期升序逐日执行,支持幂等重跑(已处理日自动跳过)。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|---|---|---|---|---|---| +| `groupBatchId` | Path | Long | 是 | 雪花 ID | 团期主订单 ID | + +#### 出参字段表 `Result` + +| 字段 | 类型 | 说明 | +|---|---|---| +| `groupBatchId` | String(雪花 ID,`ToStringSerializer`) | 团期主订单 ID | +| `confirmedDates` | `List` | 本次新确认的入住日列表(yyyy-MM-dd);前 k−1 日成功后第 k 日失败时只返前 k−1 日,重跑会跳过 | +| `skippedDates` | `List` | 本次之前已全部确认的入住日(幂等重跑时返回) | +| `emptyDemand` | Boolean | `true` 表示全团无需房户或每户每晚都自订,已直接置配房完成;`false` 表示有需房户需逐日确认 | +| `doneOrderIds` | `List`(元素 `ToStringSerializer`) | 本次累计被置为已完成的子订单 ID | +| `hotelReady` | Boolean | 本次结束后团期的配房完成标志 | +| `warnings` | `List` | 逐日告警并集 | + +#### 请求示例 + +```http +POST /v3/admin/house/group-batches/20260610001/room-plans/confirm +``` + +#### 响应示例(正常确认) + +```json +{ + "code": 200, + "success": true, + "data": { + "groupBatchId": "20260610001", + "confirmedDates": ["2026-06-12", "2026-06-13"], + "skippedDates": [], + "emptyDemand": false, + "doneOrderIds": ["900001", "900002"], + "hotelReady": true, + "warnings": [] + } +} +``` + +#### 响应示例(全团无需订房豁免出口) + +```json +{ + "code": 200, + "success": true, + "data": { + "groupBatchId": "20260610001", + "confirmedDates": [], + "skippedDates": [], + "emptyDemand": true, + "doneOrderIds": [], + "hotelReady": true, + "warnings": [] + } +} +``` + +#### 空数据 / 降级响应 + +- 全团无需房或每户自订时直接返 `emptyDemand=true`,不再逐日处理。 +- 第 k 日失败时已确认的日期在 `confirmedDates`,未处理的日期不返回(不是返回空,而是整体返回成功日期 + 错误响应)。 + +#### 错误响应 + +```json +{ "code": 808607, "message": "示例酒店 的 标间 订房 3 间 / 已确认需求 5 间(共 2 项不等,详见预检)", "success": false } +{ "code": 808610, "message": "入住日 2026-06-12 订房 35 间,超过班期最大房间数 30", "success": false } +{ "code": 808631, "message": "本团仍有 3 户住宿需求未填全或未落在团期区间内,不能按「无需订房」置配房完成", "success": false } +{ "code": 808090, "message": "无权操作(仅房务角色可操作)", "success": false } +{ "code": 808091, "message": "无权操作(仅房务管理员或超管可操作)", "success": false } +``` + +#### 业务边界 + +- **幂等窗口**:按「团期 ID + 'ALL'」组合,3 秒租约。 +- **两步预检**:第一步全局检查(有基线、阶段允许);第二步逐日检查(每日等量 + 不超班期)。全通过才进执行。 +- **豁免出口**:全团无需房或每户自订时直接置 `hotelReady=true`,跳过逐日等量校验与越界户一票否决。 +- **部分成功**:若第 k 日失败,前 k−1 日已确认状态保留、不回滚,`confirmedDates` 只返前 k−1 日,重跑会自动跳过。 + + +--- + +### 3. 订房确认预检 `GET /v3/admin/house/group-batches/{groupBatchId}/room-plans/confirm-check` + +**VO**: `GroupBatchRoomConfirmCheckReqVO(GET 直接绑定) → GroupBatchRoomConfirmCheckRespVO` + +#### 使用场景 + +在确认前查看「哪一天哪个房型差几间」的完整差额表,以及阻塞名单(越界户/无基线户)。支持按单日过滤,也支持不传日期查看有需求或有计划行的全部日。**零副作用,但同样有角色门**——非房务角色返 808090,房务组长放行(见「关键变化 1」)。 + +#### 入参字段表 + +`GroupBatchRoomConfirmCheckReqVO`(GET 参数直接绑定): + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|---|---|---|---|---|---| +| `groupBatchId` | Path | Long | 是 | 雪花 ID | 团期主订单 ID | +| `stayDate` | Query | LocalDate(ISO) | 否 | yyyy-MM-dd;不传则返回「有需求或有计划行」的全部日 | 仅查看某一天的差额;确认弹窗按日打开时传,看板整团预检时不传 | + +#### 出参字段表 `Result` + +| 字段 | 类型 | 说明 | +|---|---|---| +| `groupBatchId` | String(雪花 ID,`ToStringSerializer`) | 团期主订单 ID | +| `batchStatus` | String | 团期主状态(如 `TRAVELLING`) | +| `stageAllowed` | Boolean | 团期阶段是否允许确认(`REVIEWING`/`RECRUITING`/`SETTLED`/`CANCELLED` 不允许) | +| `baselineExists` | Boolean | 是否存在任一户已确认的需求基线 | +| `hotelReady` | Boolean | 当前配房完成标志 | +| `maxRooms` | Integer | 班期最大房间数(`null` 或 `0` 表示不限) | +| `ready` | Boolean | 整团是否可确认(全部可执行日都等量 ∧ 阶段允许 ∧ 有基线);**注:`ready=true` 不等于配房完成标志能置上**(还需无阻塞) | +| `blockedByOutOfRange` | Boolean | 是否被越界户/无基线户阻塞(房务自己解决不了,需团期管理员改期/重新确认需求/置为不需配房) | +| `days` | `List` | 逐日预检 | +| `noBaselineOrders` | `List` | 需房但无已确认基线的户 | +| `outOfRangeOrders` | `List` | 越界或出发日缺失的户(阻塞名单,不是剔除名单) | + +**DayCheck** 子结构(逐日明细): + +| 字段 | 类型 | 说明 | +|---|---|---| +| `stayDate` | String(yyyy-MM-dd) | 入住日 | +| `planStatus` | String | 该日计划行状态:`NONE`(无计划)/ `PENDING`(全待确认)/ `PARTIAL`(混合)/ `CONFIRMED`(全已确认) | +| `plannedTotal` | Integer | 该日订房总间数 | +| `demandedTotal` | Integer | 该日已确认需求总间数 | +| `exceedsMaxRooms` | Boolean | 该日订房总数是否超过班期最大房间数 | +| `demand` | `Map` | 该日各房型大类的需求间数(键=房型大类,值=间数);含越界户落在本格的需求 | +| `mismatch` | `List` | 逐房型大类的差额(仅列 `diff≠0` 的行) | +| `stale` | Boolean | 该日存在的分房记录基线与当前基线不一致(基线被重新确认过) | +| `dayReady` | Boolean | 该日是否就绪(等量 ∧ 不超班期);越界日恒为 `false` | +| `outOfBatchRange` | Boolean | 该日落在团期区间之外(越界户那一格,订不了也确认不了) | + +**CategoryMismatch** 子结构(某日某房型的差额): + +| 字段 | 类型 | 说明 | +|---|---|---| +| `roomCategory` | String | 房型大类(如 `STANDARD`) | +| `planned` | Integer | 订房间数 | +| `demanded` | Integer | 已确认需求间数 | +| `diff` | Integer | 差额 = 订房 − 需求;正数多订、负数少订 | + +**NoBaselineOrder** 子结构(无基线户): + +| 字段 | 类型 | 说明 | +|---|---|---| +| `orderId` | Long(`ToStringSerializer`) | 子订单 ID | +| `orderNo` | String | 订单号 | +| `reason` | String | 原因:`NOT_SUBMITTED`(未提过)/ `PENDING_REVIEW`(待确认)/ `REJECTED`(被打回) | + +**OutOfRangeOrder** 子结构(越界或日期缺失户): + +| 字段 | 类型 | 说明 | +|---|---|---| +| `orderId` | Long(`ToStringSerializer`) | 子订单 ID | +| `orderNo` | String | 订单号 | +| `departDate` | String(可空,yyyy-MM-dd) | 该户出发日(缺失为空) | +| `reason` | String | 原因:`OUT_OF_RANGE`(出发日外)/ `DATE_MISSING`(缺失日期) | + +#### 请求示例 + +```http +GET /v3/admin/house/group-batches/20260610001/room-plans/confirm-check +GET /v3/admin/house/group-batches/20260610001/room-plans/confirm-check?stayDate=2026-06-12 +``` + +#### 响应示例(有需求不等量) + +```json +{ + "code": 200, + "success": true, + "data": { + "groupBatchId": "20260610001", + "batchStatus": "TRAVELLING", + "stageAllowed": true, + "baselineExists": true, + "hotelReady": false, + "maxRooms": 30, + "ready": false, + "blockedByOutOfRange": false, + "days": [ + { + "stayDate": "2026-06-12", + "planStatus": "PENDING", + "plannedTotal": 3, + "demandedTotal": 5, + "exceedsMaxRooms": false, + "demand": { "STANDARD": 5 }, + "mismatch": [ + { + "roomCategory": "STANDARD", + "planned": 3, + "demanded": 5, + "diff": -2 + } + ], + "stale": false, + "dayReady": false, + "outOfBatchRange": false + } + ], + "noBaselineOrders": [], + "outOfRangeOrders": [] + } +} +``` + +#### 响应示例(被越界户阻塞) + +```json +{ + "code": 200, + "success": true, + "data": { + "groupBatchId": "20260610001", + "batchStatus": "TRAVELLING", + "stageAllowed": true, + "baselineExists": true, + "hotelReady": false, + "maxRooms": null, + "ready": false, + "blockedByOutOfRange": true, + "days": [], + "noBaselineOrders": [], + "outOfRangeOrders": [ + { + "orderId": "900003", + "orderNo": "ORD202606120003", + "departDate": "2026-06-08", + "reason": "OUT_OF_RANGE" + } + ] + } +} +``` + +#### 空数据 / 降级响应 + +- `days[]` / `noBaselineOrders[]` / `outOfRangeOrders[]` 均可为空数组(团尚无需求提交或全部已就绪)。 +- 单日查询(传了 `stayDate`)时,若查询日不在「有需求或有计划行」的日期范围内,`days` 返回空数组。 + +#### 错误响应 + +```json +{ "code": 589500, "message": "团期不存在", "success": false } +``` + +#### 业务边界 + +- **零副作用**:不更新任何状态,不消耗幂等令牌,即便并发调用也互不影响。 +- **阶段允许**:`RECRUITING` / `REVIEWING` / `SETTLED` / `CANCELLED` 团期返 `stageAllowed=false`,但预检仍继续返回差额表(前端可用于诊断)。 +- **与整团确认的异同**: + - 相同:都检查阶段、基线、等量、班期上限、阻塞情况。 + - 不同:预检只读不扣库存,整团确认还会顺手补检「豁免出口」(全团无需房时直接置完成)。 + + +--- + +## 四、契约约束与正确调用方式 + +### ✅ 正确 / ❌ 错误调用顺序 + +| 场景 | 调用顺序 | +|---|---| +| ✅ 逐日确认工作流 | 先调 `GET /confirm-check` 查看差额表 → 房务调整订房 → 再调 `POST /days/{stayDate}/confirm` 逐日确认 | +| ✅ 整团一键确认 | 先调 `GET /confirm-check` 检查整团是否 `ready=true` → 再调 `POST /confirm` 一并执行 | +| ✅ 幂等重跑 | 整团确认失败后(第 k 日失败),修复第 k 日问题 → 再调 `POST /confirm` 一次,前 k−1 日自动跳过 | +| ❌ 不看差额直接调用 POST | 房务无法预知会因 808607 / 808610 失败,应先看 confirm-check | +| ❌ 用旧的 `ready` 状态去执行 | 预检与执行之间可能有新的需求确认或订房改动,不能信时间轴之外的 `ready`;前端应在执行前再确认一遍 | + +### 角色与权限拦截顺序 + +| 步骤 | 拦截点 | 返回码 | +|---|---|---| +| 1 | `@HouseWriteGuarded` 检查(两个 POST 才有) | 808090(非房务)/ 808091(组长只读) | +| 2 | `@Idempotent` 幂等窗(三个端点都有) | 「处理中」文案 | +| 3 | 业务逻辑 | 808602 / 808604 / 808605 / 等 | + +非房务角色在第 1 步就被挡下、压根进不了幂等窗口。 + +--- + +## 五、数据库行为 + +| 操作 | `group_batch_room_plan` 表 | `group_batch_room_allocation` 表 | `group_batch` 表 | +|---|---|---|---| +| `POST /days/{stayDate}/confirm` 成功 | 匹配行 `plan_status` 改为 `CONFIRMED`;`version` 不变 | 逐日 diff-apply 生成新分房或调整存量分房(若自动分房上线) | 可能改 `hotel_ready=true`(全日全户已分房 ∧ 无阻塞) | +| `POST /confirm` 成功 | 全部匹配行 `plan_status` 改为 `CONFIRMED` | 逐日全量重算分房 | 最终置 `hotel_ready=true` 或保持 `false`(有阻塞) | +| `GET /confirm-check` 成功 | 无变化 | 无变化 | 无变化 | +| 库存扣减 | 在按日确认时按幂等键 `gbrp-{planId}-v{version}` 与 Feign 到 resource 扣库存(成功后落 `group_batch_room_plan_deduct_log`) | — | — | + +--- + +## 六、边界行为 + +- **并发确认**:多个房务同时确认不同日期,由团期级 `@Lock4j` 序列化(30 秒租约)。 +- **已发生间夜**:确认端点对已发生的间夜(`stayDate < today` ∧ `plan_status = CONFIRMED`)逐行返 808690,直接拒不执行。 +- **阶段限制**:`RECRUITING` / `REVIEWING` / `SETTLED` / `CANCELLED` 团期调确认端点返 808600;预检仍然可调(只读)。 +- **部分成功回滚**:某行失败时已扣的库存必须同事务归还(`afterCommit` 不执行),确保「计划行状态 vs 库存持有 log」对账平衡。 + +--- + +## 六.5、枚举 / 数据字典 + +### 计划行状态(GroupBatchRoomPlanDO.planStatus) + +**所属字段**: `days[].planStatus` 及 `GroupBatchRoomPlanRespVO.planStatus` | **类型**: `String` + +| 值 | 中文 | 说明 | +|----|------|------| +| `NONE` | 无 | 该日没有计划行 | +| `PENDING` | 待确认 | 该日全部计划行状态都是 `PENDING` | +| `PARTIAL` | 混合 | 该日既有 `PENDING` 也有 `CONFIRMED` 计划行 | +| `CONFIRMED` | 已确认 | 该日全部计划行状态都是 `CONFIRMED` | + +### 告警码(GroupBatchRoomConfirmWarningVO.code) + +**所属字段**: `GroupBatchRoomDayConfirmRespVO.warnings[].code` 及 `GroupBatchRoomConfirmAllRespVO.warnings[].code` | **类型**: `String` + +| 值 | 中文 | 说明 | +|----|------|------| +| `BASELINE_INACTIVE` | 待新版需求确认 | 该户有新版本需求待管理员确认,本次未置为已完成 | +| `DAY_OUT_OF_RANGE` | 越界告警 | 该户某晚换算后落在团期区间外;需求已计入分母、该户进阻塞名单,整团配房完成置不上 | +| `MANUAL_OVERFLOW` | 人工分房超出 | 人工分房行超出计划行间数或该户需求,本次未自动调整 | +| `ALLOC_SHORTAGE` | 缺房告警 | 该户该房型还欠房;首次确认不会出现,它来自重确认 / 人工微调 / 改删连锁重算 | +| `ALLOC_LEFTOVER` | 多房告警 | 该计划行还有房没分出去(订了但没人住) | +| `ALLOC_SPLIT_HOTEL` | 跨酒店分房 | 该户同一晚被分到了不止一家酒店(算法精确匹配房型大类、不看酒店) | + +### 无基线原因(GroupBatchRoomConfirmCheckRespVO.noBaselineOrders[].reason) + +**所属字段**: `noBaselineOrders[].reason` | **类型**: `String` + +| 值 | 中文 | 说明 | +|----|------|------| +| `NOT_SUBMITTED` | 未提交 | 该户从未提交过需求 | +| `PENDING_REVIEW` | 待确认 | 提过但最新版本待管理员确认 | +| `REJECTED` | 被打回 | 最新版本被打回,无有效基线 | + +### 越界原因(GroupBatchRoomConfirmCheckRespVO.outOfRangeOrders[].reason) + +**所属字段**: `outOfRangeOrders[].reason` | **类型**: `String` + +| 值 | 中文 | 说明 | +|----|------|------| +| `OUT_OF_RANGE` | 出发日外 | 该户出发日落在团期 `[departDate, endDate)` 之外 | +| `DATE_MISSING` | 日期缺失 | 该户出发日为空,无法判定是否在团期内 | + +--- + +## 七、不影响范围 + +- **仅影响**: 管理后台房务团期页面的确认弹窗与看板视图 +- **零影响**: + - C 端行程相关接口 + - 订单创建、详情查看 + - 既有配房、退改、核单流程 + - 其他后台模块 + +--- + +## 八、测试环境已验证 + +**部署**:2026-09-11 10:12:31 部署 `hl-order-service-v3` 到测试服(`dev-v3` @ `dfd5a8f6f`,双实例滚动)。 + +| 验的是什么 | 证据 | +|---|---| +| 进程 | `LISTEN *:8086`、`LISTEN *:8186` 两实例 | +| Nacos | 两实例 `"healthy":true,"enabled":true` | +| 跑的确是 `dfd5a8f6f` | **两条独立路径**:①服务器 `git rev-parse HEAD` = `dfd5a8f6ffb0e768548e787fe1b8cb276ccf86fc`;②jar mtime `10:12:31` 与 `.deployed` 登记一致,两实例 lstart 均晚于 jar mtime | +| Flyway | `flyway_schema_history` 版本 `20260910.302` `success=1`(10:12:38);`SHOW COLUMNS` 列序为 `order_id → hotel_id → room_type_id → room_count`,与 `AFTER` 定义相符 | +| 启动异常 | 两实例日志 `ERROR|Exception` 计数均为 **0** | + +**网关实测**(走网关,非直连服务端口): + +| 端点 | 角色 | 业务码 | 说明 | +|---|---|---|---| +| `GET /confirm-check` | `house_keeper_lead` | 200 | 正常返回预检体(`baselineExists:false` / `ready:false` / `noBaselineOrders[].reason=NOT_SUBMITTED`) | +| `GET /confirm-check` | `CUSTOMIZER` | **808090** | 读门生效(更正了本篇起草时的错误口径) | +| `GET /confirm-check` | `ROOM_MANAGER`(非该团认领人) | 808612 | 团未被认领 | +| `POST /days/{stayDate}/confirm` | `CUSTOMIZER` | **808090** | — | +| `POST /days/{stayDate}/confirm` | `house_keeper_lead` | **808091** | 只读监督角色 | +| `POST /confirm` | `CUSTOMIZER` | **808090** | — | +| `POST /confirm` | `house_keeper_lead` | **808091** | — | + +三个端点全部返回**业务层响应**而非网关路由未命中,证明既有 `/v3/admin/**` 通配已覆盖新路径。 +网关零改动另有独立证据:`hl-gateway` 自 2026-09-07 21:53 起未重启(jar mtime 与进程 lstart 两条路径核过),与本次改动无交集。 + +被拒的两次 POST **零副作用**已用 DB 复核:`group_batch_room_plan` 该团行数 = 0,`order_group_batch.update_time` 未变。 + +**单元测试**:合并前全量 `Tests run: 9925, Failures: 0, Errors: 0, Skipped: 7`,BUILD SUCCESS。 + +**Flyway 迁移验证**:新增 `GroupBatchRoomAllocationFlywayMySqlIT` 在真实 MySQL 8.0.33 容器上验过 `V20260910_302` 含存量行的 `ALTER`(先插一行存量再跑迁移,断言两列 NOT NULL 回填 0 且落在 `order_id` 之后,2 个用例绿)。 + +> 🔴 **尚未验证,如实标注**:**H7 / H8 的真实确认业务逻辑没有跑通。** +> 取证用的团期处于「未被房务认领」态,POST 先撞 808612 就返回了,触达不到确认逻辑本身。 +> 要跑通需要先造「整团抢单 → 提交需求 → 管理员确认基线」这条数据链路,本轮没做—— +> 所以本节证明的是**可达性 + 鉴权 + 迁移 + 启动**,**不是** H7/H8 的业务正确性。 +> 后者目前只有单测覆盖。前端联调时若遇到与预期不符的确认行为,请直接反馈,不要假定后端已实测过。 + +**单元测试**: 合并前全量 `Tests run: 9925, Failures: 0, Errors: 0, Skipped: 7`,BUILD SUCCESS。 + +**Flyway 迁移验证**: 新增 `GroupBatchRoomAllocationFlywayMySqlIT` 在真实 MySQL 8.0.33 容器上验过 `V20260910_302` 含存量行的 `ALTER TABLE group_batch_room_allocation ADD COLUMN hotel_id / room_type_id`(2 个用例绿)。 + +--- + +## 九、相关历史 PR + +| PR | Issue | 说明 | 是否仍有效 | +|----|-------|------|------------| +| #7465 | #7324 | 房务团期看板 H1-H6 + 整团释放(前一期确认前置工作) | ✅ 有效 | +| **本 PR #xxxx** | **#7325** | 按日确认 H7 + 整团确认 H8 + 只读预检 | ✅ 最新 | + +--- + +## 十、相关文档 + +- **后续计划**: 分房与微调(#7326 H9-H11,定案中),按日确认分房重算全景(#7327 巡检) +- **错误码管理**: 见 `HouseGroupBatchErrorCode.java` 文档注释,段位 808600-808699,本单占 808604-808610 / 808630 / 808631 / 808643 + +--- + +## 关联 / 联系人 + +### 链接 + +- **Issue**: [#7325](https://git.1814.love:8443/wx/HL/issues/7325) +- **PR**: [#xxxx](https://git.1814.love:8443/wx/HL/pulls/xxxx) +- **Merge commit**: (合并后回填) + +### 联系人 + +- **后端负责人**: @wx