hl-api-changelog/changelogs-v2/2026-07/29_4777_房务清空配房信息与驳回按钮动作契约-前端待处理-管理后台.md

房务清空配房信息与驳回按钮动作契约

• 工单：HL #4777
• 状态：front-end todo
• 影响端：管理后台房务详情弹窗 / 订单详情行程安排住宿卡片

背景

已有配房的住宿需求不能直接驳回。后端驳回接口已拦截 active 配房，但前端仍在已有配房时展示可点击的“驳回需求”，导致页面看起来像还能驳回。

本次后端补齐详情动作字段和清空配房接口，前端按后端 actions 渲染按钮，不再自行用流程状态猜测。

新增接口

清空当前生效需求全部配房：

DELETE /v3/admin/order/hotel-requirements/{requirementId}/assignments

响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "clearedCount": 2
  }
}

语义：

• 清空当前生效需求下全部 active 配房行。
• 级联清空房间分配并释放已扣库存。
• 不释放抢单人，不回抢单池，仍由当前房务继续处理。
• 清空成功后刷新订单详情。

详情动作字段

订单详情 actions 新增：

{
  "canRejectRequirement": {
    "enabled": false,
    "code": "REJECT_REQUIREMENT",
    "label": "驳回需求",
    "disabledReason": "已有配房, 不能驳回, 请先清空/删除配房",
    "endpoint": "POST /v3/admin/order/{orderId}/hotel-requirement/supplier-reject"
  },
  "canClearAssignments": {
    "enabled": true,
    "code": "CLEAR_ASSIGNMENTS",
    "label": "清空配房",
    "disabledReason": null,
    "endpoint": "DELETE /v3/admin/order/hotel-requirements/{requirementId}/assignments"
  }
}

requirement.actions 同步新增布尔字段：

{
  "canRejectRequirement": false,
  "canClearAssignments": true
}

前端渲染要求

1. 有任意 active 配房时，canRejectRequirement.enabled=false，不要展示可点击“驳回需求”。
2. canClearAssignments.enabled=true 时展示“清空配房”按钮。
3. 点击“清空配房”调用新增 DELETE 接口，成功后刷新详情。
4. 清空后如果后端返回 canRejectRequirement.enabled=true，再允许填写驳回原因并调用驳回接口。
5. 已驳回需求只读展示，不允许修改、删除、配房、替换、最终确认。

验收

• 已配房两晚：驳回按钮隐藏或置灰；清空配房按钮可用。
• 清空成功：配房行消失，状态从待最终确认回到配房中，驳回按钮按详情刷新结果变更。
• 无配房：清空按钮隐藏或置灰；驳回按钮按后端 action 显示。

2026-07-07 补充：每个行程日都要有清空按钮

• 补充工单：HL #4804
• 状态：front-end todo
• 后端接口：已补按天清空，整体清空接口保留为批量动作。

新增按天清空接口

只清空当前生效需求某一天的 active 配房：

DELETE /v3/admin/order/hotel-requirements/{requirementId}/assignments/days/{dayNumber}

响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "clearedCount": 1
  }
}

语义：

• 只清空 {dayNumber} 当天 active 配房行，不影响其他天。
• 级联清空当天房间分配。
• 只释放实际扣过资源库存的配房行；deductInventory=false 的配房快照不释放库存。
• 不释放抢单人，不回抢单池。
• 清空成功后刷新订单详情；该天应回到待配房，其他天保持原配房状态。

前端渲染要求

1. 在每个行程 day 行展示“清空”按钮；不能只在弹窗底部放整体清空。
2. 当 itinerary[].assignments 非空时，该 day 的“清空”按钮可用。
3. 点击 day 行“清空”时调用新增按天清空接口： DELETE /v3/admin/order/hotel-requirements/{requirementId}/assignments/days/{dayNumber}。
4. 清空前仍需要二次确认，文案要说明“只清空第 N 晚配房，不影响其他晚”。
5. 底部整体“清空配房”可保留，但语义必须是清空当前需求全部天；不要替代 day 行清空按钮。

补充验收

• 两晚订单第 1 晚、第 2 晚都有独立“清空”按钮。
• 清空第 1 晚后，第 1 晚回到待配房，第 2 晚配房仍保留。
• 清空不扣系统库存的配房时，不应释放资源库存。