docs(7445,7446): 两份交接件补网关实测结果，gateway_status 转 verified Refs #7445 Refs #7446

两单的 §八「测试环境已验证」原先都写着「本节当前为空，网关实测尚未进行」， frontmatter 的 gateway_status 卡在 pending、pre-push 校验器报 E_GATEWAY_PENDING。 2026-09-11 网关实测已完成，本次把结果写进两份交接件： - #7445 四组（17:38 三组 + 18:36 补一组）：团期单 + 用车 PENDING → 584131；推 DONE → 200；散客单两类需求都 PENDING → 200（两闸均不误触发）；车费派生行全部软删 + 需求 PROCESSING → 仍 584131 - #7446 四组：方向甲 + 住宿 PENDING → 584130；推 DONE → 200；待回填老单（product 非空 + group 为空 + 团期存活）→ 仍 584130；散客单 → 200 两份都如实写明了两条取证边界，不许读的人误推： 1. 全部前置都是 SQL 直更造出来的（直接改需求 status），不是走真实配车/配房链路产生的 2. 取证路上绕过了三道与本单无关的通用前置闸（584310 八分类未确认、584082 待收尾款、车费草稿冻结确认），手段是 SQL 标 CONFIRMED / 清零应收；这三道闸自身的正确性未被验证 gateway_status pending→verified、verified_at 填 2026-09-11、status_note 改为如实描述。 frontend_status 保持 pending 未动。
2026-09-11 18:58:29 +08:00
@@ -0,0 +1,379 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7445"
+title: "整单核单 finalize 新增团期用车户级闸门（新增错误码 584131，warnings 新增 VEHICLE 取值）"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: "2026-09-11"
+status_note: "gateway_status=verified：2026-09-11 网关实测已完成（17:38 批次 + 18:36 补测批次，详见“八、测试环境已验证”），经 hl-gateway 网关调用 POST /v3/admin/order/{orderId}/settlement/finalize 验证 584131 硬阻断与放行两个分支。所有前置条件均为 SQL 直更需求表状态构造，非真实业务链路（配车）产生；另绕过与本单无关的 584310/584082/车费草稿冻结确认三道通用前置闸，其正确性未验证。"
+updated_at: "2026-09-11"
+base: "dev-v3"
+---
+
+# order-v3: 整单核单 finalize 新增团期用车户级闸门
+
+> **服务**: hl-order-service-v3
+> **PR**: #7499
+> **Issue**: #7445
+> **日期**: 2026-09-11
+> **影响范围**: 既有端点 `POST /v3/admin/order/{orderId}/settlement/finalize`（完成核单）新增一道团期子订单用车户级校验；新增业务错误码 584131；成功响应 `warnings[]` 新增 `category=VEHICLE` 取值。请求体（无）、方法、路径、网关路由均未改。
+
+---
+
+## ⚠️ 关键变化
+
+本次改动是什么：团期子订单在 finalize（完成核单）时，新增一道"该户用车是否已安排完成"的硬阻断校验——用车需求存在但状态不是 DONE 时，finalize 返回业务错误码 584131（HTTP 恒 200，按 code 判断）。这是 #7347（团期住宿户级闸门，584130）在车侧的对称件，判定入口是新增私有方法 SettlementService.assertGroupVehicleReadyForFinalize，排在住宿闸（584130）之后、CASH_PAID 软预警之前——若住宿与用车同时未就绪，先返 584130，不会同时返回两个码。
+
+前端以前不知道的事，现在必须知道：
+
+1. 成功响应体 warnings[] 数组新增一种元素：category="VEHICLE"。这类预警项的 settlementId 与 dayNumber 恒为 null——与既有 HOTEL/TICKET 预警（这两者的 settlementId/dayNumber 恒非空）不同，前端若假设 warnings[] 每项都能按 settlementId 定位到某一行明细，会在这类新预警上取到 null 而出错。
+2. VEHICLE 预警不阻塞提交——它是"该团期子订单压根没提交过用车需求"这一种情形下的软提示（wx 2026-09-10 拍板的已知敞口，D-2 定案 A），finalize 仍会成功。这与 584131 硬阻断是两回事：同一订单不会同时出现 584131 报错和 VEHICLE 预警，二者互斥（有 active 需求行才可能触发 584131，没有需求行才触发预警）。
+3. 该软预警是过渡态：待 #7441 交付 vehicleWaived 后，其 D-C26 ② 会把这条分支从软预警升级为硬阻断（584131），届时 warnings[] 里不会再出现这条 VEHICLE 缺行提示。前端不要把这个取值当长期契约来做长期兼容设计。
+
+---
+
+## 一、背景
+
+SettlementService.performSubmitBlockingChecks（finalize 事务内的阻断检查方法）此前对住宿有户级闸门（#7347，584130），但用车没有——通用品类门禁 SettlementCategoryCheckService.validateReadyForReport 对 VEHICLE 品类的校验条件是 rowCount() > 0 且 !lineItemsConfirmed()，零车费派生行时整个分支不进，于是"一条车费行都没有、用车需求还卡在 PENDING_REVIEW"的团期子订单能一路走完 finalize 把钱结掉。本单补上车侧对称闸门：只读户级 order_vehicle_requirement.status，status == DONE 才放行；不读车费派生行、不读实配行、不读镜像列 order_main.vehicle_control_status；只判 TRAVEL（行程用车），不判 TRANSFER（接送机，理由见"业务边界"）。
+
+与住宿闸不同的是：车侧的 needs_vehicle 自工单 #4499 起对所有新订单恒为 true（零信息量），若对"该户压根没提交过用车需求"也做硬阻断，会把"整团都不需要车"的团全部卡死在结算口且无任何逃生口。故 wx 2026-09-10 拍板取方案 A：需求行存在但未完成 = 硬阻断（584131）；需求行缺失 = 软预警（不阻断），待 #7441 交付团级免车开关 vehicleWaived 后再升级。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 完成核单 | POST | `/v3/admin/order/{orderId}/settlement/finalize` | 新增错误码 + 响应新增预警取值 | 团期子订单新增用车户级闸门（584131），warnings[].category 新增 VEHICLE |
+
+---
+
+## 三、接口详情
+
+### 1. 完成核单 `POST /v3/admin/order/{orderId}/settlement/finalize`
+
+**VO**: `Long（Path 参数 orderId，无请求体） → Result<SettlementSubmitRespVO>`
+
+#### 使用场景
+
+管理后台核单页点击「完成核单」按钮时调用，原子完成结算并推订单进终态。本单不改调用方式；团期子订单（group_batch_id 非空，经统一判团门面判定）在此次改动后，若该户 needs_vehicle=true 且用车需求未完成，会被本闸拦截。
+
+#### 入参字段表
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| orderId | Path | Long | 是 | 大于等于1 | 订单 ID；团期子订单与核心订单共用本端点；本单未改 |
+
+（finalize 本身无请求体，本单未新增/删除任何入参。）
+
+#### 出参字段表
+
+Result<SettlementSubmitRespVO>，字段集合本单未增删，为保证本节自包含仍列出全部字段，并单列 warnings[] 子字段（本单实际改动点）：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| summaryId | Long | 新写入的 settlement_summary 主键 |
+| finalSnapshotId | Long | 核单终态快照 ID |
+| finalSnapshotVersionNo | Integer | 核单终态快照版本号 |
+| finalSnapshotStatus | String | 核单终态快照状态 |
+| orderId | Long | 订单 ID |
+| settledAt | LocalDateTime | 核单完成时间 |
+| totalAmount | BigDecimal | 订单总金额快照 |
+| paidAmount | BigDecimal | 已付金额快照 |
+| balanceAmount | BigDecimal | 尾款金额快照 |
+| roomCost | BigDecimal | 住宿实际成本 |
+| ticketCost | BigDecimal | 门票实际成本 |
+| staffCost | BigDecimal | 人员费用实际成本 |
+| subsidyCost | BigDecimal | 补助实际成本 |
+| mealCost | BigDecimal | 餐食实际成本 |
+| vehicleCost | BigDecimal | 车辆基础服务总车费（按 Fleet 派车组合计） |
+| otherExpenseCost | BigDecimal | 其他支出实际成本 |
+| insurancePremium | BigDecimal | 保险实际保费（未出单/已撤单=0） |
+| totalActualCost | BigDecimal | 总实际成本 |
+| driverTransferAmount | BigDecimal | 给司机/主报账人转回金额 |
+| profitAmount | BigDecimal | 公司毛利 |
+| profitRate | BigDecimal | 毛利率（小数） |
+| orderStatusAfter | String | 结算后订单状态 |
+| mqTriggered | Boolean | 当前版本固定为 false |
+| warnings | List<WarningItemVO> | 软预警列表，见下表 |
+
+warnings[]（WarningItemVO）：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| settlementId | Long | 触发预警的核单明细行 id。category=VEHICLE 时恒为 null（既有 HOTEL/TICKET 恒非空），新增取值 |
+| category | String | 核单分类；新增取值 VEHICLE，枚举见"六.5" |
+| dayNumber | Integer | 行程第几天。category=VEHICLE 时恒为 null（既有 HOTEL/TICKET 恒非空），新增取值 |
+| message | String | 预警文案；VEHICLE 缺行场景固定为「用车：未提交用车需求」 |
+
+#### 请求示例
+
+```http
+POST /v3/admin/order/1934567890123456789/settlement/finalize
+Authorization: Bearer {token}
+```
+
+（无请求体，仅 Path 参数 orderId；本单未改请求形态）
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "success": true,
+  "data": {
+    "summaryId": "9600000000001",
+    "finalSnapshotId": "9600000000002",
+    "finalSnapshotVersionNo": 1,
+    "finalSnapshotStatus": "FINALIZED",
+    "orderId": "1934567890123456789",
+    "settledAt": "2026-09-11T10:30:25",
+    "totalAmount": "24800.00",
+    "paidAmount": "24800.00",
+    "balanceAmount": "0.00",
+    "roomCost": "4280.00",
+    "ticketCost": "3680.00",
+    "staffCost": "14260.00",
+    "subsidyCost": "720.00",
+    "mealCost": "860.00",
+    "vehicleCost": "5200.00",
+    "otherExpenseCost": "1260.00",
+    "insurancePremium": "180.00",
+    "totalActualCost": "23120.00",
+    "driverTransferAmount": "22940.00",
+    "profitAmount": "1680.00",
+    "profitRate": 0.0677,
+    "orderStatusAfter": "待财务复核",
+    "mqTriggered": false,
+    "warnings": [
+      {
+        "settlementId": null,
+        "category": "VEHICLE",
+        "dayNumber": null,
+        "message": "用车：未提交用车需求"
+      }
+    ]
+  }
+}
+```
+
+#### 空数据 / 降级响应
+
+本闸不产生独立的空态/降级响应：warnings 在没有任何软预警时为空数组 []，其余字段均为结算终态实值。本闸判定是同步内存/DB读取（不经 Feign/MQ），判据不可达时直接按错误响应处理，不发生静默降级。
+
+```json
+{ "code": 200, "success": true, "data": { "warnings": [] } }
+```
+
+#### 错误响应
+
+新增错误码 584131（本单核心变更）：
+
+```json
+{
+  "code": 584131,
+  "message": "团期子订单 GB202609120007 的用车尚未安排完成（用车需求当前状态：PENDING），请等车务配车完成后再提交核单",
+  "success": false,
+  "data": null
+}
+```
+
+若住宿闸与用车闸同时未就绪，先返回住宿侧既有错误码（闸序：住宿在前）：
+
+```json
+{
+  "code": 584130,
+  "message": "团期子订单 GB202609120007 的住宿尚未安排完成（住宿需求当前状态：PROCESSING），请等房务配房完成后再提交核单",
+  "success": false,
+  "data": null
+}
+```
+
+message 模板（SettlementErrorCode.SETTLEMENT_GROUP_VEHICLE_NOT_READY，584131）：团期子订单 {0} 的用车尚未安排完成（用车需求当前状态：{1}），请等车务配车完成后再提交核单。{0} = 订单号 orderNo；{1} = 用车需求当前 status 字面量（六个取值见"六.5"）。该分支不会出现"需求缺失"的情况——需求缺失走软预警（见响应示例），不抛错误码。
+
+#### 业务边界
+
+- 本闸只对团期子订单（经统一判团门面 OrderService.resolveGroupBatchLinks 判定，与 #7446 共用同一私有方法 isGroupSubOrder）且 needs_vehicle=true 生效；非团期订单与 needs_vehicle=false/null（工单 #4062~#4499 之间创建的存量订单）整体跳过，不发起判团查询，行为与改动前逐字节一致。
+- 判定顺序：先判 needs_vehicle（内存字段零成本），后判团（要发一次库查）——两处判断都为真才继续查用车需求。
+- 闸序固定：住宿闸（584130）→ 用车闸（584131）→ CASH_PAID 软预警。两闸同时未就绪只返回先触发的住宿闸错误码。
+- 判定只读户级 order_vehicle_requirement 当前 active 行的 status；不读车费派生行、不读实配行 order_vehicle_assignment、不读镜像列 order_main.vehicle_control_status——删除派生行、清空实配行都不能绕过闸门。
+- 只判 TRAVEL（行程用车），不判 TRANSFER（接送机）：结算车费日快照本身固定按 TRAVEL 取，闸门与账对齐；接送机需求未完成不会拦住本次结算。
+- 缺行软预警是已知的临时敞口（不是遗漏）：待 #7441 落地 vehicleWaived 后升级为硬阻断，届时 warnings[] 不再出现该 VEHICLE 缺行项。
+- 并发与幂等：判定与后续结算写入在同一 finalize 事务、同一把锁内，不存在 TOCTOU 窗口；本闸是只读判定，不加 @Idempotent。
+- 上线顺序约束（不由本接口契约体现，前端无需处理，仅供知悉）：本闸放行条件 status=DONE 今天只由逐户派车回调生产；#7441 的 D-C22（团车完成回写户级 DONE）必须先于 #7442（团级配车通电）上生产，否则团车配好的团会被本闸全部拦死。这条约束不影响本单契约本身。
+
+---
+
+## 四、契约约束与正确调用方式
+
+### 正确 / 错误 调用结果对照
+
+| 场景（订单形态） | 结果 |
+|------|------|
+| 团期子订单，用车需求 status=DONE（正确） | 200 成功，warnings 无车侧项 |
+| 团期子订单，用车需求 status 为 PENDING/PROCESSING/PENDING_REVIEW/REJECTED_TO_CONSULTANT/REJECTED_TO_ADMIN（错误） | 584131（HTTP 仍 200） |
+| 团期子订单，无 active 用车需求行（提示） | 200 成功，warnings 新增一条 category=VEHICLE 软预警（不阻断） |
+| 非团期订单（正确） | 200 成功，行为与改动前完全一致 |
+| 团期子订单但 needs_vehicle=0/null（存量单，正确） | 200 成功，不查用车需求，行为与改动前完全一致 |
+
+### 切换状态时的必要动作
+
+无需前端主动切换任何请求字段——finalize 无请求体，本闸完全由后端按订单当前状态判定。前端唯一需要改的是响应解析：warnings[] 渲染逻辑不能假设 settlementId/dayNumber 恒非空（category=VEHICLE 时两者为 null），需按 category 分支处理，VEHICLE 项直接展示 message 整体提示，不尝试用 settlementId 定位某一行明细。
+
+---
+
+## 五、数据库行为
+
+本单不新增任何数据库写操作。闸门是纯只读判定（读取该团期子订单当前用车需求状态与归团关系），随 finalize 既有事务执行；若判定不通过（584131），finalize 在写入结算数据之前即中止、整个事务回滚，不产生部分写入，不影响 finalize 对住宿/门票/人员等既有数据的写入行为。不新增表、不新增列、不写 Flyway、不改索引。
+
+---
+
+## 六、边界行为
+
+- 未登录 → 401（网关拦截）
+- 订单不存在 / 状态不允许核单 → 沿用 finalize 既有前置校验，本单未改动
+- 团期子订单但 needs_vehicle=0/null → 直接放行，不查用车需求
+- 非团期订单 → 直接放行，不查用车需求
+- 用车需求行缺失 → 不阻断，warnings 追加一条 category=VEHICLE 软预警（见上）
+- 下游判团门面/需求门面本身不可用（同步内存/DB 调用，非 Feign/MQ）→ 按既有全局异常处理返回错误，本单不新增降级分支
+- 老数据兼容：存量老响应结构不受影响，warnings[] 新增取值属"新增元素"而非"改变既有元素结构"，向前兼容读取（未识别 category 的前端旧代码按未知分类兜底展示即可，不会因该字段崩溃，只是 settlementId/dayNumber 为 null 需要前端自身做好判空）
+
+---
+
+## 六.5、枚举
+
+### warnings[].category（com.hulalv.order.settlement.enums.SettlementCategory）
+
+**所属字段**: `warnings[].category` | **类型**: `String`
+
+SettlementCategory 枚举全量有 8 个取值（原型八个核单明细 Tab），但当前 finalize 的 performSubmitBlockingChecks 只会产出以下 3 种到 warnings[]，其余 5 个（MEAL/GUIDE/PHOTOGRAPHER/OTHER_INCOME/OTHER_EXPENSE）不会出现在本字段里：
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| HOTEL | 住宿 | 既有取值，CASH_PAID 现付缺凭证软预警，settlementId/dayNumber 恒非空 |
+| TICKET | 门票/游玩项目 | 既有取值，同上，恒非空 |
+| VEHICLE | 车辆 | 本单新增取值，团期子订单缺失用车需求行时的软预警，settlementId/dayNumber 恒为 null |
+
+### 584131 message 占位符 {1}（com.hulalv.order.requirement.enums.RequirementStatus）
+
+**所属字段**: 错误响应 message 文本内嵌值（非独立 JSON 字段） | **类型**: `String`
+
+| 值 | 中文 | 是否放行本闸 |
+|----|------|------|
+| PENDING | 待房务配 | 否 |
+| PROCESSING | 配房中 | 否 |
+| DONE | 配房完成 | 是（唯一放行值） |
+| PENDING_REVIEW | 待审核 | 否 |
+| REJECTED_TO_CONSULTANT | 驳回 | 否 |
+| REJECTED_TO_ADMIN | 驳回 | 否 |
+
+（label 文案是历史上的房务侧措辞，车需求场景下前端应另行映射展示文案，不要直接透出 PROCESSING 对应"配房中"这种误导性文案。）
+
+---
+
+## 六.6、修改前后对比
+
+### 字段级对比
+
+| 字段 | 改前 | 改后 |
+|------|------|------|
+| warnings[].category 可能取值 | HOTEL / TICKET | HOTEL / TICKET / VEHICLE（新增） |
+| warnings[].settlementId | 恒非空 | HOTEL/TICKET 恒非空；VEHICLE 恒为 null（新增分支） |
+| warnings[].dayNumber | 恒非空 | HOTEL/TICKET 恒非空；VEHICLE 恒为 null（新增分支） |
+| 错误码集合 | 无 584131 | 新增 584131 SETTLEMENT_GROUP_VEHICLE_NOT_READY |
+| 其余响应字段 | 无变化 | 无变化 |
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 |
+|------|------|------|
+| 团期子订单 + needs_vehicle=1 + 用车需求非 DONE（有需求行） | 200 成功，结算完成 | 584131（HTTP 仍 200） |
+| 团期子订单 + 用车需求 DONE | 200 成功 | 200 成功（不变） |
+| 团期子订单 + 无 active 用车需求行 | 200 成功，warnings 无车侧项 | 200 成功，warnings 新增一条 category=VEHICLE 缺行预警 |
+| 非团期订单 | 200 成功 | 200 成功（完全不变，本闸不进） |
+| 团期子订单 + needs_vehicle=0（存量单） | 200 成功 | 200 成功（不变，本闸不进） |
+| 用车需求非 DONE + 车费派生行被清空/撤销 | 200 成功（通用品类门禁 rowCount>0 分支不进） | 584131（本闸只读需求 status，删行不能绕过） |
+
+---
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**: 是。团期子订单在特定状态下（用车需求存在但未完成）由"可结算"变为"584131 阻断"——这正是本单的设计目的，用于堵住"用车没配好也能结算"的洞。
+- **前端是否必须同步上线**: 是。需要新增对 584131 的错误提示（建议直接展示后端 message，已含订单号与需求状态）；warnings[] 渲染逻辑必须兼容 category=VEHICLE 时 settlementId/dayNumber 为 null 的情形，否则可能因假设非空而报错或渲染异常。
+- **前端 workaround 清理点**: 无（本单是新增闸门，不涉及清理旧 workaround）。
+
+---
+
+## 七、不影响范围
+
+- **仅影响**: `POST /v3/admin/order/{orderId}/settlement/finalize` 端点在团期子订单（且 needs_vehicle=true）时的错误码集合与 warnings[] 取值集合。
+- **零影响**:
+  - 核心（非团期）订单的 finalize 行为——完全不变。
+  - needs_vehicle=0/null 的存量团期订单——完全不变。
+  - finalize 内其余既有检查（住宿闸 584130、GUIDE/PHOTOGRAPHER 结算完成检查、CASH_PAID 软预警、金额汇总写入）——未改动。
+  - `POST /v3/admin/order/{orderId}/settlement/submit` 及分步保存/草稿接口——本闸只挂在 finalize。
+  - fleet 侧、hl-common-*、hl-gateway 路由——本单只改 hl-order-service-v3 一个服务，`/v3/admin/**` 路由沿用既有通配，未新增路由配置。
+  - 权限点——未新增。
+  - 响应体除 warnings[] 新增取值外的其余字段结构——未增删。
+
+---
+
+## 八、测试环境已验证
+
+**取证环境**（2026-09-11 17:38 批次，hl-gateway、hl-order-service-v3 当时一致停在 dev-v3 `f035b85be`）：
+
+```
+hl-gateway               dev-v3   f035b85be  0/N   2026-09-11 17:25:31   ok
+hl-order-service-v3      dev-v3   f035b85be  0/N   2026-09-11 17:24:23   ok
+```
+
+端点：`POST /v3/admin/order/{orderId}/settlement/finalize`，角色 ADMIN，经 hl-gateway 网关实调（非绕网关直连服务）。
+
+**17:38 批次三组**：
+
+| 场景 | 前置 | code | message 原文 |
+|---|---|---|---|
+| 团期子订单 + 用车需求 PENDING | 订单 HL20260819230641736，group_batch_id 非空；用车需求 status 由 SQL 直更为 PENDING | **584131** | 团期子订单 HL20260819230641736 的用车尚未安排完成（用车需求当前状态：PENDING），请等车务配车完成后再提交核单 |
+| 同订单需求推 DONE | 同上，SQL 直更回 DONE | **200** | 成功（finalSnapshotStatus=FINALIZED、orderStatusAfter=待财务复核） |
+| 核心散客单 | 订单 HL20260819223840144，两个 batch 列均为 NULL，住宿与用车需求都压成 PENDING | **200** | 成功——两道团期闸均未触发（若误触发必返 584130/584131） |
+
+**18:36 补测批次一组**（服务已滚至 `02e998fbf`，四行部署状态均 0/N）：
+
+| 场景 | 前置 | code | message 原文 |
+|---|---|---|---|
+| 车费派生行全部软删 + 需求 PROCESSING | order_settlement_vehicle_fee 活跃 0 行（请求前实测），需求 status='PROCESSING' | **584131** | 团期子订单 HL20260819230641736 的用车尚未安排完成（用车需求当前状态：PROCESSING），请等车务配车完成后再提交核单 |
+
+**取证边界（如实说明，不得省略）**：
+
+1. 以上所有前置条件均为 SQL 直更需求表 status（第二批次另直更车费派生行）构造，不是配车链路真实产生的业务状态；配车/车务回调链路本身未在本次取证中被验证。
+2. 取证过程中用 SQL 绕过了与本单无关的三道通用前置闸：584310（八个核单分类未全部确认）、584082（待收尾款）、车费草稿冻结确认——手段是把明细行标记 CONFIRMED、把应收金额清零对齐已付。这三道闸自身的正确性未在本次取证中验证。
+
+backend_status: "deployed" 代表代码已合并 dev-v3 并随服务部署（合并提交 bacd1ac86，2026-09-11 10:16:01，PR #7499）；gateway_status 现更新为 verified，依据即上述 2026-09-11 17:38 与 18:36 两批网关实测。
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#7445](https://git.1814.love:8443/wx/HL/issues/7445)
+- 关联 PR: [wx/HL#7499](https://git.1814.love:8443/wx/HL/pulls/7499)
+- 前置/关联依赖：`#7347`（住宿侧同形闸门，584130，本单车侧对称件）、`#7446`（同一方法体内住宿闸判团口径统一，与本单共用私有方法 isGroupSubOrder，#7445 先合、#7446 随后统一）、`#7441`（尚未合入，其 D-C26 ② 将把本单"缺行软预警"分支升级为硬阻断并接入 vehicleWaived）
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#7445](https://git.1814.love:8443/wx/HL/issues/7445)
+- **PR**: [#7499](https://git.1814.love:8443/wx/HL/pulls/7499)
+- **Merge commit**: [bacd1ac86](https://git.1814.love:8443/wx/HL/commit/bacd1ac86cdeba0f368f1f01b92ed2f5a47aa4a2)
+
+### 联系人
+
+- **后端负责人**: @wx
@@ -0,0 +1,307 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7446"
+title: "住宿结算闸归团判据改走统一门面，修正已降级的 productBatchId 误用（584130 触发人群变更）"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: "2026-09-11"
+status_note: "gateway_status=verified：2026-09-11 17:38 批次网关实测已完成（详见“八、测试环境已验证”），经 hl-gateway 网关调用 POST /v3/admin/order/{orderId}/settlement/finalize 验证四组场景（含 584130 硬阻断与放行分支）。所有前置条件均为 SQL 直更需求表状态构造，非真实业务链路（配房）产生；另绕过与本单无关的 584310/584082/车费草稿冻结确认三道通用前置闸，其正确性未验证；本单“团期已软删放行”这一唯一取舍点未在本次网关实测中单独覆盖。"
+updated_at: "2026-09-11"
+base: "dev-v3"
+---
+
+# order-v3: 住宿结算闸归团判据改走统一门面
+
+> **服务**: hl-order-service-v3
+> **PR**: #7504
+> **Issue**: #7446
+> **日期**: 2026-09-11
+> **影响范围**: 既有端点 `POST /v3/admin/order/{orderId}/settlement/finalize`（完成核单）中住宿结算闸（584130）的归团判据修正；签名、错误码值/符号/message 文案、响应结构均未改，仅 584130 的触发人群变化。
+
+---
+
+## ⚠️ 关键变化
+
+本次只改判据，不改契约：`POST /v3/admin/order/{orderId}/settlement/finalize` 的住宿结算闸（错误码 584130）判断"这单是不是团期子订单"的依据，从 `order.getProductBatchId() == null` 改为统一判团门面 `OrderService.resolveGroupBatchLinks`（经新增私有方法 isGroupSubOrder 转发；#7445 已在同一方法体建立该方法，本单复用）。
+
+**之前的 changelog（#7347，见十节链接）说"闸门只对 productBatchId 非空的订单生效"——这句话现在不再准确**，判团依据已改为统一门面。签名、错误码值/符号、message 文案与两个占位参数、响应体结构**均未改变**，但 584130 实际覆盖的订单范围变了：
+
+1. 一部分此前被静默漏判为非团期从而放行的订单（`group_batch_id` 非空但 `product_batch_id` 为空，即"脱离产品排期独立建团"的团单），现在会被 584130 正确拦截。
+2. 一部分此前因裸列判断误判为团期从而阻断的订单（`product_batch_id` 非空、`group_batch_id` 为空、且所属团期**已被软删**），现在会被判定为非团期，改为放行——这是本单唯一一处放松结算闸的已知取舍（详见"六.6"）。
+
+前端**无需修改任何代码**：错误码、message 文案、响应结构一字未变，只是该错误码出现的订单范围变了。
+
+---
+
+## 一、背景
+
+`SettlementService.assertGroupHotelReadyForFinalize`（#7347/PR #7433 引入的住宿户级闸门，方法体内新增于本单之前）原判团短路条件是 `order.getProductBatchId() == null`。但 `product_batch_id` 自 Issue #7083 起已被显式降级为"产品侧排期溯源 + 迁移期两跳回退通路"、**不再作归团判别**——`order_main` 表的列 COMMENT 与 `OrderInfo.java` 的字段 javadoc 均明确记载归团判别唯一依据是 `group_batch_id`。用错判据会让闸门在"建团脱离产品排期"的一部分团单上静默不生效，#7347 想堵的洞在这批订单上依然成立。
+
+本单**不是简单地把 getProductBatchId 换成 getGroupBatchId**——单列直换会在另一个方向开新洞：`group_batch_id` 是 #7083 后加列，存量靠回填脚本、增量靠创单同事务回写、漏网靠对账 Job 兜底，三者都不是瞬时完成的，回填窗口期内团期仍存活但 `group_batch_id` 尚未回填的老单，裸判会把它们误判成普通单直接放行。本单改调仓内已有的统一判团口径 `OrderService.resolveGroupBatchLinks`（一跳 `group_batch_id`、为空再两跳回退 `product_batch_id`），两个方向都不漏。与 #7445（同一方法体新增的用车闸）已协调统一使用同一私有方法 `isGroupSubOrder`，避免同一方法体内相邻两道闸对同一订单给出相反的"是不是团单"结论。
+
+---
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 完成核单 | POST | `/v3/admin/order/{orderId}/settlement/finalize` | 判据修正（584130 触发人群变更） | 住宿结算闸归团判据由已降级的 productBatchId 改走统一判团门面 |
+
+---
+
+## 三、接口详情
+
+### 1. 完成核单 `POST /v3/admin/order/{orderId}/settlement/finalize`
+
+**VO**: `Long（Path 参数 orderId，无请求体） → Result<SettlementSubmitRespVO>`
+
+#### 使用场景
+
+管理后台核单页点击「完成核单」按钮时调用，原子完成结算并推订单进终态。本单不改调用方式、不改请求/响应结构，只改住宿闸内部的归团判据，因此本节按模板要求自包含列出请求/响应契约（与 #7445 changelog 重复列出属正常，两单各自独立可读）。
+
+#### 入参字段表
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| orderId | Path | Long | 是 | 大于等于1 | 订单 ID；本单未改 |
+
+（finalize 本身无请求体，本单未新增/删除任何入参。）
+
+#### 出参字段表
+
+`Result<SettlementSubmitRespVO>`，字段集合本单**未增删任何字段**（本单只改内部判据，不改响应结构），为保证本节自包含仍列出关键字段：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| orderId | Long | 订单 ID |
+| finalSnapshotStatus | String | 核单终态快照状态 |
+| totalAmount | BigDecimal | 订单总金额快照 |
+| paidAmount | BigDecimal | 已付金额快照 |
+| roomCost | BigDecimal | 住宿实际成本 |
+| totalActualCost | BigDecimal | 总实际成本 |
+| orderStatusAfter | String | 结算后订单状态 |
+| warnings | List<WarningItemVO> | 软预警列表；本单不改其结构与产出逻辑 |
+
+（完整字段清单共 24 个，见 `SettlementSubmitRespVO`；本单未增删任何字段，故不重复列出全部，只摘录关键项用于自包含理解。）
+
+#### 请求示例
+
+```http
+POST /v3/admin/order/1934567890123456789/settlement/finalize
+Authorization: Bearer {token}
+```
+
+（无请求体，仅 Path 参数 orderId；本单未改请求形态）
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "success": true,
+  "data": {
+    "orderId": "1934567890123456789",
+    "finalSnapshotStatus": "FINALIZED",
+    "totalAmount": "24800.00",
+    "paidAmount": "24800.00",
+    "roomCost": "4280.00",
+    "totalActualCost": "23120.00",
+    "orderStatusAfter": "待财务复核",
+    "warnings": []
+  }
+}
+```
+
+#### 空数据 / 降级响应
+
+本闸不产生独立的空态/降级响应；判团查询是既有门面的纯本地只读查询（同库同服务，非 Feign/MQ），不发生外部降级。warnings 为空时返回空数组：
+
+```json
+{ "code": 200, "success": true, "data": { "warnings": [] } }
+```
+
+#### 错误响应
+
+584130 错误码本身未变，仅摘录触发该码的一个示例（判团结果来自统一门面而非旧的 productBatchId 判据）：
+
+```json
+{
+  "code": 584130,
+  "message": "团期子订单 GB202609120007 的住宿尚未安排完成（住宿需求当前状态：PROCESSING），请等房务配房完成后再提交核单",
+  "success": false,
+  "data": null
+}
+```
+
+message 模板（SettlementErrorCode.SETTLEMENT_GROUP_HOTEL_NOT_READY，584130，本单未改）：团期子订单 {0} 的住宿尚未安排完成（住宿需求当前状态：{1}），请等房务配房完成后再提交核单。{0} = 订单号 orderNo；{1} = 住宿需求当前 status 字面量，需求缺失时固定文案"未提交住宿需求"。
+
+#### 业务边界
+
+- 判团口径统一为 `OrderService.resolveGroupBatchLinks`（经私有方法 isGroupSubOrder 转发），不再使用已降级的 productBatchId；该方法同时被 #7445 新增的用车闸复用，是全类唯一的判团落点。
+- needsHotel 半条件判断依旧前置：短路顺序为"先 needsHotel、后判团"，needs_hotel=0/null 时直接放行、不发判团查询（与改动前一致，未变）。
+- 已知取舍：所属团期已被软删的订单（product_batch_id 非空、group_batch_id 为空、团期已软删）此前会因 productBatchId 非空而进闸判定住宿状态，改判后判定为非团期、跳闸放行——这是本单唯一一处放松结算闸的行为变更，详见"六.6"。
+- 待回填窗口内的老单（product_batch_id 非空、group_batch_id 为空、团期存活）判团口径经统一门面的两跳回退仍判定为团单，闸门继续生效，不受影响。
+- 判定语义本身完全未变：仍只读户级住宿需求 status，仍只认 DONE 放行，不读住宿派生行，不解析行程日自行判断"是否自助订房"。
+
+---
+
+## 四、契约约束与正确调用方式
+
+### 正确 / 错误 调用结果对照（本单不改请求 payload，用订单形态代替）
+
+| 场景（订单形态） | 结果 |
+|------|------|
+| group_batch_id 非空 + product_batch_id 非空（常规团单），住宿需求非 DONE | 584130（不变） |
+| group_batch_id 非空 + product_batch_id 为空（脱离产品排期建团），住宿需求非 DONE | 584130（改前静默漏判放行，本单修正为阻断） |
+| product_batch_id 非空 + group_batch_id 为空 + 团期存活（回填窗口老单），住宿需求非 DONE | 584130（不变，两跳回退保住） |
+| product_batch_id 非空 + group_batch_id 为空 + 团期已软删，住宿需求非 DONE | 放行（改前 584130，改后判定为非团单，已知取舍） |
+| 两列皆空（核心散客单） | 放行（不变） |
+| needs_hotel=0/null | 放行（不变，且改后连判团查询都不发） |
+
+### 切换状态时的必要动作
+
+无需前端做任何动作。本单不改请求 payload、不改错误码、不改响应结构，仅内部判据修正；前端现有对 584130 的处理逻辑无需调整，唯一影响是该错误码出现的订单范围变了（不改变前端识别/展示逻辑）。
+
+---
+
+## 五、数据库行为
+
+本单不写数据库。判团查询是既有门面 `OrderService.resolveGroupBatchLinks` 的纯只读查询（同库同服务本地查询，非 Feign/MQ），不新增表、不新增列、不新增索引、不写 Flyway。判定不通过时 finalize 在写入结算数据之前即中止、整个事务回滚，不产生部分写入。
+
+---
+
+## 六、边界行为
+
+- 未登录 → 401（网关拦截）
+- needs_hotel=0/null → 直接放行，不发判团查询（短路顺序：先 needsHotel、后判团，未变）
+- 判团查询本身若异常，走既有全局异常处理，本单不新增降级分支
+- 团期已软删的订单 → 判定为非团期，放行（已知取舍，见"六.6"）
+- 待回填窗口老单（团期存活但 group_batch_id 未回填）→ 判定为团期，闸门继续生效（不受回填进度影响）
+
+---
+
+## 六.5、枚举
+
+本单不新增、不改变任何响应字段的枚举取值。584130 的两个 message 占位符沿用既有定义，未变：
+
+### 584130 message 占位符 {1}（com.hulalv.order.requirement.enums.RequirementStatus）
+
+**所属字段**: 错误响应 message 文本内嵌值（非独立 JSON 字段） | **类型**: `String`
+
+| 值 | 中文 | 是否放行本闸 |
+|----|------|------|
+| PENDING | 待房务配 | 否 |
+| PROCESSING | 配房中 | 否 |
+| DONE | 配房完成 | 是（唯一放行值） |
+| PENDING_REVIEW | 待审核 | 否 |
+| REJECTED_TO_CONSULTANT | 驳回 | 否 |
+| REJECTED_TO_ADMIN | 驳回 | 否 |
+
+### warnings[].category（com.hulalv.order.settlement.enums.SettlementCategory，本单未改动，供自包含参照）
+
+**所属字段**: `warnings[].category` | **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| HOTEL | 住宿 | 既有取值，本单未改 |
+| TICKET | 门票/游玩项目 | 既有取值，本单未改 |
+| VEHICLE | 车辆 | 既有取值（由 #7445 同批引入，本单未涉及） |
+
+---
+
+## 六.6、修改前后对比
+
+### 字段级对比
+
+无字段级变化。请求 payload（无）、响应体 `SettlementSubmitRespVO` 的字段集合均未改动；584130 的错误码值、符号、message 文案、两个占位参数均未改；仅错误响应触发人群变化。
+
+### 行为级对比
+
+| 订单形态 | 改前 | 改后 |
+|---|---|---|
+| group_batch_id 非空、product_batch_id 非空（绝大多数团单） | 进闸 | 进闸（不变） |
+| group_batch_id 非空、product_batch_id 为空（脱离产品排期建团） | 跳闸（漏判） | 进闸（本单修正） |
+| product_batch_id 非空、group_batch_id 为空、团期存活（回填窗口老单） | 进闸 | 进闸（不变，靠门面两跳回退保住） |
+| product_batch_id 非空、group_batch_id 为空、团期已软删 | 进闸 | 跳闸（行为变更，已知取舍，见下方说明） |
+| 两列皆空（核心散客单） | 跳闸 | 跳闸（不变） |
+| needs_hotel 为 0/null | 跳闸 | 跳闸（不变，且改后连判团查询都不发） |
+
+**关于"团期已软删"这一行的取舍说明**：门面对团期已软删的订单返回"不归团"（反查通道被软删过滤），于是这批订单从"今天进闸"变为"跳闸"。这仍是行为变更。之所以可接受：软删团期不再提供子订单视图是 #7083 已确立的系统级口径，团都解散了还卡住结算不符合业务预期；工单要求先量化受影响订单数再合并（工单 AC-1 的方向乙 SQL），量化结果见工单本身，本 changelog 不重复贴库查数据。
+
+---
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**: 是（覆盖人群变化——一部分订单从放行变阻断，一部分从阻断变放行；签名、错误码值/符号、响应结构本身不变）。
+- **前端是否必须同步上线**: 否。前端无需改代码；错误码、message 文案、响应结构一字未变，前端现有对 584130 的处理逻辑无需调整。
+- **前端 workaround 清理点**: 无。
+
+---
+
+## 七、不影响范围
+
+- **仅影响**: `POST /v3/admin/order/{orderId}/settlement/finalize` 中住宿结算闸（assertGroupHotelReadyForFinalize）的归团判据。
+- **零影响**:
+  - 584130 的错误码值/符号/message 文案/两个占位参数——完全不变。
+  - 响应结构 SettlementSubmitRespVO 的任何字段——不增删。
+  - 住宿闸的判定语义本身（只读户级需求 status/只认 DONE 放行/不看派生行/不解析行程日）——逐字节未变。
+  - #7445 新增的用车闸（同一方法体内相邻代码，但两者是独立判定，互不影响各自触发条件）。
+  - `POST /v3/admin/order/{orderId}/settlement/submit` 及分步保存/草稿接口。
+  - 核心（非团期）订单的 finalize 行为。
+  - fleet 侧、hl-common-*、网关路由、权限点——均未改动。
+
+---
+
+## 八、测试环境已验证
+
+**取证环境**（2026-09-11 17:38 批次，hl-gateway、hl-order-service-v3 当时一致停在 dev-v3 `f035b85be`）：
+
+```
+hl-gateway               dev-v3   f035b85be  0/N   2026-09-11 17:25:31   ok
+hl-order-service-v3      dev-v3   f035b85be  0/N   2026-09-11 17:24:23   ok
+```
+
+端点：`POST /v3/admin/order/{orderId}/settlement/finalize`，角色 ADMIN，经 hl-gateway 网关实调。
+
+四组请求/响应：
+
+| 场景 | 前置 | code | message 原文 |
+|---|---|---|---|
+| 方向甲（group_batch_id 非空 + product_batch_id 为空）+ 住宿 PENDING | 订单 HL20260819230221927；SQL 直更住宿需求为 PENDING | **584130** | 团期子订单 HL20260819230221927 的住宿尚未安排完成（住宿需求当前状态：PENDING），请等房务配房完成后再提交核单 |
+| 同订单住宿推 DONE | SQL 直更回 DONE | **200** | 成功（finalSnapshotStatus=FINALIZED） |
+| 待回填老单（product_batch_id 非空 + group_batch_id 为空 + 团期存活） | 订单 HL20260819224314154；团期 deleted_at IS NULL 已实测 | **584130** | 团期子订单 HL20260819224314154 的住宿尚未安排完成（住宿需求当前状态：PENDING），请等房务配房完成后再提交核单 |
+| 核心散客单 | 订单 HL20260819223840144，两列均 NULL | **200** | 成功 |
+
+**取证边界（如实说明，不得省略）**：
+
+1. 以上所有前置条件均为 SQL 直更需求表 status 构造，不是配房链路真实产生的业务状态；配房链路本身未在本次取证中被验证。本单唯一的放松取舍点——"团期已被软删的订单改为放行"（见"六.6"）——未在本次网关实测中单独覆盖。
+2. 取证过程中用 SQL 绕过了与本单无关的三道通用前置闸：584310（八个核单分类未全部确认）、584082（待收尾款）、车费草稿冻结确认——手段是把明细行标记 CONFIRMED、把应收金额清零对齐已付。这三道闸自身的正确性未在本次取证中验证。
+
+backend_status: "deployed" 代表代码已合并 dev-v3 并随服务部署（合并提交 da3bd7854，2026-09-11 10:42:41，PR #7504）；gateway_status 现更新为 verified，依据即上述 2026-09-11 17:38 网关实测。存量影响量化（工单 AC-1 的方向甲/方向乙/方向丙三条 SQL 结果）由工单正文本身承载，本节不重复贴库查数据。
+
+---
+
+## 十、相关文档
+
+- 关联 Issue: [wx/HL#7446](https://git.1814.love:8443/wx/HL/issues/7446)
+- 关联 PR: [wx/HL#7504](https://git.1814.love:8443/wx/HL/pulls/7504)
+- 前置/关联依赖：`#7347`（原始需求单，PR #7433 引入了本单要修正的判据缺陷，本单是其判据订正件而非同一工单的延续）、`#7445`（同一方法体内新增的用车闸，与本单共用私有方法 isGroupSubOrder，#7445 先合、#7446 随后统一判团口径）、`#7449`（判团口径统一，收口全仓其余 23 处同类 productBatchId 误用，本单不处理，另建单处理）
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#7446](https://git.1814.love:8443/wx/HL/issues/7446)
+- **PR**: [#7504](https://git.1814.love:8443/wx/HL/pulls/7504)
+- **Merge commit**: [da3bd7854](https://git.1814.love:8443/wx/HL/commit/da3bd785463425fbdfebf409385fa77ff69752f9)
+
+### 联系人
+
+- **后端负责人**: @wx