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

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

⚠️ 关键说明

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

两处需前端配合：

houseStatus 现返房务侧 6 态中文（待配房/配房中/询房中/待最终确认/已确认/异常），不再是旧 2 态；stats 四桶现为真计数（pendingConfirm/exception 不再恒 0）；primaryAction 按 6 态推导。
⚠️ 最终确认（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。

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

5.0 KiB 原始文件 Blame 文件历史 Unescape Escape