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

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

⚠️ 关键说明

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

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

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

前置校验顺序：

需求未进入「待最终确认」态（未配齐全部行程晚）→ 808185 需求未进入待最终确认, 请先配齐全部行程晚
该需求无任何回执 → 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)  → 已确认 → 回写订单

# 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/** 路由已覆盖。

5.4 KiB 原始文件 永久链接 Blame 文件历史 Unescape Escape