From 2bce6cb8eafaf263767ed7cd25dcb583f78cb880 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Wed, 30 Sep 2026 00:44:55 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20#8493=20=E4=B8=8B=E7=BA=BF?= =?UTF-8?q?=E6=88=BF=E5=8A=A1=E7=BB=84=E9=95=BF=E4=BC=9A=E8=AF=9D=E5=85=A5?= =?UTF-8?q?=E5=8F=A3=20open-house-lead?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5.5 (1M context) --- ..._下线房务组长会话入口-删除接口-管理后台.md | 245 ++++++++++++++++++ 1 file changed, 245 insertions(+) create mode 100644 changelogs-v2/2026-09/30_8493_下线房务组长会话入口-删除接口-管理后台.md diff --git a/changelogs-v2/2026-09/30_8493_下线房务组长会话入口-删除接口-管理后台.md b/changelogs-v2/2026-09/30_8493_下线房务组长会话入口-删除接口-管理后台.md new file mode 100644 index 00000000..202b710d --- /dev/null +++ b/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`（请求 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`：组长「联系房务」入口按钮，直接移除。