hl-api-changelog/changelogs-v2/2026-09/06_7149_团期子订单支付后即可提房车需求-物资准备起冻结-团单房型间数必填-修改接口-管理后台.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	7149	团期子订单支付后即可提房车需求、物资准备起冻结、团单房型与间数必填	admin	wx(GIT)	修改接口	deployed	verified	pending	mmg			2026-09-06	后端已合 dev-v3 并部署测试服、网关实测通过；前端需改团期子订单提需求弹窗：房型大类必填+两个新错误码展示+招募中即显示提需求入口。	2026-09-06	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
• PR #7177
• 团期房务方案：docs/group/团期房务实现方案-v1.0.html

关联 / 联系人

链接

• Issue: #7149
• PR: #7177
• Merge commit: a52365278

联系人

• 后端: @wx
• 前端: @mmg