diff --git a/changelogs-v2/2026-06/23_4312_4318_4319_房务异常标记完成+已确认改已完成+释放转单修复_管理后台.md b/changelogs-v2/2026-06/23_4312_4318_4319_房务异常标记完成+已确认改已完成+释放转单修复_管理后台.md new file mode 100644 index 0000000..fcc78a4 --- /dev/null +++ b/changelogs-v2/2026-06/23_4312_4318_4319_房务异常标记完成+已确认改已完成+释放转单修复_管理后台.md @@ -0,0 +1,49 @@ +# 房务配房:异常态加「标记完成」终态 + 「已确认」文案统一改「已完成」 + 释放/转单弹窗 body 必填 400 修复 + +> 变更类型:✅ 新增接口 + 🔧 修复(已部署测试服;契约层已 round-trip 实测,数据依赖行为见下「验证说明」) +> 端类型:管理后台(房务管家·订单详情/异常桶/转单·释放弹窗) +> 日期:2026-06-23 | 工单:#4307 #4315 #4317 | PR:#4312 #4318 #4319 | 服务:hl-order-service-v3 / hl-user-service +> 关联:承接 #4301(房务状态机修复)的 P1 设计项;本批多为房务侧体验修复。 + +--- + +## 一、需要前端动手的 + +### 1. 异常态加「标记完成」按钮(新增端点)✅契约已实测 +房务 6 态里「异常」原本没有「处置完成」出口(取消单/放弃单永卡异常)。现新增统一终态出口。 + +- **端点**:`POST /v3/admin/order/hotel-requirements/{requirementId}/close` +- **body**:可空。可选 `{"reason":"异常已处置"}`(reason 选填,≤200 字)。 +- **成功**:`house_status` → `CONFIRMED`(label =「已完成」)。 +- **前置**:仅 `house_status == EXCEPTION` 可调;非异常态返 **808022「当前房务状态非异常,不可标记完成」**;需求不存在返 808002。 +- **前端**:异常桶/订单详情,当 `houseStatus==EXCEPTION` 时显示「标记完成」按钮 → 调本端点 → 成功后该单进「已完成」。 + +### 2. 房务终态文案:「已确认」→「已完成」 +房务侧 `CONFIRMED` 态的中文 label 由「已确认」统一改为「已完成」(配房回传完成 与 异常处置完成 都落这个终态)。 +- 后端 `houseStatusLabel` / 进度条 step5 等已返「已完成」。 +- **前端**:若有**硬编码**「已确认」字样(房务终态徽章/进度条/筛选 Tab)需同步改「已完成」;若直接用后端返回的 label 则无需改。 + +--- + +## 二、后端已修复 / 行为变化(前端一般无需改,知会) + +### 3. 释放/转单确认弹窗 body 必填 400 — 已修复 ✅实测 +之前「确认释放」「确认转单」弹窗不带 body 时后端报 `400 Required request body is missing`。 +- 现 `release` / `close` 端点 body 改可选;`release/close/transfer` 的 `reason` 改可选(reason 留空后端兜底)。 +- `transfer` 的 `toUserId` 仍必填;超管指派 reason≥10 字校验保留。 +- **前端无需改**:原来不传 body 的调用现在不再 400。 + +### 4. 转单候选去企微强制过滤(纯后端) +「转单/指派」候选「选择目标房务」原只返回**已绑企微**的房务,导致未绑企微账号不显示、下拉「无数据」。现改为按**房务角色**(house_keeper/house_lead,多角色感知)+ 活跃查,**企微可选**(未绑企微者名字回落用户名)。 +- **前端无需改**。 +- 注意:候选仍要求环境里有除自己外、持房务角色、活跃的账号;若仍空请确认环境已给测试账号分配 house_keeper/house_lead 角色。 + +### 5. 释放回池后会话消息转「留言」+ 重抢转发(纯后端) +房务释放回池后,原房务↔定制师的会话消息退回「留言池」(抢单前留言态);之后别的房务再抢单时,这些留言会转发给新房务(计入未读 + SSE)。 +- **前端无需改**:沿用现有「内部留言框」/未读展示,行为自然生效。 + +--- + +## 验证说明(如实) +- ✅ **测试服 round-trip 实测通过**:`release` / `close` 端点已上线、body 可空(无 body 调用返业务码而非 `Required request body is missing` 400)、`/close` 已路由(非 404)。 +- ⚠️ **数据依赖行为未在测试服演示**:测试服当前无房务订单/房务角色账号,故「候选有数据」「异常单标记完成→已完成」「释放后留言转发」三项**完整业务流程**未在测试服跑通演示;均已被后端**单元测试覆盖**且已部署(hl-order-service-v3 双实例 8086/8186、hl-user-service 双实例 8081/8181 health UP)。建议在有房务数据的环境二次确认完整流程。