wx/hl-api-changelog

派生 0

文件

T

API Changelog Bot和Claude Fable 5.1 184ca5ed44

changelog-filename-gate / validate (push) Successful in 2s

详情

changelog(7149): PR #7184 三轮——订单详情 days[].customerSelfBooked 新增字段说明

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Claude-Session: https://claude.ai/code/session_01XYL5S9SsBtkg7aGyFAbrrQ

2026-09-06 17:10:27 +08:00

26 KiB

原始文件 Blame 文件历史

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 并部署测试服、网关实测通过；前端需改团期子订单提需求弹窗：房型大类必填、两个新错误码直接展示 message、招募中即显示提需求入口、物料准备中入口置灰。	2026-09-06	dev-v3

团期模块：子订单支付后即可提房车需求、物资准备起冻结、团单房型与间数必填

服务: hl-order-service-v3 Issue: #7149 PR: #7177（squash 合入 dev-v3 a52365278）、#7184（复审补漏：汇总跳自订晚、团单房数缺失统一 582099）日期: 2026-09-06 影响范围: 管理后台团期子订单详情「住宿安排 / 用车安排」提需求弹窗与「订单调整」提交

⚠️ 关键变化

三条行为改造，请求 / 响应结构一律不变：

支付后即可提需求：团期子订单（详情里 groupOrder=true / productBatchId 非空）在客户已支付（orderStatus=CUSTOMIZING）后即可提 / 改用房、用车需求，团期处于「招募中 RECRUITING」或「资源准备中 RESOURCE_PREPARING」都放行，不再等团期成团。改前团期非 RESOURCE_PREPARING 一律 589501「团期状态不允许当前操作」。
物资准备起冻结：团期进入「物料准备中 MATERIAL_PREPARING」及之后（PENDING_DEPARTURE / TRAVELLING / REVIEWING / SETTLED）提 / 改需求被拒，新错误码 589536「团期已进入物资准备，需求已冻结，请联系团期管理员」（文案里的「物资准备」就是状态芯片的「物料准备中」，同义）。唯一例外：该户该资源最新一版需求被团期管理员打回（REJECTED_TO_CONSULTANT）时可以重提一次，重提后再改仍 589536。团期 CANCELLED / 查不到团期仍 589501。
团单房型大类与房间数必填：团期子订单每个非自订晚（customerSelfBooked 非 true）的每段，按段首候选 candidates[0].rooms[] 逐行要求 roomCategory 非空且 roomCount ≥ 1（旧结构无 rooms[] 时按段级 roomCategory + roomCount 判），缺失返回新错误码 582099「团期订单第{N}晚第{M}段需填写房型大类与房间数」（M 从 1 起），拒绝时零副作用。核心订单不受影响，房型仍选填。团单不再接受「加晚次空白占位」段——每晚要么填齐房型行，要么标 customerSelfBooked=true。

前端要做：① 团期子订单提需求弹窗把「房型大类」改必填并提示；② 589536 / 582099 直接展示后端 message；③ 团期子订单在招募中即显示「提交房型需求 / 用车需求」入口；进入物料准备中后入口置灰或提示已冻结（被打回的户除外）；④ 团单去掉「先提交空白占位」交互。

二、变更接口清单

#	接口	方法	路径	变更类型	说明
1	提交 / 修改用房需求（兼容期 @Deprecated）	PUT	`/v3/admin/order/{id}/hotel-requirement`	行为修改	团期闸门放宽 + 冻结 + 团单房型间数必填
2	订单调整统一提交	POST	`/v3/admin/order/{id}/adjustment/submit`	行为修改	`updates.hotelRequirement` / `updates.vehicleRequirement` 走同一闸门与必填校验
3	提交 / 修改用车需求	PUT	`/v3/admin/order/{id}/vehicle-requirement`	行为修改	团期闸门放宽 + 冻结，不加必填

三、接口详情

1. 提交 / 修改用房需求 `PUT /v3/admin/order/{id}/hotel-requirement`

VO: HotelRequirementReqVO → HotelRequirementRespVO（hl-order-service-v3/src/main/java/com/hulalv/order/requirement/controller/admin/vo/）

使用场景

定制师在子订单详情「住宿安排」提交或修改用房需求。后端按当前生效版本自动分支：无生效版本 → INIT_SUBMIT（新版本）；生效版本为 PENDING / PENDING_REVIEW → PENDING_EDIT（同版本覆盖）；DONE 等 → DONE_ADJUST（版本 +1）。团期子订单新版本状态恒为 PENDING_REVIEW（等团期管理员确认），不进房务抢单池。本端点为兼容期入口（#4515 标 @Deprecated），新客户端走接口 2。

入参

字段	位置	类型	必填	约束	说明
`id`	Path	String(Long)	是	订单 ID	团期子订单 `productBatchId` 非空
`days`	Body	Array	是	长度 = `tripNights`，`dayNumber` 1..tripNights 不重复	逐晚安排
`days[].dayNumber`	Body	Integer	是	1..tripNights	第几晚
`days[].customerSelfBooked`	Body	Boolean	否	`true` = 客人自订	自订晚不校验房型，`segments` 可空
`days[].segments`	Body	Array	非自订晚 ≥1	缺段 582098	当晚分住段
`days[].segments[].candidates`	Body	Array	是（≥1）	候选酒店，房控择一	`hotelId / hotelName` 可空（无酒店候选）
`days[].segments[].candidates[].rooms`	Body	Array	新结构	房型行	团单按 `candidates[0].rooms` 逐行校验
`…rooms[].roomCategory`	Body	String	团单是	字典 `room_category`（STANDARD/SINGLE/TWIN/QUEEN/KING/SUITE/FAMILY/YURT/SPECIAL）	核心订单选填不变
`…rooms[].roomCount`	Body	Integer	团单是，≥1	有行即 >0（582016）	房数
`…rooms[].roomTypeId / roomTypeName / protocolPrice / remark`	Body	Long / String / Decimal / String	否	—	真实房型与快照，可空
`days[].segments[].roomCategory / roomCount`	Body	String / Integer	兼容	旧结构无 `rooms[]` 时团单必填	段级兼容字段
`days[].segments[].budget / remark`	Body	Decimal / String(≤200)	否	预算由后端按协议价覆盖	—
`specialTags`	Body	String[]	否	字典 `house_special_demand`	特殊诉求
`remark`	Body	String(≤500)	否	—	备注

出参 `Result<HotelRequirementRespVO>`

字段	类型	说明
`data.requirementId`	String	需求行 ID
`data.version`	Integer	版本号（INSERT-only 单调递增）
`data.isActive`	Boolean	是否当前生效版本
`data.status`	String	团单恒 `PENDING_REVIEW`；核心为 `PENDING`
`data.submittedAt`	String	首提时间
`data.claimerId / claimerName / claimedAt`	String / String / String	团单恒 null（不进抢单池）
`data.branchTaken`	String	`INIT_SUBMIT / PENDING_EDIT / DONE_ADJUST`
`data.previousVersion`	Integer	`DONE_ADJUST` 时上一版本号，否则 null
`data.assignmentDeletedCount`	Integer	`DONE_ADJUST` 时软删配房行数，否则 null

请求示例

{
  "days": [
    { "dayNumber": 1, "segments": [ { "remark": "第1晚", "candidates": [ { "hotelName": "网关实测酒店", "rooms": [ { "roomTypeName": "测试房型", "roomCategory": "KING", "roomCount": 1 } ] } ] } ] },
    { "dayNumber": 2, "segments": [ { "remark": "第2晚", "candidates": [ { "hotelName": "网关实测酒店", "rooms": [ { "roomTypeName": "测试房型", "roomCategory": "TWIN", "roomCount": 2 } ] } ] } ] }
  ],
  "remark": "#7149 网关实测"
}

响应示例

{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": {
    "requirementId": "2096504560393551873",
    "version": 1,
    "isActive": true,
    "status": "PENDING_REVIEW",
    "submittedAt": "2026-09-06 15:44:21",
    "claimerId": null,
    "claimerName": null,
    "claimedAt": null,
    "branchTaken": "INIT_SUBMIT",
    "previousVersion": null,
    "assignmentDeletedCount": null
  }
}

空数据 / 降级响应

本接口无空列表语义；days 为空数组或长度与 tripNights 不符返回 582011「天数长度与订单住宿晚数不一致」。第 2 晚 customerSelfBooked=true 且无 segments 时正常返回 200（自订晚不进房务分母，团单房型校验跳过）。

错误响应

{ "code": 582099, "message": "团期订单第2晚第1段需填写房型大类与房间数", "success": false, "data": null }

{ "code": 589536, "message": "团期已进入物资准备，需求已冻结，请联系团期管理员", "success": false, "data": null }

其它沿用：589501「团期状态不允许当前操作」（团期 CANCELLED / 查不到）、582098「第{N}晚缺少用房需求，请填写房间需求或标记为客户自订」、582016「房间数必须大于 0」、582019「候选方案必须至少含 1 个房型行」、582017「订单状态不允许提交需求」（未支付）。HTTP 始终 200，错误在 code / message。

业务边界

团期闸门（房车共用）：RECRUITING / RESOURCE_PREPARING 放行；MATERIAL_PREPARING / PENDING_DEPARTURE / TRAVELLING / REVIEWING / SETTLED 及未知状态 589536；CANCELLED / 查不到团期 589501；核心订单不查团期。
冻结期例外：该户用房需求最新一版为 REJECTED_TO_CONSULTANT（团期管理员打回）时放行重提，新版本回到 PENDING_REVIEW；之后再改仍 589536，要再改只能再次被打回。
团单房型间数必填按「段首候选 rooms 行」判，与全团需求汇总 requirement-summary 同口径；旧结构（无 rooms[]）按段级 roomCategory + roomCount 合成一行判。
校验顺序（PR #7184 起）：订单状态（582017）→ 团期闸门（589536 / 589501）→ 晚数匹配（582011）→ 团单房型间数（582099，含房数为空 / 0）→ 通用结构校验（582098 / 582016 / 582019）；任一拒绝均在写库之前，无新版本、room_control_status 不变。核心订单仍以通用结构校验给码（房数 0 → 582016）。
成功后 order_main.room_control_status=PENDING_REVIEW（既有行为），团期成团时定制师不再产生「房型需求 · 待提交」待办。

2. 订单调整统一提交 `POST /v3/admin/order/{id}/adjustment/submit`

VO: AdjustmentSubmitReqVO → AdjustmentSubmitRespVO（hl-order-service-v3/src/main/java/com/hulalv/order/adjustment/controller/admin/vo/）

使用场景

管理端子订单详情「订单调整」一次性提交各子域改动；本次只涉及 updates.hotelRequirement（用房需求完整新版本）与 updates.vehicleRequirement（用车需求完整新版本），两者与接口 1 / 接口 3 走同一团期闸门与团单房型间数校验。其它子域（人数 / 日期 / 出行人等）本次不变、省略。

入参

字段	位置	类型	必填	约束	说明
`id`	Path	String(Long)	是	订单 ID	—
`updates`	Body	Object	是	至少一个子域非空	各子域修改内容
`updates.hotelRequirement`	Body	`HotelRequirementBodyVO`	否	结构同接口 1 的 `days / specialTags / remark`	用房需求完整新版本，团单房型间数必填规则同接口 1
`updates.vehicleRequirement`	Body	`VehicleRequirementBodyVO`	否	结构同接口 3 的 `fleet / specialTags / pickupRequired / dropoffRequired / remark`	用车需求完整新版本

出参 `Result<AdjustmentSubmitRespVO>`

字段	类型	说明
`data.success`	Boolean	提交成功恒 `true`

请求示例

{
  "updates": {
    "hotelRequirement": {
      "days": [
        { "dayNumber": 1, "segments": [ { "candidates": [ { "hotelName": "网关实测酒店", "rooms": [ { "roomCategory": "KING", "roomCount": 1 } ] } ] } ] },
        { "dayNumber": 2, "segments": [ { "candidates": [ { "hotelName": "网关实测酒店", "rooms": [ { "roomCategory": "TWIN", "roomCount": 1 } ] } ] } ] }
      ],
      "remark": "#7149 网关实测 调整入口"
    }
  }
}

响应示例

{ "code": 200, "message": "成功", "success": true, "data": { "success": true } }

空数据 / 降级响应

updates 各子域全空时沿用既有「无有效变更」拒绝；hotelRequirement 提交成功但版本号不变（PENDING_EDIT 覆盖同版本）属正常，前端以订单详情重新拉取为准。

错误响应

{ "code": 589536, "message": "团期已进入物资准备，需求已冻结，请联系团期管理员", "success": false, "data": null }

{ "code": 582099, "message": "团期订单第2晚第1段需填写房型大类与房间数", "success": false, "data": null }

业务边界

调整入口绕过「订单须为定制中」的普通提交闸，但不绕团期闸门与团单房型间数校验，行为与接口 1 / 3 一致。
团期冻结期内该入口同样 589536，被打回户例外同接口 1。
拒绝发生在事务内任何写操作之前，其它子域改动一并回滚。

3. 提交 / 修改用车需求 `PUT /v3/admin/order/{id}/vehicle-requirement`

VO: VehicleRequirementReqVO → VehicleRequirementRespVO（hl-order-service-v3/src/main/java/com/hulalv/order/requirement/controller/admin/vo/）

使用场景

定制师在子订单详情「用车安排」提交或修改用车需求。本次只改团期闸门（放宽 + 冻结 + 打回例外），不加任何必填；车型 / 座位联动校验、容量校验、派单展开等既有逻辑不变。

入参

字段	位置	类型	必填	约束	说明
`id`	Path	String(Long)	是	订单 ID	—
`fleet`	Body	Array	是（≥1）	缺 582021	用车明细
`fleet[].vehicleType`	Body	String	是	车务车型大类 key（582022）	车型大类
`fleet[].seats`	Body	Integer	是	该车型可选座位数（582024）	座位数
`fleet[].count`	Body	Integer	是	>0（582023）	车辆数
`specialTags`	Body	String[]	否	字典 `vehicle_special_demand`（582025）	特殊诉求
`pickupRequired / dropoffRequired`	Body	Boolean	否	—	接 / 送机
`remark`	Body	String	否	—	备注

出参 `Result<VehicleRequirementRespVO>`

字段	类型	说明
`data.requirementId`	String	需求行 ID
`data.version`	Integer	版本号
`data.isActive`	Boolean	是否当前生效版本
`data.status`	String	团单恒 `PENDING_REVIEW`
`data.submittedAt`	String	首提时间
`data.branchTaken`	String	`INIT_SUBMIT / PENDING_EDIT / DONE_ADJUST`

请求示例

{ "fleet": [ { "vehicleType": "SUV", "seats": 7, "count": 1 } ] }

响应示例

{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": { "requirementId": "2096504700000000001", "version": 1, "isActive": true, "status": "PENDING_REVIEW", "submittedAt": "2026-09-06 15:46:02", "branchTaken": "INIT_SUBMIT" }
}

空数据 / 降级响应

fleet 为空返回 582021「用车需求数组不能为空」；车队车型库不可用返回 582091「车队车型库不可用，无法校验座位数选项」（既有降级，本次不变）。

错误响应

{ "code": 589536, "message": "团期已进入物资准备，需求已冻结，请联系团期管理员", "success": false, "data": null }

其它沿用：589501（团期 CANCELLED / 查不到）、582022 / 582024 / 582023 / 582025（车型 / 座位 / 数量 / 诉求校验）。

业务边界

团期闸门与接口 1 完全一致（同一方法），放行 / 冻结 / 打回例外按用车需求自身的最新一版判。
车侧不加房型类必填；fleet 结构与既有校验不变。
成功后 order_main.vehicle_control_status=PENDING_REVIEW（既有行为）。

四、契约约束与正确调用方式（接口类必写）

✅ 正确 / ❌ 错误 payload 对照

场景	payload 要点	结果
✅ 团单每晚房型行齐全	`candidates[0].rooms[]` 每行 `roomCategory` + `roomCount ≥ 1`	200，`status=PENDING_REVIEW`
✅ 团单某晚客人自订	`{ "dayNumber": 2, "customerSelfBooked": true }`，无 `segments`	200，该晚跳过校验
✅ 旧结构团单	无 `rooms[]`，段级 `roomCategory` + `roomCount` 齐全	200
❌ 团单房型行缺 `roomCategory`	`rooms: [ { "roomCount": 1 } ]`	582099
❌ 团单房型行房数为空 / 0	`rooms: [ { "roomCategory": "KING", "roomCount": 0 } ]`	582099（PR #7184 起；核心订单仍 582016）
❌ 团单旧结构缺段级 `roomCategory`	段级只有 `roomCount`，候选带 `roomTypeId`	582099
❌ 团单「加晚次空白占位」段	候选与段全空	582099（核心订单该形态仍放行）
❌ 团期物料准备中提交 / 修改	任何合法 payload	589536（该户最新需求被打回除外）
❌ 子订单未支付	任何 payload	582017「订单状态不允许提交需求」

切换状态时的必要动作

团期从招募中推进到物料准备中后，前端应把提需求入口置灰并以 589536 文案提示；管理员打回某户后该户入口恢复一次。
团单弹窗保存前在前端做房型大类必填校验，减少 582099 往返；后端仍以 582099 兜底。

五、数据库行为（涉及写操作时必写）

无表结构变更、无 Flyway。
提交成功：order_hotel_requirement / order_vehicle_requirement 写入新版本（PENDING_EDIT 为同版本换行，其它版本 +1），status=PENDING_REVIEW；order_main.room_control_status / vehicle_control_status 回写 PENDING_REVIEW（既有行为）。
被拒（589536 / 582099 / 589501 / 结构校验）：无任何写入。

六、边界行为

团单不再接受「加晚次空白占位」段：核心订单允许先提交全空的候选 / 段占位，团期子订单的非自订晚一律按缺房型拒绝（582099「第 N 晚第 M 段」）；团单每晚要么填齐 rooms[]，要么标 customerSelfBooked=true。
文案「物资准备」= 团期状态芯片「物料准备中」（MATERIAL_PREPARING）：589536 文案沿用代码里的「物资准备」叫法，与状态枚举文案同义，前端直接展示 message 即可。
冻结期打回只给一次重提机会：重提后最新版变 PENDING_REVIEW，再改回到 589536；这是有意设计（改需求须经管理员再次打回）。
自订晚：customerSelfBooked=true 的晚不做房型校验；全团汇总 requirement-summary 也整晚跳过（PR #7184 复审补漏），残留 segments/rooms 不计入采购分母、不再出「未知」桶——前端标记自订后仍建议清空该晚 segments，但后端不依赖它。
未知团期状态按冻结处理（fail closed），不会误放行。
错误码优先级变化（PR #7184，核心订单也受影响）：结构校验（582098 / 582016 / 582019 / 582020）从「最先」挪到订单状态（582017）、团期闸门（589536 / 589501）、晚数匹配（582011）、已配房晚改自订（582097）之后；同一请求同时有结构错误和前置错误时，现在先返回前置错误码。前端若按错误码分支提示需按新顺序理解，语义是「更根因的错误优先」。
调整入口同口径（PR #7184）：adjustment/submit 对团期子订单同样先做团单房型间数校验，房数为空 / 0 也返回 582099「第 N 晚第 M 段」，不再先出 582016。
全团汇总某晚全团自订则无该晚条目：dailyRoomBreakdown 按 dayNumber 升序但不保证连续，前端逐日表按 dayNumber 对齐、不要按下标。
子订单详情统计同步（PR #7184）：订单详情 hotelRequirementBrief.totalRoomCount / roomTypeSummary 也不再计入自订晚残留段，与全团汇总一致；该晚仍出现在 days[] 里，并新增响应字段 hotelRequirementBrief.days[].customerSelfBooked（Boolean，纯新增不破坏契约）供前端解释「段里有房型行但不计入总数」。

六.5、枚举 / 数据字典（接口出现枚举时必写）

roomCategory（字典 `room_category`）

值	含义
STANDARD	标准间
SINGLE	单人间
TWIN	双床房
QUEEN	大床房
KING	特大床房
SUITE	套房
FAMILY	家庭房
YURT	帐篷 / 毡房
SPECIAL	特色房

团期状态（`com.hulalv.order.groupbatch.enums.GroupBatchStatus`）

值	芯片文案	提 / 改需求
RECRUITING	招募中	放行
RESOURCE_PREPARING	资源准备中	放行
MATERIAL_PREPARING	物料准备中	589536（打回户例外）
PENDING_DEPARTURE	待出发	589536（打回户例外）
TRAVELLING	出行中	589536（打回户例外）
REVIEWING	核单中	589536（打回户例外）
SETTLED	已结算	589536（打回户例外）
CANCELLED	已取消	589501

需求状态（`com.hulalv.order.requirement.enums.RequirementStatus`，`data.status` / `room_control_status`）

值	含义
PENDING_REVIEW	待团期管理员审核（团单提交后）
REJECTED_TO_CONSULTANT	已打回定制师（冻结期可重提一次）
PENDING / PROCESSING / DONE	核心订单 / 管理员提交房务后的房务侧状态，本次不变

六.6、修改前后对比（修改/删除类接口必写，新增跳过）

字段级对比

请求无字段增删；rooms[].roomCategory、rooms[].roomCount（及旧结构段级同名字段）由「选填」改为「团期子订单必填」，核心订单不变。响应新增 GET /v3/admin/order/{id}（订单详情）hotelRequirementBrief.days[].customerSelfBooked（Boolean，PR #7184）。

行为级对比

行为	修改前	修改后
团期子订单提 / 改需求时机	团期须为 `RESOURCE_PREPARING`（成团后），否则 589501	支付后即可：`RECRUITING / RESOURCE_PREPARING` 放行
团期物料准备及之后	589501	589536（新码，文案明确「已冻结」），最新需求被打回的户可重提一次
团单缺房型大类 / 房数	放行，全团汇总出现「未知」房型	582099 拒绝，零副作用（房数为空 / 0 也是 582099，不再先出 582016；PR #7184）
自订晚残留段进入全团汇总	计入「未知」桶	整晚跳过，不计入（PR #7184）
团单空白占位段	放行	582099 拒绝
用车需求	同 589501 闸	同新闸门，不加必填

六.7、影响评估（修改/删除类必写）

破坏向后兼容：部分——请求 / 响应结构不变，但团单缺房型或空白占位段的旧调用会从 200 变 582099，招募中的调用从 589501 变 200，物料准备中从 589501 变 589536。
前端是否必须同步上线：建议同步——不同步时功能可用但用户会收到 582099 / 589536 提示且入口显示时机不准。
前端需清理的分支：「未成团不显示提需求入口」「物料准备中仍允许提交」「团单空白占位先提交」。

七、不影响范围（显式声明, 帮前端/QA 缩小排查面）

核心订单（productBatchId 为空）的提需求、房型选填、抢单池、房务配房全部不变。
团期管理员确认 / 打回 / 提交房务（…/hotel-requirement/reject、…/dispatch、group-batch/{groupBatchId}/requirement/*）本次不改；打回后重提的版本号规则不变。
GET /v3/admin/order/group-batch/{groupBatchId}/requirement-summary 结构不变，只是按本次提交的团单不再出现 roomCategory="未知" 项（历史数据仍可能出现）。
网关路由、权限码、表结构均无改动。

八、测试环境已验证

环境：TEST 网关 https://api.test.1814.love:9443，order-v3 dev-v3 a52365278 两实例 2026-09-06 15:43 滚动部署，登录 admin（adminId 1001，SUPER_ADMIN，且为两张测试单的定制师），实测 15:44–15:47。

场景	请求	结果
招募中（`RECRUITING`）子订单 2096412454488612866 提完整房型	`PUT …/hotel-requirement`	200，`status=PENDING_REVIEW`
招募中，第 2 晚房型行缺 `roomCategory`	`PUT …/hotel-requirement`	582099「团期订单第2晚第1段需填写房型大类与房间数」，DB 无新版本
招募中，旧结构段级缺 `roomCategory`（候选带 `roomTypeId`）	`PUT …/hotel-requirement`	582099，同上
资源准备中完整提交	`PUT …/hotel-requirement`	200，`version=1 INIT_SUBMIT PENDING_REVIEW`；`order_main.room_control_status=PENDING_REVIEW`
资源准备中经调整入口改需求	`POST …/adjustment/submit`	200，`data.success=true`（同版本 `PENDING_EDIT` 换行）
第 2 晚 `customerSelfBooked=true` 无段	`PUT …/hotel-requirement`	200
团期 2089713777065832450 子订单 2096029450184347649 资源准备中提交	`PUT …/hotel-requirement`	200
团期管理员打回该户	`POST …/hotel-requirement/reject`	200，需求行 `REJECTED_TO_CONSULTANT`、`is_active=0`
团期改为 `MATERIAL_PREPARING` 后被打回户重提	`PUT …/hotel-requirement`	200，`version=2 PENDING_REVIEW`（冻结期例外）
重提后再改	`PUT …/hotel-requirement`	589536「团期已进入物资准备，需求已冻结，请联系团期管理员」
物料准备中经调整入口改需求	`POST …/adjustment/submit`	589536
物料准备中提用车需求	`PUT …/vehicle-requirement`	589536

单测：RequirementServiceTest 244 / OrderTodoServiceTest 15 / RequirementGroupBatchErrorCodeRangeTest 3 + 5 个 ArchTest（RedLine / MapperBoundary / HouseModuleBoundary / DashboardLayer / LocalCacheVetting）全绿，BUILD SUCCESS 396 用例。

十、相关文档

团期模块接口文档 docs/group/团期模块接口文档-v2.0.html §0C.11.1（提需求时机）/ §0C.11.2（房型间数必填）/ GB-ADM-011：https://web.test.1814.love:9443/hl-docs/group/
团期房务实现方案 docs/group/团期房务实现方案-v1.0.html §3.12.1 / §3.12.2
后续工单（本次不做）：管理员确认 / 打回改造（M1 / M2）、房务团期看板与按日订房、定制师 ↔ 团期管理员站内会话

26 KiB 原始文件 Blame 文件历史 Unescape Escape

团期模块：子订单支付后即可提房车需求、物资准备起冻结、团单房型与间数必填

⚠️ 关键变化

二、变更接口清单

三、接口详情

1. 提交 / 修改用房需求 PUT /v3/admin/order/{id}/hotel-requirement

使用场景

入参

出参 Result<HotelRequirementRespVO>

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

2. 订单调整统一提交 POST /v3/admin/order/{id}/adjustment/submit

使用场景

入参

出参 Result<AdjustmentSubmitRespVO>

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

3. 提交 / 修改用车需求 PUT /v3/admin/order/{id}/vehicle-requirement

使用场景

入参

出参 Result<VehicleRequirementRespVO>

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

四、契约约束与正确调用方式（接口类必写）

✅ 正确 / ❌ 错误 payload 对照

切换状态时的必要动作

五、数据库行为（涉及写操作时必写）

六、边界行为

六.5、枚举 / 数据字典（接口出现枚举时必写）

roomCategory（字典 room_category）

团期状态（com.hulalv.order.groupbatch.enums.GroupBatchStatus）

需求状态（com.hulalv.order.requirement.enums.RequirementStatus，data.status / room_control_status）

六.6、修改前后对比（修改/删除类接口必写，新增跳过）

字段级对比

行为级对比

六.7、影响评估（修改/删除类必写）

七、不影响范围（显式声明, 帮前端/QA 缩小排查面）

八、测试环境已验证

十、相关文档

关联 / 联系人

链接

联系人

26 KiB

原始文件 Blame 文件历史

1. 提交 / 修改用房需求 `PUT /v3/admin/order/{id}/hotel-requirement`

出参 `Result<HotelRequirementRespVO>`

2. 订单调整统一提交 `POST /v3/admin/order/{id}/adjustment/submit`

出参 `Result<AdjustmentSubmitRespVO>`

3. 提交 / 修改用车需求 `PUT /v3/admin/order/{id}/vehicle-requirement`

出参 `Result<VehicleRequirementRespVO>`

roomCategory（字典 `room_category`）

团期状态（`com.hulalv.order.groupbatch.enums.GroupBatchStatus`）

需求状态（`com.hulalv.order.requirement.enums.RequirementStatus`，`data.status` / `room_control_status`）