docs(changelog): #8493 下线房务组长会话入口 open-house-lead

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

changelogs-v2/2026-09/30_8493_下线房务组长会话入口-删除接口-管理后台.md

@@ -0,0 +1,245 @@
+---
+schema: "hl-changelog/v2"
+ticket: "8493"
+title: "下线房务组长会话入口 POST /admin/message/chat/open-house-lead"
+consumer: "admin"
+author: "wx(GIT)"
+change_type: "删除接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "测试服 hl-user-service 已部署 eee6d17ef4（PR #8569）。网关实测：open-house-lead 返回 code=404，open-house 与 conversations 均返回 code=200。历史 HOUSE_LEAD 会话数据只读保留，会话列表、消息分页、标记已读三个既有接口按通用逻辑处理，不对 HOUSE_LEAD 做特殊拦截。"
+updated_at: "2026-09-30"
+base: "dev-v3"
+---
+
+# hl-user-service：下线房务组长会话入口 `POST /admin/message/chat/open-house-lead`
+
+> **服务**: hl-user-service (端口 8081)
+> **PR**: #8569（dev-v3 `eee6d17ef4`）
+> **Issue**: #8493
+> **日期**: 2026-09-30
+> **影响范围**: 管理后台「房务组长联系房务」会话入口
+
+---
+
+## ⚠️ 关键变化
+
+🔴 **`POST /admin/message/chat/open-house-lead` 已整体下线**，不再接受任何调用，经网关返回业务码 `404`。这不是临时故障，是本单的预期结果。
+
+🔴 **历史 HOUSE_LEAD 会话不受影响，仍可正常读写。** 只是下线了"新开一条组长会话"的入口；已存在的 `HOUSE_LEAD:{orderId}` 会话在会话列表（`GET conversations`）、消息分页（`GET {conversationKey}/messages`）、标记已读（`POST {conversationKey}/read`）、发消息（`POST {conversationKey}/messages`）四个既有接口上都按通用逻辑处理，后端不做任何额外拦截。前端对这类历史行不要再调 `open-house-lead`（也不要改调其它 `open-*`，那会新建一条会话、找不回历史那条），直接用行上的 `conversationKey` 调上述四个既有接口即可。
+
+---
+
+## 一、背景
+
+`open-house-lead` 原本的用法：房务组长在 `all-claims` 列表里选中一个订单，把该单房务（claimer）的 `adminId` 作为 `peerAdminId` 传入，开一个键为 `HOUSE_LEAD:{orderId}` 的组长↔房务独立会话。#8491 取消了"房务组长"角色、同时删除了 `all-claims` 读口，这个入口从此既没有使用者也没有数据来源，本单据此下线 Controller 方法、Manager 方法、专用请求 VO（`ChatOpenHouseLeadReqVO`）与专用常量（`ChatConstants.BIZ_MODULE_HOUSE_LEAD`、`ROLE_HOUSE_LEAD`、`ConversationKeyUtil.buildHouseOrderLead`）。
+
+`ChatRoleEnum.HOUSE_LEAD`（值「房务组长」）本单**没有**删除：测试服 `peer_role = 'HOUSE_LEAD'` 的历史成员行不为 0，删掉枚举值会让这些历史行的角色徽章从「房务组长」退化成裸码 `HOUSE_LEAD`，故保留该枚举值只用于历史数据回显。
+
+---
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 打开/找回房务组长会话 | POST | `/admin/message/chat/open-house-lead` | 删除 | 接口整体下线；下线前用于开一条组长↔房务订单维度会话 |
+
+---
+
+## 三、接口详情
+
+### 1. 打开/找回房务组长会话（已删除） `POST /admin/message/chat/open-house-lead`
+
+**VO**: `ChatOpenHouseLeadReqVO → Result<ChatOpenFullRespVO>`（请求 VO 已随本单删除；响应类型下线前复用现仍在用的 `ChatOpenFullRespVO`——该类当前的类头注释已注明"组长会话入口 open-house-lead 已由 #8493 下线"）
+
+#### 使用场景
+
+**已下线，不再有使用场景。** 下线前用于「房务组长在 all-claims 列表选中一个订单、为该单房务（claimer）开一条独立组长会话」。#8491 取消组长角色并删除 all-claims 读口后，这个场景已不存在。
+
+#### 入参
+
+**已下线，不再接受任何入参。** 以下是下线前的参数语义（工单 #8493「现状事实」节口径；字段命名与序列化方式对照同结构的 `open-house` 请求 VO——两者均为"雪花 id、JSON 按 String 透传"，仅供核对旧调用代码，不代表下线前 VO 的逐字段校验注解）：
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|------|------|------|------|------|------|
+| orderId | Body | String | 是 | 雪花id，JSON 按 String 透传 | **已下线**。会话维度键 `HOUSE_LEAD:{orderId}` |
+| peerAdminId | Body | String | 是 | 雪花id，JSON 按 String 透传 | **已下线**。该订单房务（claimer）员工id，原由前端从 all-claims 列表传入 |
+
+#### 出参
+
+**已下线，不再有响应体。** 下线前复用现仍在用的 `ChatOpenFullRespVO`（继承 `ChatOpenRespVO` 基类字段）：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| conversationKey | String | **已下线**。规范化会话键，形如 `HOUSE_LEAD:{orderId}` |
+| peerAdminId | Long | **已下线**。对方（房务）员工id |
+| peerName | String | **已下线**。对方姓名快照 |
+| peerRole | String | **已下线**。对方角色，值为 `HOUSE_LEAD` |
+| peerRoleLabel | String | **已下线**。对方角色中文 label，`HOUSE_LEAD` 对应「房务组长」 |
+| order | Object | **已下线**。订单卡 |
+| thread | Object | **已下线**。首屏消息（最新一页 20 条） |
+| unreadTotal | Integer | **已下线**。标记已读后的合并未读总数 |
+
+#### 请求示例
+
+已下线，以下是下线前的请求形态，用来识别调用点：
+
+```json
+{
+  "orderId": "70123",
+  "peerAdminId": "205"
+}
+```
+
+#### 响应示例
+
+**接口已下线，现在的实际响应（测试服经网关实测；HTTP 状态码 200，业务码 `code=404`）：**
+
+```json
+{
+  "code": 404,
+  "message": "接口不存在: POST /admin/message/chat/open-house-lead",
+  "data": null,
+  "traceId": null,
+  "success": false
+}
+```
+
+#### 空数据 / 降级响应
+
+**不适用。** 接口已不存在，不论带什么参数、用哪个账号，响应都与上面相同，没有空数据或降级分支。
+
+#### 错误响应
+
+下线前这个接口没有专属错误码（越权、参数缺失都走通用的 `281005`/`281010` 等，与 `open-house` 共用一套）。现在唯一的响应就是路由未命中：
+
+```json
+{
+  "code": 404,
+  "message": "接口不存在: POST /admin/message/chat/open-house-lead",
+  "data": null,
+  "traceId": null,
+  "success": false
+}
+```
+
+#### 业务边界
+
+- 下线是纯删除：只删了这一个接口，以及只为它存在的请求 VO、Manager 方法、常量、单测；`ChatOpenFullRespVO`、`ChatOpenRespVO` 等公共响应类型未动。
+- 同控制器下的 `open`、`open-house`、`open-fleet`、`open-group`、`open-group-house`、`open-group-fleet` 六个接口本单没有改动，仍可正常调用。
+- 历史 `HOUSE_LEAD:{orderId}` 会话不受影响：数据不删、不迁移，会话列表、消息分页、标记已读、发消息四个既有接口对它们照常放行（详见四、六）。
+- 不要用别的 `open-*` 接口去"找回"历史 HOUSE_LEAD 会话——键前缀不同（`HOUSE_LEAD:` vs `HOUSE:`），会新建一条会话而不是复用旧会话。
+
+---
+
+## 四、契约约束与正确调用方式
+
+- 不要调用 `POST /admin/message/chat/open-house-lead`，也不要重试或做降级兜底：它现在固定返回上面那个 404 响应。
+- 历史 HOUSE_LEAD 会话的正确访问方式：直接用会话列表行上的 `conversationKey`（形如 `HOUSE_LEAD:70123`）去调既有的 `GET /admin/message/chat/{conversationKey}/messages`（分页）、`POST /admin/message/chat/{conversationKey}/read`（已读）、`POST /admin/message/chat/{conversationKey}/messages`（发消息）——这三个端点路径、参数、响应结构本单均未改动。
+- 这三个端点对 HOUSE_LEAD 键走的是**普通会话成员校验**（`ChatMessageService.requireActiveMember`），不是团队会话的 `TeamChatAuthorizationService` 授权分支——因为 `TeamChatModule` 只有 `FLEET`/`GROUP`/`GROUP_HOUSE`/`GROUP_FLEET` 四个团队模块，`HOUSE_LEAD` 不在其中；`assertConversationAccess` 对非团队键统一返回 `null`，放行给调用方原有的成员校验，不会因为组长角色已取消就把这些历史成员判成越权。
+- `GET /admin/message/chat/conversations` 按 `bizModule=HOUSE_LEAD` 过滤仍然可用（服务端不校验 `bizModule` 取值是否在文档列出的枚举里，透传给 Mapper），可用于单独拉出历史组长会话列表。
+- 会话列表返回的 `peerRoleLabel` 字段对 HOUSE_LEAD 行固定是「房务组长」（`ChatRoleEnum.resolveLabel("HOUSE_LEAD")`），前端可直接展示，不需要自己再映射。
+- 会话列表返回的 `orderNo` 字段对 HOUSE_LEAD 行恒为 `null`（不做 order-v3 订单摘要 Feign 富化，与 HOUSE/FLEET 订单维度会话不同），不要用它判断订单归属或做展示兜底。
+
+---
+
+## 五、数据库行为
+
+本单零数据库变更：没有新增 Flyway 脚本，`ai_admin_conversation`（会话）、`ai_admin_conversation_member`（成员）、`ai_admin_message`（消息）三张表结构不动。历史 `HOUSE_LEAD:*` 的会话、成员行、消息行只读保留，不删除、不迁移。接口下线只是不再产生**新的** HOUSE_LEAD 会话，不影响任何已有数据。
+
+---
+
+## 六、边界行为
+
+| 场景 | 行为 |
+|---|---|
+| 调 `POST .../open-house-lead`，不带参数或带任意参数 | 路由未命中，返回上面的 404 响应 |
+| 历史 HOUSE_LEAD 会话调 `GET conversations`（不加 bizModule 过滤） | 正常返回，与其它会话混排，`peerRoleLabel`=「房务组长」 |
+| 历史 HOUSE_LEAD 会话调 `GET conversations?bizModule=HOUSE_LEAD` | 正常返回，只含 HOUSE_LEAD 会话 |
+| 历史 HOUSE_LEAD 会话调 `GET {conversationKey}/messages` | 正常返回，走普通成员校验，不走团队授权 |
+| 历史 HOUSE_LEAD 会话调 `POST {conversationKey}/read` | 正常返回，标记已读到最新 |
+| 历史 HOUSE_LEAD 会话调 `POST {conversationKey}/messages`（发消息） | 正常发送，后端不拦截 |
+| 非该会话成员访问 HOUSE_LEAD 会话 | 返回 `281002`（无权访问该会话），与其它会话一致 |
+
+## 六.5、枚举 / 数据字典
+
+### peerRole / peerRoleLabel（`ChatRoleEnum`）
+
+**所属字段**: `ChatConversationRespVO.peerRole` / `peerRoleLabel`（会话列表出参，`GET /admin/message/chat/conversations`） | **类型**: `String`
+
+本单只涉及 `HOUSE_LEAD` 这一个值——它在下线前是 `open-house-lead` 专属对端角色，下线后仅作为历史数据的回显值继续存在：
+
+| 值 | 中文 | 说明 |
+|----|------|------|
+| `HOUSE_LEAD` | 房务组长 | 历史会话专属，本单起不会再新产生带这个值的会话；`ChatRoleEnum.resolveLabel` 未知码回退原码，故枚举值一旦被删，历史行会退化成显示裸码 `HOUSE_LEAD` 而非中文——本单保留了该枚举值，不会发生这种退化 |
+
+## 六.6、修改前后对比
+
+| 维度 | 改前 | 改后 |
+|---|---|---|
+| `POST /admin/message/chat/open-house-lead` | 路由存在，可新开组长↔房务会话 | 路由不存在，返回 404 |
+| `ChatOpenHouseLeadReqVO` | 存在 | 已删除 |
+| `ChatConstants.BIZ_MODULE_HOUSE_LEAD` / `ROLE_HOUSE_LEAD` | 存在 | 已删除 |
+| `ConversationKeyUtil.buildHouseOrderLead` | 存在 | 已删除 |
+| `ChatRoleEnum.HOUSE_LEAD` 枚举值 | 存在，用于新建会话的对端角色 | 保留，仅用于历史会话回显 |
+| 历史 `HOUSE_LEAD:*` 会话的 conversations/messages/read/发消息 | 可用 | 不变，仍可用 |
+| 网关路由配置 | — | 未改动（`/admin/message/chat/**` 整段转发） |
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**：对历史数据不破坏（只读保留、既有接口照常可用）；对"新开组长会话"这一个操作是破坏性下线，因为它的前置角色和数据来源（#8491）已经不存在。
+- **前端是否必须同步上线**：是——继续调用已下线的 `open-house-lead` 会拿到 404。需要移除的前端调用点见「关联 / 联系人」下方备注。
+- **前端 workaround 清理点**：历史 HOUSE_LEAD 会话若在前端有专属的"打开会话"分支（调 `open-house-lead`），需要改为直接用行上的 `conversationKey` 调 `messages`/`read`；组长发起新会话的入口（原「联系房务」按钮）直接移除，不需要替换成别的接口。
+
+---
+
+## 七、不影响范围
+
+- **仅影响**：`POST /admin/message/chat/open-house-lead` 这一个接口的可用性。
+- **零影响**：
+  - 同控制器下 `open`、`open-house`、`open-fleet`、`open-group`、`open-group-house`、`open-group-fleet`、`conversations`、`{conversationKey}/messages`（GET/POST）、`{conversationKey}/read`、`unread-total` 十个既有接口，均未改动。
+  - 历史 HOUSE_LEAD 会话、成员、消息数据本身：不删除、不迁移。
+  - 网关路由：`/admin/message/chat/**` 整段转发未改动，无需新增或删除路由配置。
+  - 通知收件方配置：`HOUSE_LEAD` 收件方已由 `V20260922_211` 单独清理，与本单无关。
+
+---
+
+## 八、测试环境已验证
+
+- **部署**：hl-user-service 已部署合并提交 `eee6d17ef4`（PR #8569）。
+- **改后实测（经网关）**：
+  - `POST /admin/message/chat/open-house-lead` → HTTP 200，业务码 `code=404`。
+  - `POST /admin/message/chat/open-house` → HTTP 200，业务码 `code=200`（同域保留接口，未受影响）。
+  - `GET /admin/message/chat/conversations` → HTTP 200，业务码 `code=200`。
+
+---
+
+## 十、相关文档
+
+- Issue：https://git.1814.love/wx/HL/issues/8493
+- PR：https://git.1814.love/wx/HL/pulls/8569
+- 前置工单：#8491（取消房务组长角色、删除抢单池读口 `all-claims`）
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#8493](https://git.1814.love/wx/HL/issues/8493)
+- **PR**: [#8569](https://git.1814.love/wx/HL/pulls/8569)
+- **Merge commit**: [eee6d17ef4](https://git.1814.love/wx/HL/commit/eee6d17ef4)
+
+### 联系人
+
+- **后端负责人**: @wx
+
+### 前端需要移除的调用点（hl-ui，`origin/v2.1` 已核实）
+
+- `src/api/chat.js`：`openHouseLead` 接口封装。
+- `src/components/chat/ChatDrawer.vue`：HOUSE_LEAD 分支里调 `open-house-lead` 打开会话的逻辑——改为对 HOUSE_LEAD 行直接用 `conversationKey` 走 `messages`/`read`。
+- `src/views/notification/MyMessages/index.vue`：消息中心按 `row.bizModule` 打开 `ChatDrawer` 时，HOUSE_LEAD 行会走到上面这条分支，需同步调整。
+- `src/views/housekeeper/orders/HouseholdTable.vue`、`src/views/housekeeper/orders/index.vue`：组长「联系房务」入口按钮，直接移除。