# 房务管家·配房流程顺畅度修复（待最终确认可达 + finalize/回执状态闸口 + 新错误码）— 行为变更 — 管理后台

> 变更类型：🔧 行为变更（修复 #4013 落地后的流程衔接缺口，使房务 6 态流转闭环顺畅）
> 端类型：管理后台（房务管家 → 我的接单 / 最终确认 / 回执上传）
> 日期：2026-06-19
> 服务：hl-order-service-v3（house 模块）
> PR：https://git.1814.love:8443/wx/HL/pulls/4027 （Closes #4019）
> 承接：本次是 [#4013 房务 6 态 + 强制回执](18_4013_房务配房状态升级6态+最终确认强制回执-修改接口-管理后台.md) 的流程顺畅度修复，**端点路径/入参/出参均不变**，仅状态流转与前置校验更严谨。

---

## ⚠️ 关键说明

#4013 落地了房务 6 态 + 最终确认强制回执，但状态流转有 4 处衔接缺口（待最终确认态实际不可达、finalize 不校验状态、回执可任意态上传、驳回不清房务态）。本次全部修复，使「配房中 → 待最终确认 → 最终确认」闭环真正跑通。

**前端需关注 3 点（均为行为收紧，happy-path 不变）：**

1. **「待最终确认」现在真的会出现**：房务把**所有行程晚都配齐且无在途询价**后，需求自动进入「待最终确认」（`PENDING_FINALIZE`），`stats.pendingConfirm` 不再恒 0。之前会一直停在「配房中/询房中」。
2. **最终确认（finalize）现要求先到「待最终确认」态**：未配齐全部行程晚就调 finalize → 返 **`808185`**（在原「无回执 `808183`」之上新增的前置闸口）。
3. **回执上传现按状态放行**：仅「配房中/询房中/待最终确认」可上传回执，其它状态 → 返 **`808186`**。

已部署测试服双实例 health UP，9443 实测：我的接单 200、house_status 字典 6 态、登录链路正常。

---

## 1. 「待最终确认」态现在可达（核心行为变更）

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

房务提交配房结果时，后端按「是否已配齐全部行程晚 + 无在途询价」自动判定下一态：

| 提交时情形 | 流转结果 | houseStatus |
|---|---|---|
| 全部行程晚已确认、无在途询价 | 进入待最终确认 | 待最终确认（PENDING_FINALIZE）|
| 仍有未配晚 / 有在途询价 | 维持配房中 | 配房中（CLAIMING）|

> 影响：我的接单列表 `houseStatus` 现会出现「待最终确认」，`stats.pendingConfirm` 为真计数；前端「最终确认」按钮应在该态下才高亮可点。

---

## 2. 最终确认 / 回执上传前置闸口收紧

### 2.1 最终确认新增状态闸口（808185）

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

前置校验顺序：

1. 需求未进入「待最终确认」态（未配齐全部行程晚）→ **`808185` 需求未进入待最终确认, 请先配齐全部行程晚**
2. 该需求无任何回执 → `808183` 最终确认前必须上传至少一张回执（#4013 已有）

> happy-path 不变：配齐所有晚（自动转待最终确认）→ 上传回执（§2.2）→ finalize。

### 2.2 回执上传新增状态闸口（808186）

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

仅「配房中 / 询房中 / 待最终确认」可上传回执；其它状态（如待配房/已确认/异常）→ **`808186` 当前状态不允许上传回执**。

---

## 3. 驳回清房务态（内部一致性）

定制师驳回需求（`reject`）时，后端同步把 `house_status` 清空，使该需求回到「待房务配」初始语义，房务重新抢单后从「配房中」干净起步（避免残留旧态）。前端无需改动。

---

## 新增错误码汇总

| 错误码 | 含义 | 触发 |
|---|---|---|
| 808185 | 需求未进入待最终确认, 请先配齐全部行程晚 | finalize 时全部行程晚未配齐 |
| 808186 | 当前状态不允许上传回执 | 在非「配房中/询房中/待最终确认」态上传回执 |

> 808183（最终确认前必须上传回执）为 #4013 已有，本次不变。

---

## 完整 happy-path（前端流程参考）

```
抢单成功(配房中)
  → [发询价(询房中) → 酒店回复]
  → 配齐全部行程晚 + 无在途询价  → 自动进入「待最终确认」
  → 上传酒店回执(§2.2)
  → 最终确认 finalize(§2.1)  → 已确认 → 回写订单
```

```bash
# 1. 配齐后提交（自动转待最终确认）
curl -k -X POST "https://api.test.1814.love:9443/admin/house/assignments/requirements/{id}/submit" \
  -H "Authorization: Bearer <token>"
# 2. 上传回执（非配房中/询房中/待最终确认态会 808186）
curl -k -X POST "https://api.test.1814.love:9443/admin/house/assignments/requirements/{id}/receipts" \
  -H "Authorization: Bearer <token>" -F "file=@回执.pdf"
# 3. 最终确认（未到待最终确认会 808185；无回执会 808183）
curl -k -X POST "https://api.test.1814.love:9443/admin/house/assignments/requirements/{id}/finalize" \
  -H "Authorization: Bearer <token>"
```

---

## 备注

- 对外 4 态 requirement_status 不变（已回写 order_main.room_control_status）；房务 6 态 roll-up 到对外 4 态。
- 团期(GROUP)配房先不做，本次仅散客/私人订制。
- 网关无需改：`/admin/house/assignments/**` 路由已覆盖。