hl-api-changelog/changelogs-v2/2026-09/06_7197_订单详情main透传groupBatchStatus-修改接口-管理后台.md

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

schema	ticket	title	consumer	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	7197	订单详情 main 透传团期状态 groupBatchStatus	admin	wx(GIT)	修改接口	deployed	verified	verified	mmg	22eb9b03		2026-09-08	后端已合 dev-v3 并部署测试服、网关实测通过(PR #7213)。前端待接入 groupBatchStatus 用于判团及下游需求冻结期置灰。	2026-09-06	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.*	—	其它字段不变

请求示例

GET /v3/admin/order/2096412454488612866

响应示例

{
  "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，其它订单字段正常填充。

错误响应

{
  "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
• PR: #7213
• Merge commit: 1f87dd04

联系人

• 后端负责人: wx
• 前端负责人（hl-ui）: mmg