---
schema: "hl-changelog/v2"
ticket: "7446"
title: "住宿结算闸归团判据改走统一门面，修正已降级的 productBatchId 误用（584130 触发人群变更）"
consumer: "admin"
author: "wx(GIT)"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "not_required"
frontend_owner: "mmg"
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/车费草稿冻结确认三道通用前置闸，其正确性未验证；本单“团期已软删放行”这一唯一取舍点未在本次网关实测中单独覆盖。前端 2026-09-11 闭环 not_required：本单只改住宿闸归团判据(productBatchId 误用→统一门面 isGroupSubOrder)，584130 错误码值/符号/message 文案/响应结构一字未变，仅触发人群变化；前端对 584130 本就无专属处理走兜底透传后端 message，人群变化不影响识别/展示逻辑。零业务代码改动。"
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