API Changelog Bot和Claude Fable 5.1
c1d7fed7b6
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XYL5S9SsBtkg7aGyFAbrrQ
282 行
11 KiB
Markdown
282 行
11 KiB
Markdown
---
|
||
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
|