diff --git a/changelogs-v2/2026-09/06_7149_团期子订单支付后即可提房车需求-物资准备起冻结-团单房型间数必填-修改接口-管理后台.md b/changelogs-v2/2026-09/06_7149_团期子订单支付后即可提房车需求-物资准备起冻结-团单房型间数必填-修改接口-管理后台.md new file mode 100644 index 00000000..b88e3812 --- /dev/null +++ b/changelogs-v2/2026-09/06_7149_团期子订单支付后即可提房车需求-物资准备起冻结-团单房型间数必填-修改接口-管理后台.md @@ -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. 物料准备中冻结提示:入口置灰或提示「已冻结」 + +**当前状态**:待前端处理