docs(changelog): record group membership predicate fix (#7449)

2026-09-16 20:27:40 +08:00
@@ -0,0 +1,115 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7449"
+title: "订单团期成员判定统一门面（无接口契约变化，仅覆盖人群纠正）"
+consumer: "multiple"
+author: "wx(GIT)"
+change_type: "修复"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "not_required"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "三批后端 PR 已合入 dev-v3，合并提交 c51647a1d；hl-order-service-v3 已随 dev-v3 测试部署（部署现场 HEAD 3d2161a67，包含本单提交），8086/8186 两实例健康。经测试网关鉴权 GET /v3/admin/order/group-batch?page=1&pageSize=1 返回 HTTP/code 200。五段整合测试最新 791 份 Surefire 报告、至少 11117 个测试，0 failures/errors；无 Controller/Feign/DTO/VO/路径/字段/类型/枚举/错误码变化，前端无需改码。"
+updated_at: "2026-09-16"
+base: "dev-v3"
+---
+
+# 订单团期成员判定统一门面（修复）
+
+## 一、给前端与测试的一句话
+
+**前端无需任何改动。** 本次不新增、不删除、不修改任何接口、字段、路径、参数、枚举或错误码；只把订单在房务、车务、调整单、派单、小程序编辑、结算普通池、团期监听器和合同/保险自动出具中的“是否属于团期”判断统一为同一门面，纠正少量订单形态此前被错分支处理的问题。
+
+## 二、变更接口清单（无签名变化）
+
+本单未修改 Controller、Feign、DTO、VO 或共享契约，因此没有新增、删除或改签名的接口。以下是复用既有接口/后台任务时发生的内部分类修复。
+
+### 修复前的问题
+
+同一张订单同时存在两条团期关联通道：
+
+- 一跳：`order_main.group_batch_id` 直接指向运营团期；
+- 两跳：`order_main.product_batch_id` 通过仍存活的产品排期反查运营团期（历史兼容）。
+
+部分旧代码仍直接判断 `productBatchId`，导致：
+
+1. 只有 `groupBatchId` 的真实团期子订单被误当普通单，可能进入逐户房务/车务/调整或编辑路径；
+2. 只有 `productBatchId`、但已经查不到活跃团期的订单被误当团单，普通流程被错误拦截；
+3. 需要团期聚合根时，个别流程曾把产品排期 ID 当作运营团期 ID 使用；
+4. 结算普通池 SQL 只排除 `product_batch_id`，无法保守排除仅有 `group_batch_id` 的团期子订单。
+
+## 三、接口详情（契约不变）
+
+所有既有入口的请求与响应结构保持不变；业务内部按下表统一分类。
+
+### 修复后的统一口径
+
+| 订单形态 | 修复后分类 | 聚合根读取 |
+|---|---|---|
+| `groupBatchId != null`（无论 productBatchId 是否也存在） | 团期子订单 | 直连 ID 权威，按解析出的 groupBatchId 读取；不回退旧 productBatchId |
+| `groupBatchId == null` 且 productBatchId 可反查活跃团期 | 团期子订单 | 按反查得到的真实 groupBatchId 读取 |
+| 两列皆空 | 普通订单 | 不读取团期聚合根 |
+| 仅 productBatchId、但无法反查活跃团期 | 普通订单 | 不读取团期聚合根 |
+
+Java 业务判断统一走 `OrderService.isGroupSubOrder/resolveGroupBatchLinks`；Mapper SQL 无法调用 Java 门面时，普通池统一保守要求 `group_batch_id IS NULL AND product_batch_id IS NULL`。
+
+## 四、契约约束与正确调用方式
+
+前端和调用方继续按原接口契约调用，不传递或推导新的团期字段。后端受影响的既有能力如下：
+
+- 房务：酒店需求池、逐户抢单/转单、房态调整、团期房务归属；
+- 车务：用车需求生成、普通改期重置、人数变化重开、团期派车；
+- 订单：调整单增删游客与改期、人员派单默认报账人、报账人等级、小程序订单编辑；
+- 结算：CORE 普通结算任务池；
+- 团期：取消后报名计数回减、清单确认准入、合同/保险自动出具门。
+
+这些能力复用原有入口、请求体、响应体和错误码；仅命中人群与分支恢复到统一团期定义。小程序响应里的 `groupBatchId` 仍按既有契约表示产品侧排期 ID，本次未改字段语义。
+
+## 五、前端与兼容性结论
+
+- **字段级变化**：无。
+- **调用方式变化**：无。
+- **错误码/文案变化**：无。
+- **前端是否必须同步上线**：否（`frontend_status=not_required`）。
+- **可观察行为变化**：仅上述四种订单形态会按统一分类进入正确的既有成功/拦截分支。
+- **数据库变化**：无 DDL、无生产数据写入；本单只改应用判据和查询过滤条件。
+
+## 六、边界行为
+
+- 两列同时存在时，`groupBatchId` 权威，禁止回退到可能陈旧的 `productBatchId`。
+- 直连 groupBatchId 指向的聚合根不存在时，不再尝试 productBatchId 兜底。
+- product-only 仅在能反查到活跃团期时判为团期子订单；反查不到按普通订单。
+- SQL 普通池无法调用 Java 门面，故采用“两列同时为空”的保守过滤。
+
+## 七、不影响范围
+
+- 不改 Controller/Feign/DTO/VO/共享契约。
+- 不改路径、HTTP method、请求/响应字段、枚举、错误码或提示文案。
+- 不改小程序既有 `groupBatchId` 字段语义。
+- 不新增 DDL，不执行生产数据修复；正式环境不在本工单范围。
+
+## 八、测试环境已验证
+
+- 测试环境 AC-1 只读量化：方向 A=0、方向 B=0、方向 C=0；正式环境不在本工单范围。
+- 三批 PR 定向单测、MySQL 8 Testcontainers Mapper 回归与架构门禁通过。
+- 最终整合分段测试：五段 Maven reactor 全部 BUILD SUCCESS；最新 791 份 Surefire 报告合计至少 11,117 个测试，0 failures、0 errors。
+- 测试环境部署：`hl-order-service-v3` 随 `dev-v3` 滚动部署成功；部署现场 HEAD `3d2161a67` 包含本单 merge `c51647a1d`，8086/8186 两实例均健康。
+- 网关/API：鉴权调用 `GET /v3/admin/order/group-batch?page=1&pageSize=1`，HTTP 200、业务 code 200，分页结构与团期列表字段存在。
+- 日志：部署任务记录 Maven BUILD SUCCESS、两实例依次 UP、rolling deploy complete；持久证据已登记到 ticket 7449 workflow evidence。
+
+## 十、相关文档
+
+- Issue #7449 顶部实施说明与三批 PR 验证证据。
+- PR #7828、#7830、#7835 的变更说明和测试记录。
+
+## 关联 / 联系人
+
+- Issue: [#7449](https://git.1814.love:8443/wx/HL/issues/7449)
+- PR A: [#7828](https://git.1814.love:8443/wx/HL/pulls/7828)（house/hotel + shared facade）
+- PR B: [#7830](https://git.1814.love:8443/wx/HL/pulls/7830)（vehicle）
+- PR C: [#7835](https://git.1814.love:8443/wx/HL/pulls/7835)（core/adjustment/assignment/listeners/mapper/docs）
+- Merge commits: `b9cda3646`、`c07ff22ef`、`c51647a1d`
+- 后端负责人: @wx