changelog(7197): 订单详情 data.main 透传 groupBatchStatus（修改接口·管理后台）

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XYL5S9SsBtkg7aGyFAbrrQ
2026-09-06 21:45:25 +08:00
@@ -0,0 +1,262 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7197"
+title: "订单详情 main 透传团期状态 groupBatchStatus"
+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-06"
+status_note: "后端已合 dev-v3 并部署测试服、网关实测通过(PR #7213)。前端待接入 groupBatchStatus 用于判团及下游需求冻结期置灰。"
+updated_at: "2026-09-06"
+base: "dev-v3"
+---
+
+# 团期模块：订单详情 main 透传团期状态 groupBatchStatus
+
+> **服务**: `hl-order-service-v3`
+> **Issue**: #7197
+> **PR**: #7213（squash 合入 dev-v3 `1f87dd04`）
+> **日期**: 2026-09-06
+> **影响范围**: 管理后台订单详情页面、团期子订单需求冻结期置灰（#7149 后续）
+
+## ⚠️ 关键变化
+
+`GET /v3/admin/order/{id}` 响应 `data.main` 新增只读字段 `groupBatchStatus`（String / null），映射所属团期的 `order_group_batch.batch_status` 原样透传。普通订单、团期查不到、团期已软删均返回 null；与既有 `groupBatchId / batchNo / batchName` 同源同事务。**无破坏向后兼容**——纯新增字段，旧客户端无需改动。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|---|---|---|---|---|
+| 1 | 订单详情 | GET | `/v3/admin/order/{id}` | 响应字段新增 | `data.main.groupBatchStatus` 透传团期状态 |
+
+---
+
+## 三、接口详情
+
+### 1. 订单详情 `GET /v3/admin/order/{id}`
+
+**VO**: `OrderDetailRespVO → OrderMainVO`（`data.main`，`hl-order-service-v3/src/main/java/com/hulalv/order/core/controller/admin/vo/detail/OrderMainVO.java`）新增 `groupBatchStatus: String / null`
+
+#### 使用场景
+
+管理后台订单详情页面加载订单全量信息；定制师根据 `groupBatchStatus` 判定团期是否进入物料准备及之后的冻结期，下游（提需求弹窗 #7149）据此置灰「提交房型 / 用车需求」入口。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| `id` | Path | String(Long) | 是 | 订单 ID | 团期子订单、核心订单均支持 |
+
+#### 出参 `Result<OrderDetailRespVO>`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `data.main.groupBatchStatus` | String / null | 团期状态枚举值；普通订单 / 团期查不到 / 软删 均为 null；新增字段 |
+| `data.main.groupBatchId` | String | 团期 ID（既有字段） |
+| `data.main.batchNo` | String | 团期编号（既有字段） |
+| `data.main.batchName` | String | 团期名称（既有字段） |
+| `data.main.*` | — | 其它字段不变 |
+
+#### 请求示例
+
+```json
+GET /v3/admin/order/2096412454488612866
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "success": true,
+  "data": {
+    "main": {
+      "id": "2096412454488612866",
+      "groupOrder": true,
+      "groupBatchId": "2096412454643802114",
+      "batchNo": "Q202610012052935476548939777",
+      "batchName": "测试班期",
+      "groupBatchStatus": "RESOURCE_PREPARING",
+      "orderStatus": "CUSTOMIZING",
+      "roomControlStatus": "PENDING_REVIEW",
+      "vehicleControlStatus": "PENDING",
+      ...
+    },
+    "hotelRequirementBrief": { ... },
+    "vehicleRequirementBrief": { ... },
+    ...
+  }
+}
+```
+
+#### 空数据 / 降级响应
+
+无空列表语义。订单 ID 不存在返回 404；团期查不到（查询失败、已软删）时 `groupBatchStatus` 返回 null，其它订单字段正常填充。
+
+#### 错误响应
+
+```json
+{
+  "code": 404,
+  "message": "订单不存在",
+  "success": false,
+  "data": null
+}
+```
+
+#### 业务边界
+
+- **团期查询**：执行 `SELECT batch_status FROM order_group_batch WHERE id=groupBatchId AND is_deleted=0`；无结果返回 null，不异常。
+- **数据一致**：`groupBatchStatus` 与团期查询同一事务，保证与 `groupBatchId / batchNo / batchName` 同源。
+- **自动扩展**：后端不维护 `groupBatchStatus` 枚举白名单，新增团期状态（如 #7190 的 `TRIP_FINISHED`）自动透出，前端按未知值兜底不置灰。
+- **权限**：继承订单查询权限，无独立权限码。
+
+---
+
+## 四、契约约束与正确调用方式
+
+### ✅ 正确 / ❌ 错误 payload 对照
+
+| 场景 | 预期结果 |
+|---|---|
+| ✅ 团单（`productBatchId` 非空）查询 | `groupBatchStatus` 返回团期状态值（RECRUITING / RESOURCE_PREPARING / … / CANCELLED）或 null |
+| ✅ 普通订单（`productBatchId` 为空）查询 | `groupBatchStatus` 恒为 null，`groupBatchId / batchNo` 也为 null |
+| ✅ 团期已软删或查询失败 | `groupBatchStatus = null`，其它订单字段正常 |
+| ✅ 后端新增团期状态 | 前端收到新枚举值时应兜底（如当作「其它状态」处理），不硬编码状态列表 |
+
+### 调用约束
+
+- 本接口为 GET，无请求体，路径参数 `id` 必填。
+- 频率不限；响应内容随订单 / 团期实时变化（团期状态变更时 `groupBatchStatus` 同步更新）。
+
+---
+
+## 五、数据库行为
+
+纯查询接口，无写操作。
+
+查询逻辑：
+```
+SELECT batch_status FROM order_group_batch 
+WHERE id = order_main.product_batch_id AND is_deleted = 0 LIMIT 1
+```
+
+如果 `product_batch_id` 为 null 或查询无结果，`groupBatchStatus` 返回 null。无任何 INSERT / UPDATE / DELETE。
+
+---
+
+## 六、边界行为
+
+- **软删处理**：团期软删（`is_deleted=1`）视作查不到，返回 null，不异常。
+- **并发团期状态变更**：响应返回查询时刻的 `batch_status` 快照；前端在分秒级变更（如定制师拖入物料准备中）时仍可能看到旧值，但后端需求冻结拒绝以实时团期状态为准。
+- **前端置灰逻辑**：可据 `groupBatchStatus ∈ {MATERIAL_PREPARING, PENDING_DEPARTURE, TRAVELLING, REVIEWING, SETTLED}` 弱化「提需求」入口（#7149）；但**打回户例外**：该户最新需求被团期管理员 `REJECTED_TO_CONSULTANT` 后可重提一次，前端无法从本接口判定，需依赖提交时的 589536 或管理员系统提示。
+- **未知状态兜底**：枚举后续扩展时前端应将新枚举值按某种默认行为处理（如当作"冻结"、不置灰），不抛异常。
+
+---
+
+## 六.5、枚举 / 数据字典
+
+### groupBatchStatus（`com.hulalv.order.groupbatch.enums.GroupBatchStatus`）
+
+**所属字段**: `data.main.groupBatchStatus` | **类型**: `String / null`
+
+| 值 | 芯片文案 | 含义 | 需求提交 |
+|---|---|---|---|
+| RECRUITING | 招募中 | 正在招募参加者 | ✅ 放行 |
+| RESOURCE_PREPARING | 资源准备中 | 已成团，资源采购中 | ✅ 放行 |
+| MATERIAL_PREPARING | 物料准备中 | 物资准备中，需求冻结 | ❌ 589536（打回户例外） |
+| PENDING_DEPARTURE | 待出发 | 即将出发 | ❌ 589536（打回户例外） |
+| TRAVELLING | 出行中 | 正在出行 | ❌ 589536（打回户例外） |
+| TRIP_FINISHED | 行程结束 | 出行结束 | ❌ 589536（打回户例外） |
+| REVIEWING | 核单中 | 核对结算数据中 | ❌ 589536（打回户例外） |
+| SETTLED | 已结算 | 结算完成 | ❌ 589536（打下户例外） |
+| CANCELLED | 已取消 | 团期已取消 | ❌ 589501（团期不存在） |
+| null | — | 普通订单或团期查不到 | — |
+
+**注意**：列表以后端枚举为准，后续可能新增状态。前端应对未来枚举值容错，不能只处理上述 9 个值。
+
+---
+
+## 六.6、修改前后对比
+
+### 字段级对比
+
+| 字段 | 修改前 | 修改后 |
+|---|---|---|
+| `data.main.groupBatchStatus` | 无（缺失） | 新增，返回团期 `batch_status` 原值或 null |
+| `data.main.*（其它）` | 无变化 | 无变化 |
+
+### 行为级对比
+
+| 行为 | 修改前 | 修改后 |
+|---|---|---|
+| 判团依据 | 靠 `groupBatchId` 非空判定（前端硬编码） | 直接读 `groupBatchStatus`，含义更明确 |
+| 需求冻结期判定 | 前端/下游服务需自己维护团期状态枚举 | 后端透传团期实时状态，减少失同步 |
+| 新增团期状态 | 需改前端硬编码列表 | 自动支持，前端兜底即可 |
+
+---
+
+## 六.7、影响评估
+
+- **破坏向后兼容**：否——纯新增字段，旧客户端忽略 `groupBatchStatus` 仍能正常工作。
+- **前端是否必须同步上线**：建议同步——为了支持 #7149 的冻结期置灰。不同步时功能不受影响，但无法根据团期状态判定需求是否冻结。
+- **前端需清理的分支**：「硬编码团期状态枚举」应改为后端透传，若有本地状态映射表需同步新增状态。
+- **后端改动范围**：仅 `OrderMainVO`（`OrderDetailRespVO.main`）新增一个只读字段，零业务逻辑改动，兼容性最高。
+
+---
+
+## 七、不影响范围
+
+- **订单详情其它字段**：`groupBatchId / batchNo / batchName / orderStatus / roomControlStatus` 等既有字段零改动。
+- **订单创建 / 修改**：`POST /admin/order / PUT /admin/order/{id}` 等写操作不变。
+- **需求提交接口**：#7149 的 `PUT /admin/order/{id}/hotel-requirement` 等冻结期逻辑独立，本接口仅供前端读取状态。
+- **权限码 / 网关路由**：无新增权限码，网关路由规则不变。
+- **数据库表结构**：无 Flyway 迁移。
+
+---
+
+## 八、测试环境已验证
+
+**环境**：TEST 网关 `https://api.test.1814.love:9443`，order-v3 dev-v3 `1f87dd04` 两实例 2026-09-06 21:29 滚动部署完成。
+
+| 场景 | 请求 | 结果 |
+|---|---|---|
+| 团单（状态 RESOURCE_PREPARING） | `GET /v3/admin/order/2096412454488612866` | 200，`main.groupBatchStatus="RESOURCE_PREPARING"` ✓ |
+| 团单详情（状态 PENDING_DEPARTURE） | `GET /v3/admin/order/2096495107032190978` | 200，`main.groupBatchStatus="PENDING_DEPARTURE"` ✓ |
+| 普通订单 | `GET /v3/admin/order/2095549346731757569` | 200，`main.groupBatchStatus=null`，`groupBatchId=null` ✓ |
+| 团期与订单同源 | DB `order_group_batch.batch_status` | 与响应 `groupBatchStatus` 一致 ✓ |
+
+**单测**：`OrderServiceTest` 全绿；order-v3 `mvn test` 完全编译通过。
+
+---
+
+## 十、相关文档
+
+- 团期模块接口文档 `docs/order-v3/api/API-SPEC.html` §1.3.1（订单详情、判团字段透出）
+- 契约文档已同步：`docs/order-v3/api/contract/order-detail-vo.md`
+- 关联工单 #7149（下游置灰需求）、#7142（判团字段透出方案）、#7190（新增 TRIP_FINISHED）
+
+---
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#7197](https://git.1814.love:8443/wx/HL/issues/7197)
+- **PR**: [#7213](https://git.1814.love:8443/wx/HL/pulls/7213)
+- **Merge commit**: [`1f87dd04`](https://git.1814.love:8443/wx/HL/commit/1f87dd04)
+
+### 联系人
+
+- **后端负责人**: wx
+- **前端负责人（hl-ui）**: mmg
+