diff --git a/changelogs-v2/2026-06/19_4019_房务配房流程顺畅度修复-待最终确认可达+finalize与回执状态闸口+新错误码-行为变更-管理后台.md b/changelogs-v2/2026-06/19_4019_房务配房流程顺畅度修复-待最终确认可达+finalize与回执状态闸口+新错误码-行为变更-管理后台.md new file mode 100644 index 0000000..d6ee286 --- /dev/null +++ b/changelogs-v2/2026-06/19_4019_房务配房流程顺畅度修复-待最终确认可达+finalize与回执状态闸口+新错误码-行为变更-管理后台.md @@ -0,0 +1,107 @@ +# 房务管家·配房流程顺畅度修复(待最终确认可达 + 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 " +# 2. 上传回执(非配房中/询房中/待最终确认态会 808186) +curl -k -X POST "https://api.test.1814.love:9443/admin/house/assignments/requirements/{id}/receipts" \ + -H "Authorization: Bearer " -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 " +``` + +--- + +## 备注 + +- 对外 4 态 requirement_status 不变(已回写 order_main.room_control_status);房务 6 态 roll-up 到对外 4 态。 +- 团期(GROUP)配房先不做,本次仅散客/私人订制。 +- 网关无需改:`/admin/house/assignments/**` 路由已覆盖。