changelog: 房务抢单池详情弹窗新增抢单按钮接入说明

changelogs-v2/2026-07/09_房务抢单池详情弹窗新增抢单按钮-前端接入-管理后台.md

@@ -0,0 +1,83 @@
+# 房务抢单池详情弹窗新增「抢单」按钮
+
+> 模块：管理后台 · 房务管家 · 抢单池订单详情弹窗 `/housekeeper/orders`
+> 类型：**前端接入（复用既有后端接口，无需后端发版）**
+> 日期：2026-07-02
+> 背景：房务在抢单池点开订单详情后，目前弹窗底部只有「稍后再说」，需要能在详情中直接抢单，避免关闭弹窗回列表再点。
+
+## 【前端 · 房务管家】需改动
+
+### 1. 详情弹窗底部新增主按钮「抢单」
+
+位置：订单详情弹窗底部右侧，与「稍后再说」并列。
+
+建议按钮：
+
+- 「稍后再说」：保留现有次按钮样式。
+- 「抢单」：新增主按钮，放在「稍后再说」右侧。
+
+### 2. 显示条件
+
+仅当前订单仍在抢单池、未被任何房务领取时显示：
+
+```ts
+const canClaimInDetail =
+  detail?.progress?.houseStatus === 'PENDING_CLAIM' &&
+  !detail?.claim?.claimerId &&
+  !!detail?.requirement?.current?.requirementId
+```
+
+如果不满足条件，不展示「抢单」按钮，避免已被抢/已完成/异常单误操作。
+
+### 3. 点击接口
+
+复用既有抢单接口：
+
+```http
+POST /v3/admin/order/hotel-requirements/{requirementId}/claim
+```
+
+参数来源：
+
+```ts
+const requirementId = detail.requirement.current.requirementId
+```
+
+请求体：无 body。
+
+### 4. 成功后的前端行为
+
+抢单成功后建议按以下顺序处理：
+
+1. toast：`抢单成功`
+2. 关闭详情弹窗，或跳转/刷新到该订单的配房工作台
+3. 刷新抢单池列表
+4. 同步刷新房务首页、我的订单、待处理、日历统计等使用房务状态的页面数据
+
+后端抢单成功后会把需求从抢单池移出，并进入当前房务的「我的订单」。
+
+### 5. 失败处理
+
+并发抢单场景下，后端会按既有错误返回失败。前端直接 toast 后端错误文案，并刷新抢单池列表，防止弹窗停留在过期状态。
+
+常见场景：
+
+| 场景 | 前端处理 |
+|------|----------|
+| 已被其他房务抢走 | toast 后端错误，关闭弹窗或刷新详情 |
+| 当前用户无房务权限 | toast 后端错误 |
+| 需求已不在抢单池 | toast 后端错误，刷新列表 |
+
+## 涉及接口
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/admin/house/orders/{orderId}` | 房务侧订单详情弹窗，读取 `progress.houseStatus`、`claim.claimerId`、`requirement.current.requirementId` |
+| POST | `/v3/admin/order/hotel-requirements/{requirementId}/claim` | 房务抢单，详情弹窗按钮复用该接口 |
+
+## 接入要点
+
+- 不新增后端字段。
+- 不新增后端接口。
+- `requirementId` 不要从列表行缓存硬取，详情弹窗内优先使用 `detail.requirement.current.requirementId`。
+- 点击前可做 loading/防重复提交；接口返回后无论成功失败都建议刷新抢单池列表。