docs(changelog-v2): 房务异常标记完成+已确认改已完成+释放/转单修复 (#4312 #4318 #4319)

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）。建议在有房务数据的环境二次确认完整流程。