changelog(7149): 团期子订单支付后即可提房车需求、物资准备起冻结 589536、团单房型间数必填 582099（PR #7177，Refs #7149）

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XYL5S9SsBtkg7aGyFAbrrQ
2026-09-06 15:58:44 +08:00
@@ -0,0 +1,174 @@
+---
+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. 物料准备中冻结提示：入口置灰或提示「已冻结」
+
+**当前状态**：待前端处理