diff --git a/changelogs-v2/2026-09/16_7449_全链路团期成员判定统一门面-修复-管理后台.md b/changelogs-v2/2026-09/16_7449_全链路团期成员判定统一门面-修复-管理后台.md new file mode 100644 index 00000000..7e9f7c76 --- /dev/null +++ b/changelogs-v2/2026-09/16_7449_全链路团期成员判定统一门面-修复-管理后台.md @@ -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