---
schema: "hl-changelog/v2"
ticket: "7149"
title: "团期子订单支付后即可提房车需求、物资准备起冻结、团单房型与间数必填"
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 并部署测试服、网关实测通过；前端需改团期子订单提需求弹窗：房型大类必填+两个新错误码展示+招募中即显示提需求入口。"
updated_at: "2026-09-06"
base: "dev-v3"
---

# 团期模块：子订单支付后即可提房车、物资准备起冻结、房型间数必填

> **服务**: `hl-order-service-v3`
> **Issue**: #7149
> **PR**: #7177
> **日期**: 2026-09-06
> **影响范围**: 团期子订单房型与用车需求提交/修改、团期冻结逻辑、业务允许入口

## ⚠️ 关键变化

团期子订单定制师的需求操作权限、冻结时机与校验规则同时调整：

1. **支付后即可提需求**：团期子订单（`product_batch_id` 非空）在定制师端已支付（`orderStatus=CUSTOMIZING`）后，团期处于招募中（`RECRUITING`）或资源准备中（`RESOURCE_PREPARING`）即可提交/修改房车需求，无需等待团期成团。前端需在招募中即显示提需求入口。

2. **物资准备起冻结**：团期进入物料准备中（`MATERIAL_PREPARING`）及之后后，定制师不得再提交或修改房车需求。新增错误码 **589536**；唯一例外：最新版需求被打回可重提一次。前端需在物料准备中后置灰入口或弹提示。

3. **房型与间数必填**：团期子订单的每个非自订晚的每段，房型大类（`roomCategory`）与房间数（`roomCount`）必填且≥1。新增错误码 **582099**；核心订单无此约束。前端需改房型大类为必填。

## 二、变更接口清单

| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|---|---|---|---|---|
| 1 | 提交/修改房型需求 | PUT | `/v3/admin/order/{id}/hotel-requirement` | 行为与守卫修改 | 团期子订单新增权限闸门+房型间数必填校验 |
| 2 | 调整订单统一提交 | POST | `/v3/admin/order/{id}/adjustment/submit` | 行为与守卫修改 | hotelRequirement与vehicleRequirement走同一闸门 |
| 3 | 提交/修改用车需求 | PUT | `/v3/admin/order/{id}/vehicle-requirement` | 行为与守卫修改 | 团期子订单新增权限闸门 |
| 4 | 团期汇总查询 | GET | `/v3/admin/order/group-batch/{groupBatchId}/requirement-summary` | 复用不改 | 响应roomCategory不再出现未知 |

## 变更接口

（同上）

## 三、接口详情

### 1. 提交/修改房型需求 `PUT /v3/admin/order/{id}/hotel-requirement`

**VO**: HotelRequirementReqVO转HotelRequirementRespVO

#### 使用场景

定制师提交/修改/调整房型需求。后端按是否存在active行与当前状态自动三分支：无active→INIT_SUBMIT、PENDING→PENDING_EDIT、DONE→DONE_ADJUST。本端点为@Deprecated兼容期。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| id | Path | Long | 是 | 正整数 | 订单ID |
| days | Body | Array | 是 | 长度等于tripNights | 每晚用房安排 |
| days[].dayNumber | Body | Integer | 是 | 1到tripNights | 第几晚 |
| days[].customerSelfBooked | Body | Boolean | 否 | true/false/null | 客户自订标记 |
| days[].segments | Body | Array | 条件必填 | 非自订晚≥1段 | 分住段列表 |
| days[].segments[].roomCategory | Body | String | 条件必填 | 字典room_category；团期必填 | 房型大类 |
| days[].segments[].roomCount | Body | Integer | 条件必填 | 大于0；团期必填 | 房间数 |
| days[].segments[].candidates | Body | Array | 是 | ≥1家 | 候选酒店列表 |
| specialTags | Body | Array | 否 | 字典值 | 特殊诉求标签 |
| remark | Body | String | 否 | 最长500字 | 备注 |

#### 出参

| 字段 | 类型 | 说明 |
|---|---|---|
| data.requirementId | String | 需求行ID |
| data.version | Integer | 版本号 |
| data.status | String | 需求状态 |
| data.submittedAt | String | 提交时间 |

#### 请求示例

提交房型需求，第1晚TWIN房2间，第2晚自订。应答会返回requirementId和version。

#### 响应示例

成功返回code=200，data包含requirementId、version、status=PENDING_REVIEW。

#### 错误响应

冻结场景返回code=589536，消息「团期已进入物资准备，需求已冻结，请联系团期管理员」。房型缺失返回code=582099，消息「团期订单第X晚第Y段需填写房型大类与房间数」。

#### 业务边界

- 权限守卫：允许RECRUITING/RESOURCE_PREPARING，拒绝MATERIAL_PREPARING及之后（589536）、CANCELLED（589501）。
- 房型间数必填：仅团期子订单非自订晚，缺失返582099，DB零副作用。
- 自订晚customerSelfBooked=true允许segments为空，不受约束。
- 打回例外：被打回后可重提一次，重提后再改仍返589536。

### 2. 调整订单统一提交 `POST /v3/admin/order/{id}/adjustment/submit`

**VO**: AdjustmentSubmitReqVO转AdjustmentSubmitRespVO

#### 使用场景

前端内存收集改动后一次性提交，后端单事务原子应用。房、车需求通过updates.hotelRequirement和updates.vehicleRequirement传入，走同一权限守卫。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| id | Path | Long | 是 | 正整数 | 订单ID |
| updates.hotelRequirement | Body | Object | 否 | 完整新版本 | 房需求（days/specialTags/remark） |
| updates.vehicleRequirement | Body | Object | 否 | 完整新版本 | 车需求（fleet/specialTags/remark） |

#### 出参

| 字段 | 类型 | 说明 |
|---|---|---|
| data.success | Boolean | true表示提交成功 |

#### 请求示例

包含updates.hotelRequirement和updates.vehicleRequirement两个可选字段，其结构同对应的两个直接提交接口。

#### 响应示例

成功返回code=200，data.success=true。

#### 错误响应

冻结返回code=589536；房型缺失返回code=582099。

#### 业务边界

- 房、车改动走同一闸门：RECRUITING/RESOURCE_PREPARING允许，MATERIAL_PREPARING及之后冻结。
- 房型间数必填校验同PUT /hotel-requirement。
- 单事务原子应用。

### 3. 提交/修改用车需求 `PUT /v3/admin/order/{id}/vehicle-requirement`

**VO**: VehicleRequirementReqVO转VehicleRequirementRespVO

#### 使用场景

定制师提交/修改/调整用车需求。后端按是否存在active行与当前状态自动三分支。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
| id | Path | Long | 是 | 正整数 | 订单ID |
| fleet | Body | Array | 是 | 至少1项 | 车辆类型与需求行 |
| fleet[].vehicleType | Body | String | 是 | SUV/MPV/大巴/轿车 | 车型大类 |
| fleet[].seats | Body | Integer | 是 | 大于0 | 每辆座位数 |
| fleet[].count | Body | Integer | 是 | 大于0 | 该类车数量 |
| specialTags | Body | Array | 否 | 字典vehicle_special_demand | 特殊诉求标签 |
| remark | Body | String | 否 | 最长500字 | 备注 |

#### 出参

| 字段 | 类型 | 说明 |
|---|---|---|
| data.requirementId | String | 需求ID |
| data.version | Integer | 版本号 |
| data.status | String | 需求状态 |
| data.submittedAt | String | 提交时间 |

#### 请求示例

提交MPV车2辆，座位数7，包含wifi特殊诉求。

#### 响应示例

成功返回code=200，data包含requirementId、version、status=PENDING_REVIEW。

#### 错误响应

冻结返回code=589536；团期不存在返回code=589501。

#### 业务边界

- 权限守卫同房需求：允许RECRUITING/RESOURCE_PREPARING，拒绝MATERIAL_PREPARING（589536）/CANCELLED（589501）。
- 房、车需求用同一闸门判。

## 四、契约约束与正确调用方式

### 正确 payload 对照

团期子订单第1晚填房型（TWIN 2间），第2晚自订：应答返回200和PENDING_REVIEW状态。

### 错误 payload 对照

第2晚缺房型大类：返回582099；物料准备中提交：返回589536；空白占位段（仅团单）：返回582099。

## 五、数据库行为

- 无表结构变更。
- 提交成功时order_hotel_requirement新版本status=PENDING_REVIEW、version++。
- 冻结拒绝时零副作用。

## 六、边界行为

- **自订晚处理**：customerSelfBooked=true允许segments为空，不受房型必填约束；不计入配房分母。
- **打回例外与重提限制**：被打回后可重提一次，重提后再改仍返589536；被打回配房行释放库存。
- **旧客户端兼容**：rooms数组为空时回退段级roomCategory+roomCount；房型必填校验对新旧结构同样适用。
- **团期状态枚举**：RECRUITING/RESOURCE_PREPARING允许，MATERIAL_PREPARING及之后冻结，CANCELLED拒绝。

## 六.5、枚举 / 数据字典

| 字段 | 值 | 中文 |
|---|---|---|
| roomCategory | STANDARD/SINGLE/TWIN/QUEEN/KING/SUITE/FAMILY/YURT/SPECIAL | 房型大类 |
| GroupBatchStatus | RECRUITING | 招募中 |
| GroupBatchStatus | RESOURCE_PREPARING | 资源准备中 |
| GroupBatchStatus | MATERIAL_PREPARING | 物料准备中 |
| GroupBatchStatus | PENDING_DEPARTURE等 | 已出发或更后 |
| GroupBatchStatus | CANCELLED | 已取消 |

## 六.6、修改前后对比

### 字段级对比

无字段增删；roomCategory和roomCount既有字段，仅约束条件变。

### 行为级对比

| 行为 | 修改前 | 修改后 |
|---|---|---|
| 团期子订单提需求权限 | 成团后 | 招募中或资源准备中 |
| 物料准备中操作 | 允许 | 冻结（589536） |
| 房型与间数 | 选填 | 必填（582099） |

## 六.7、影响评估

- **破坏向后兼容**：是；权限、冻结时机、校验规则均变。
- **前端必须同步上线**：是。
- **前端workaround清理点**：删除「等待成团」逻辑；删除「物料准备中允许」分支；房型改必填；直接展示589536和582099。

## 七、不影响范围

- 核心订单房型仍选填。
- 其他接口逻辑不变。
- DB表结构无变更。

## 八、测试环境已验证

**环境**：TEST，api.test.1814.love:9443，2026-09-06 15:44，admin/1001

**网关实测**：招募中提房型→200，PENDING_REVIEW；缺房型大类→582099；资源准备中可提→200；物料准备中冻结→589536；被打回户可重提→200，version=2；重提后再改→589536；用车同样冻结→589536；自订晚不受约束→200。

**单测**：BUILD SUCCESS 396全绿。

**部署**：a52365278已合dev-v3并部署。

## 验证证据

上述测试环境已验证的8个场景与单测全绿。

## 十、相关文档

- [Issue #7149](https://git.1814.love:8443/wx/HL/issues/7149)
- [PR #7177](https://git.1814.love:8443/wx/HL/pulls/7177)
- 团期房务方案：docs/group/团期房务实现方案-v1.0.html

## 关联 / 联系人

### 链接

- **Issue**: [#7149](https://git.1814.love:8443/wx/HL/issues/7149)
- **PR**: [#7177](https://git.1814.love:8443/wx/HL/pulls/7177)
- **Merge commit**: [a52365278](https://git.1814.love:8443/wx/HL/commit/a52365278)

### 联系人

- **后端**: @wx
- **前端**: @mmg