docs: 告知前端房务清空配房动作契约

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

@@ -0,0 +1,84 @@
+# 房务清空配房信息与驳回按钮动作契约
+
+- 工单：HL #4777
+- 状态：front-end todo
+- 影响端：管理后台房务详情弹窗 / 订单详情行程安排住宿卡片
+
+## 背景
+
+已有配房的住宿需求不能直接驳回。后端驳回接口已拦截 active 配房，但前端仍在已有配房时展示可点击的“驳回需求”，导致页面看起来像还能驳回。
+
+本次后端补齐详情动作字段和清空配房接口，前端按后端 actions 渲染按钮，不再自行用流程状态猜测。
+
+## 新增接口
+
+清空当前生效需求全部配房：
+
+```http
+DELETE /v3/admin/order/hotel-requirements/{requirementId}/assignments
+```
+
+响应：
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": {
+    "clearedCount": 2
+  }
+}
+```
+
+语义：
+
+- 清空当前生效需求下全部 active 配房行。
+- 级联清空房间分配并释放已扣库存。
+- 不释放抢单人，不回抢单池，仍由当前房务继续处理。
+- 清空成功后刷新订单详情。
+
+## 详情动作字段
+
+订单详情 `actions` 新增：
+
+```json
+{
+  "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` 同步新增布尔字段：
+
+```json
+{
+  "canRejectRequirement": false,
+  "canClearAssignments": true
+}
+```
+
+## 前端渲染要求
+
+1. 有任意 active 配房时，`canRejectRequirement.enabled=false`，不要展示可点击“驳回需求”。
+2. `canClearAssignments.enabled=true` 时展示“清空配房”按钮。
+3. 点击“清空配房”调用新增 DELETE 接口，成功后刷新详情。
+4. 清空后如果后端返回 `canRejectRequirement.enabled=true`，再允许填写驳回原因并调用驳回接口。
+5. 已驳回需求只读展示，不允许修改、删除、配房、替换、最终确认。
+
+## 验收
+
+- 已配房两晚：驳回按钮隐藏或置灰；清空配房按钮可用。
+- 清空成功：配房行消失，状态从待最终确认回到配房中，驳回按钮按详情刷新结果变更。
+- 无配房：清空按钮隐藏或置灰；驳回按钮按后端 action 显示。