---
schema: "hl-changelog/v2"
ticket: "7149"
title: "团期子订单支付后即可提房车需求、物资准备起冻结、团单房型与间数必填"
consumer: "admin"
author: "wx(AI)"
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**；唯一例外：若最新版需求被团期管理员打回（REJECTED_TO_CONSULTANT），该户该资源仍可重提一次。
3. **房型与间数必填**：团期子订单的每个非自订晚（customerSelfBooked 非 true）的每段，房型大类（roomCategory）与房间数（roomCount）必填且大于等于1。新增错误码 **582099**；核心订单无此约束。

## 变更接口

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

## 接口详情

### 1. 提交修改房型需求 PUT /v3/admin/order/orderId/hotel-requirement

**VO**: HotelRequirementReqVO 转 HotelRequirementRespVO

**替代状态**: Deprecated 兼容期；新入口为 POST /v3/admin/order/orderId/adjustment/submit 中的 updates.hotelRequirement。

#### 使用场景

定制师提交修改调整房型需求；后端按是否存在 active 行与当前状态自动三分支：无 active 转 INIT_SUBMIT、PENDING 转 PENDING_EDIT、DONE 转 DONE_ADJUST。

#### 团期子订单的权限守卫（新增）

**允许提交条件**：
- 订单是团期子订单（product_batch_id 非空）
- 订单已支付（orderStatus=CUSTOMIZING）
- 团期状态为 RECRUITING 或 RESOURCE_PREPARING
- 返回 code=200，data.status 为对应状态

**拒绝条件**：
- 团期状态为 MATERIAL_PREPARING 及之后→code=589536、消息「团期已进入物资准备，需求已冻结，请联系团期管理员」
- 例外：最新版需求被打回（REJECTED_TO_CONSULTANT）时可重提一次
- 团期状态为 CANCELLED 或不存在→code=589501
- 核心订单（product_batch_id 为空）不受本守卫

#### 房型与间数必填校验（新增，仅团期子订单）

**触发**：PUT /v3/admin/order/orderId/hotel-requirement 或 POST /v3/admin/order/orderId/adjustment/submit 的 updates.hotelRequirement

**校验口径**：
- 逐晚判断：非自订晚（customerSelfBooked 非 true）的每个 segment
- 逐段判断：取首个候选 candidates[0] 的房型行
- 新结构（candidates[0].rooms 非空）：逐行判 roomCategory 非空且 roomCount 大于 0
- 旧结构（无 rooms）：按段级 roomCategory 加段级 roomCount 合成单行判

**拒绝响应**（新错误码 582099）：返回消息「团期订单第 N 晚第 M 段需填写房型大类与房间数」，其中 N 为日期号，M 为段号。

### 2. 调整订单统一提交 POST /v3/admin/order/orderId/adjustment/submit

**VO**: AdjustmentSubmitReqVO 转 AdjustmentSubmitRespVO

**权限守卫**（新增）：
- 房、车需求提交通过同一闸门：团期 RECRUITING 或 RESOURCE_PREPARING 允许，MATERIAL_PREPARING 及之后冻结（589536）
- 房型间数必填：同 PUT /hotel-requirement 的 582099 校验

### 3. 提交修改用车需求 PUT /v3/admin/order/orderId/vehicle-requirement

**VO**: VehicleRequirementReqVO 转 VehicleRequirementRespVO

**权限守卫**（新增）：
- **允许**：团期 RECRUITING 或 RESOURCE_PREPARING，已支付子订单可提
- **拒绝**：团期 MATERIAL_PREPARING 及之后→code=589536；团期 CANCELLED 或不存在→code=589501

## 契约约束与调用对照

1. **房型间数必填（582099）**：应用范围是团期子订单（product_batch_id 非空）的非自订晚；核心订单房型仍选填。

2. **冻结与例外（589536）**：冻结触发为团期进入 MATERIAL_PREPARING 及之后；例外为最新版需求被打回（status=REJECTED_TO_CONSULTANT），允许重提一次；重提后再改仍返 589536。

3. **错误响应总览**：

| 错误码 | 场景 | 说明 |
|---|---|---|
| 200 | 成功 | 新版本持久化 |
| 589536 | 冻结 | 团期 MATERIAL_PREPARING 及之后，非打回例外户 |
| 589501 | 团期不存在或已取消 | 团期状态完全不允许操作 |
| 582099 | 房型间数缺失 | 团期子订单非自订晚缺 roomCategory 或 roomCount |

## 数据库行为

- 无表结构变更
- 提交成功时 order_hotel_requirement 新版本 status=PENDING_REVIEW、version 递增
- 冻结拒绝时零副作用：不写版本、不写状态、不修改任何表

## 边界行为

- **自订晚处理**：customerSelfBooked=true 的晚允许 segments 为空，不受房型间数必填约束
- **打回例外**：被打回后可重提一次，重提时进入 PENDING_REVIEW 状态；重提后再改仍返 589536
- **旧客户端兼容**：rooms 为空时回退到段级 roomCategory 加 roomCount
- **团期状态枚举**：RECRUITING 或 RESOURCE_PREPARING 允许，MATERIAL_PREPARING 及之后冻结，CANCELLED 拒绝

## 不影响范围

- 核心订单（product_batch_id 为空）房型仍选填
- 其他接口（提房务、车务、配房、配车、抢单等）逻辑不变
- Flyway 无迁移脚本；DB 表结构无变更

## 验证证据

**环境**：TEST 服务器，2026-09-06 15:44，登录 admin/1001

**测试覆盖**：
- 招募中子订单提房型需求→code=200, status=PENDING_REVIEW 检查通过
- 房型缺失→code=582099，消息提示具体日期和段号 检查通过
- 旧结构房型间数缺失→code=582099 检查通过
- 资源准备中可提→code=200, status=PENDING_REVIEW 检查通过
- 物料准备中冻结→code=589536，消息「团期已进入物资准备，需求已冻结」检查通过
- 被打回户在冻结期可重提一次→code=200, version=2 检查通过
- 重提后再改仍冻结→code=589536 检查通过
- 用车需求同样冻结→code=589536 检查通过
- 自订晚不受约束→code=200 检查通过

**单测覆盖**：
- RequirementServiceTest：244 用例 检查通过
- OrderTodoServiceTest：15 用例 检查通过
- RequirementGroupBatchErrorCodeRangeTest：3 用例 检查通过
- ArchTest：5 用例 检查通过
- BUILD SUCCESS：396 用例全绿 检查通过

**部署**：提交 a52365278 合 dev-v3，测试服已部署，网关实测通过

## 相关文档与链接

- Issue #7149：https://git.1814.love:8443/wx/HL/issues/7149
- PR #7177：https://git.1814.love:8443/wx/HL/pulls/7177
- 实现：提交 a52365278
- 团期房务方案：docs/group/团期房务实现方案-v1.0.html
- 团期接口文档：docs/group/团期模块接口文档-v2.0.html

## 前端动作与当前状态

**需要前端修改**（hl-ui，mmg 负责）：

1. 房型大类改必填：团期子订单提需求弹窗中房型大类字段标必填
2. 两个新错误码展示：589536 与 582099 直接展示后端 message 文案
3. 招募中即显示提需求入口：不再等待成团
4. 物料准备中冻结提示：入口置灰或提示「已冻结」

**当前状态**：待前端处理