# 房务管家·配房状态升级为房务侧 6 态 + 最终确认强制回执 — 修改接口 — 管理后台

> 变更类型：✨ 功能增强（房务跟单状态 2→6 态 + stats 真计数 + primaryAction 6态）+ ⚠️ **破坏性变更**（最终确认前置强制上传回执）
> 端类型：管理后台（房务管家 → 我的接单列表 + 最终确认）
> 日期：2026-06-18
> 服务：hl-order-service-v3（house 模块）
> PR：https://git.1814.love:8443/wx/HL/pulls/4016 （Closes #4013）

---

## ⚠️ 关键说明

配房状态此前房务列表只产出「配房中/已确认」2 态简化值、`stats` 部分计数恒为 0。本次落地**双层状态模型**：房务侧 6 态（房务操作视图）持久化并暴露，对外 4 态（requirement_status，给定制师/订单）不变。

**两处需前端配合：**

1. **`houseStatus` 现返房务侧 6 态中文**（待配房/配房中/询房中/待最终确认/已确认/异常），不再是旧 2 态；`stats` 四桶现为真计数（`pendingConfirm`/`exception` 不再恒 0）；`primaryAction` 按 6 态推导。
2. **⚠️ 最终确认（finalize）现强制前置回执**：房务点「最终确认」前**必须先经新端点上传至少一张酒店回执**，否则 finalize 返 `808183` 拒绝。这是流程变更，前端需在最终确认前加回执上传步骤。

已部署测试服双实例 health UP，9443 实测：我的接单 200 + stats 结构、回执查询端点 200、Flyway 迁移（house_status 列 + 回执表）经成功查询坐实。

---

## 1. 我的接单 `houseStatus` 升级 6 态

**`GET /v3/admin/order/grab-pool/my-claims/hotel`**（路径不变）

`list[].houseStatus` 取值由 2 态 → **房务侧 6 态中文**：

| houseStatus(中文) | 含义 | 对应 house_status 值 |
|---|---|---|
| 待配房 | 进队列待领（一般不出现在"我的接单"，已领取才入列）| PENDING_CLAIM |
| 配房中 | 已抢、配置中 | CLAIMING |
| 询房中 | 已发询价等酒店回 | IN_INQUIRY |
| 待最终确认 | 所有晚已确认、待回传 | PENDING_FINALIZE |
| 已确认 | 已最终确认回传定制师 | CONFIRMED |
| 异常 | 询房超时/酒店拒单 | EXCEPTION |

`stats` 四桶现为真计数（按 6 态聚合）：`inProgress`=配房中+询房中、`pendingConfirm`=待最终确认、`confirmed`=已确认、`exception`=异常。

`list[].primaryAction` 按 6 态推导（待配房→配房 / 配房中·询房中→继续配房 / 待最终确认→最终确认 / 已确认→查看 / 异常→处理）。

**状态筛选入参 `status`**（不变，4 值）映射到 6 态集合：`inProgress`→配房中+询房中、`pendingConfirm`→待最终确认、`confirmed`→已确认、`exception`→异常。

### 🆕 `house_status` 数据字典（测试服已配）

前端可经 `GET /admin/dict/data/house_status`（或 `/admin/dict/all`）取 6 态 value→label 做筛选/翻译：

| value | label | 样式 |
|---|---|---|
| PENDING_CLAIM | 待配房 | info |
| CLAIMING | 配房中 | primary |
| IN_INQUIRY | 询房中 | warning |
| PENDING_FINALIZE | 待最终确认 | warning |
| CONFIRMED | 已确认 | success |
| EXCEPTION | 异常 | danger |

> 注：这是房务**内部**跟单态字典，与对外的 `requirement_status` 字典（待房务配/配房中/已打回定制师/配房完成）并存、各司其职。

---

## 2. ⚠️ 最终确认强制回执（流程变更）

### 2.1 🆕 上传回执（最终确认前置）

**`POST /admin/house/assignments/requirements/{requirementId}/receipts`**（multipart）

| 参数 | 说明 |
|---|---|
| requirementId(path) | 需求 ID |
| file(form-data) | 回执文件（PDF/图片，≤50MB），字段名 `file` |

响应 `data`：`{ receiptId, requirementId, orderId, fileName, ossUrl, ossKey, fileSize, fileType, createTime }`

### 2.2 🆕 查询回执列表

**`GET /admin/house/assignments/requirements/{requirementId}/receipts`** → `data: [回执VO...]`（无则空数组）

### 2.3 最终确认闸口变更

**`POST /admin/house/assignments/requirements/{requirementId}/finalize`**（路径/入参不变）

新增前置校验：**该需求无任何回执 → 返 `808183`（REQUIREMENT_FINALIZE_NEED_RECEIPT）拒绝**。前端流程需调整为：上传回执（§2.1）→ 再调 finalize。

```bash
# 1. 先传回执
curl -k -X POST "https://api.test.1814.love:9443/admin/house/assignments/requirements/{id}/receipts" \
  -H "Authorization: Bearer <token>" -F "file=@回执.pdf"
# 2. 再最终确认(无回执会 808183)
curl -k -X POST "https://api.test.1814.love:9443/admin/house/assignments/requirements/{id}/finalize" \
  -H "Authorization: Bearer <token>"
```

新错误码：`808183` 最终确认需先上传回执 / `808184` 回执上传失败。

---

## 备注

- 对外 4 态 requirement_status 不变（已回写 order_main.room_control_status）；房务 6 态 roll-up 到对外 4 态。
- 「已完成」态不在房务 6 态内（靠订单行程末日派生）。
- 团期(GROUP)配房先不做，本次仅散客/私人订制。
- 网关无需改：`/v3/admin/order/**` 与 `/admin/house/assignments/**` 路由已覆盖。