wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 工作流 软件包 项目 发布 百科 活动
文件
main
hl-api-changelog/changelogs-v2/2026-09/30_8493_下线房务组长会话入口-删除接口-管理后台.md
T
Mimingguang 5933096d07
changelog-filename-gate / validate (push) Failing after 2s
详情
chore(8493): 回写前端交付 implemented(hl-admin 8c9f7bc5)
2026-09-30 14:30:36 +08:00

15 KiB
原始文件 永久链接 Blame 文件历史

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base
schema ticket title consumer author change_type backend_status gateway_status frontend_status frontend_owner frontend_ref target_release verified_at status_note updated_at base
hl-changelog/v2 8493 下线房务组长会话入口 POST /admin/message/chat/open-house-lead admin wx(GIT) 删除接口 deployed verified implemented hl-admin 8c9f7bc5174f379f630b4b7530ffd82a4bc1a80c v2.1 2026-09-30 测试服 hl-user-service 已部署 eee6d17ef4（PR #8569）。网关实测：open-house-lead 返回 code=404，open-house 与 conversations 均返回 code=200。历史 HOUSE_LEAD 会话数据只读保留，会话列表、消息分页、标记已读三个既有接口按通用逻辑处理，不对 HOUSE_LEAD 做特殊拦截。前端已交付:chat.js 删 openHouseLead 封装;ChatDrawer HOUSE_LEAD 分支改 conversationKey 直连 messages/read/发消息,对端名片由 conversations 行 peerName/peerRoleLabel 补;housekeeper/orders 移除「联系房务」入口,历史会话从「我的消息」行直读。 2026-09-30 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 已下线。标记已读后的合并未读总数

请求示例

已下线，以下是下线前的请求形态，用来识别调用点：

{
  "orderId": "70123",
  "peerAdminId": "205"
}

响应示例

接口已下线，现在的实际响应（测试服经网关实测；HTTP 状态码 200，业务码 code=404）：

{
  "code": 404,
  "message": "接口不存在: POST /admin/message/chat/open-house-lead",
  "data": null,
  "traceId": null,
  "success": false
}

空数据 / 降级响应

不适用。 接口已不存在，不论带什么参数、用哪个账号，响应都与上面相同，没有空数据或降级分支。

错误响应

下线前这个接口没有专属错误码（越权、参数缺失都走通用的 281005/281010 等，与 open-house 共用一套）。现在唯一的响应就是路由未命中：

{
  "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：wx/HL#8493
  • PR：wx/HL#8569
  • 前置工单：#8491（取消房务组长角色、删除抢单池读口 all-claims）

关联 / 联系人

链接

联系人

  • 后端负责人: @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：组长「联系房务」入口按钮，直接移除。
在新工单中引用 查看 Git Blame 复制永久链接