docs(changelog): 房务配房状态升级6态+最终确认强制回执(#4013/PR#4016)

changelogs-v2/2026-06/18_4013_房务配房状态升级6态+最终确认强制回执-修改接口-管理后台.md

@@ -0,0 +1,103 @@
+# 房务管家·配房状态升级为房务侧 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/**` 路由已覆盖。