feat: add im kafka admin integration

2026-09-04 11:57:38 +08:00
parent a2abaef3a6
commit f7f8cc0ef0
74 changed files with 6254 additions and 47 deletions
@@ -0,0 +1,904 @@
+# IM Kafka 接入方案
+
+> 日期：2026-08-26
+> 关联文档：[IM Kafka 接入范围识别](./IM-Kafka接入范围识别.md)、[IM 前后端逐图对接协议](./IM-前后端对接文档.md)
+> 目标：明确 Admin 后台、IM 服务、HotGo 控制库、租户业务库之间的 Kafka 接入边界、查询方式、鉴权方式和首批落地范围。
+
+## 0. 与范围识别文档的关系
+
+[IM Kafka 接入范围识别](./IM-Kafka接入范围识别.md) 是本方案的前置输入，负责按前后端对接文档逐章识别哪些业务适合 Kafka、哪些仍应走 WebSocket/Redis/MySQL/OSS。本方案在该识别结果基础上，进一步确定服务边界、库访问边界、前后台交互模型、内部查询接口、鉴权方式和首批落地步骤。
+
+两份文档分工如下：
+
+| 文档 | 作用 |
+| --- | --- |
+| [IM Kafka 接入范围识别](./IM-Kafka接入范围识别.md) | 回答“哪些业务该用 Kafka，哪些不该用”。 |
+| 本方案 | 回答“Kafka 怎样接入，Admin 与 IM 怎样交互，服务和库怎样隔离”。 |
+
+实施时以范围识别文档的逐章清单确定业务覆盖面，以本方案确定技术实现方式。若后续新增需求，先补充范围识别，再同步调整本方案的 Topic、Command、内部接口和鉴权规则。
+
+## 1. 核心原则
+
+系统按“服务和库一一对应”设计，不允许不同服务直连对方数据库。
+
+| 服务 | 只能直接访问 | 说明 |
+| --- | --- | --- |
+| Admin/HotGo 服务 | `hotgo` 控制库 | 管理后台、租户主数据、后台配置、审核、操作单。 |
+| IM 服务 | 当前租户业务库 | 用户、好友、群、消息、文件引用、工作台业务数据。 |
+| Redis | IM 实时状态与缓存 | 在线状态、短状态、热点消息、缓存分层。 |
+| Kafka | Admin 与 IM 的命令、事件、结果桥 | 后台写操作、异步任务、业务事件、审计、缓存失效。 |
+| OSS | 文件对象存储 | 上传下载字节流不进入 Kafka。 |
+
+最终边界：
+
+1. Admin 不直连租户库。
+2. IM 不直连 `hotgo` 库。
+3. Admin 写租户业务操作统一通过 Kafka Command。
+4. IM 写后台业务状态不直写 `hotgo`，通过 Kafka Result/Event 返回 Admin。
+5. Admin 查询租户业务数据通过 IM 内部只读 API。
+6. IM 查询租户配置、字典、路由通过 Admin 内部只读 API，或消费 Kafka 配置事件维护本地副本。
+7. 在线实时投递继续走 Redis + WebSocket，Kafka 不替代 WS 主链路。
+
+## 2. 总体架构
+
+```text
+Admin/HotGo 服务
+  -> 写 hotgo 操作单
+  -> 生产 Kafka Command
+  -> IM 服务消费 Command
+  -> 写租户业务库
+  -> 生产 Kafka Result/Event
+  -> Admin 消费 Result/Event
+  -> 更新 hotgo 操作状态
+
+Admin 查询租户业务数据
+  -> 调 IM 内部只读 API
+  -> IM 查租户业务库
+  -> 返回 Admin
+
+IM 查询租户配置/字典/路由
+  -> 优先读本地缓存/本地副本
+  -> 缓存缺失时调 Admin 内部只读配置 API
+  -> Admin 查 hotgo
+  -> 返回 IM
+```
+
+## 3. Kafka 使用范围
+
+| 场景 | 是否使用 Kafka | 说明 |
+| --- | --- | --- |
+| Admin 后台群操作通知 C 端 | 是 | 后台写 hotgo 操作单，投 Kafka，IM 执行租户库变更并 WS 下发。 |
+| Admin 后台用户封禁、解封、重置密码 | 是 | IM 消费后更新租户库、踢在线、通知客户端。 |
+| Admin 后台租户配置、字典、功能开关变更 | 是 | Admin 写 hotgo 后投配置事件，IM 刷新缓存或本地副本。 |
+| 企业注册、实名、举报、反馈审核结果 | 是 | Admin 审核后投 Kafka，IM 生成通知或更新租户侧状态。 |
+| 工作台会议、日报、月报、信箱通知 | 是 | 状态变更、提醒、红点更新走 Kafka。 |
+| 私聊/群聊消息异步落库 | 是 | WS 收消息后完成鉴权、幂等和 seq，再投 Kafka 异步持久化。 |
+| 文件安全检测、恶意文件检测 | 是 | OSS 上传完成后投检测任务，消费者调用第三方并更新状态。 |
+| 离线 Push | 是 | 消息或业务事件落地后投 Push 任务。 |
+| 在线消息实时 fanout | 不作为主链路 | 继续 Redis Pub/Sub/Stream + WS。 |
+| 文件上传下载字节流 | 否 | 走 OSS/文件服务；Kafka 只处理上传完成后的事件。 |
+| 验证码、Action Token、限流、在线状态 | 否 | 继续 Redis。 |
+| 普通查询接口 | 否 | 走内部只读 API 或本服务数据库。 |
+
+## 4. 前后台交互模型
+
+### 4.1 后台写租户业务
+
+Admin 后台所有会影响租户业务库或 C 端展示的写操作，统一走 Kafka Command。
+
+```text
+Admin
+  1. 校验后台管理员权限
+  2. 写 hotgo.admin_command，状态 pending
+  3. 发送 Kafka command
+
+IM
+  4. 消费 command
+  5. 校验租户、对象、版本、权限和幂等
+  6. 写租户业务库
+  7. 必要时通过 WS 通知在线 C 端
+  8. 发送 Kafka result
+
+Admin
+  9. 消费 result
+ 10. 更新 hotgo.admin_command 状态
+```
+
+典型操作：
+
+| 操作 | Command | IM 执行动作 | C 端通知 |
+| --- | --- | --- | --- |
+| 群资料修改 | `group.profile.update` | 更新群表和 Topic 资料 | `group.profile.updated` |
+| 设置/删除管理员 | `group.admin.set` / `group.admin.remove` | 更新成员角色 | `group.role.updated` |
+| 禁言/解禁 | `group.member.mute` / `group.member.unmute` | 更新禁言表 | `group.mute.updated` |
+| 踢人 | `group.member.remove` | 更新成员状态和订阅 | `group.member.removed` |
+| 解散群 | `group.delete` | 解散 Topic、撤销权限 | `group.deleted` |
+| 用户封禁 | `user.disable` | 更新用户状态、踢在线 | `user.disabled` |
+| 重置密码 | `user.password.reset` | 更新密码和 `auth_version` | 可选安全通知 |
+
+### 4.2 后台查询租户业务
+
+Kafka 不适合做普通查询。Admin 需要实时查看租户业务数据时，调用 IM 提供的内部只读 API。
+
+只读 API 只允许 `GET`，不提供通用 SQL 或万能查询接口。
+
+| 接口 | 用途 |
+| --- | --- |
+| `GET /internal/admin-query/tenants/{tenant_code}/users/{user_id}` | 查询租户用户详情。 |
+| `GET /internal/admin-query/tenants/{tenant_code}/groups/{topic}` | 查询群详情。 |
+| `GET /internal/admin-query/tenants/{tenant_code}/groups/{topic}/members` | 查询群成员。 |
+| `GET /internal/admin-query/tenants/{tenant_code}/messages/{topic}/{seq}` | 查询消息受控快照。 |
+| `GET /internal/admin-query/tenants/{tenant_code}/files/{file_id}` | 查询文件引用和审核状态。 |
+| `GET /internal/admin-query/tenants/{tenant_code}/reports/abuse/{report_id}/target` | 查询举报目标快照。 |
+| `GET /internal/admin-query/tenants/{tenant_code}/kafka/dead-letters` | 查询 IM 租户库 Kafka 死信列表。 |
+| `GET /internal/admin-query/tenants/{tenant_code}/kafka/dead-letters/{dead_id}` | 查询单条死信详情和原始 envelope。 |
+
+后台列表、统计、高频页面优先使用 `hotgo` 摘要表。摘要由 IM 通过 Kafka 事件同步给 Admin，Admin 查询自己的库。
+
+推荐摘要表：
+
+| 摘要表 | 来源 |
+| --- | --- |
+| `admin_im_user_snapshot` | IM 用户资料变更事件。 |
+| `admin_im_group_snapshot` | IM 群资料、成员数、状态变更事件。 |
+| `admin_im_group_member_stat` | 群成员统计事件。 |
+| `admin_im_file_audit_snapshot` | 文件审核和引用状态事件。 |
+| `admin_im_workbench_snapshot` | 工作台红点、会议、日报/月报状态事件。 |
+
+### 4.3 IM 查询后台配置
+
+IM 不直连 `hotgo`。IM 需要租户路由、租户状态、字典、第三方配置时，使用两种方式：
+
+1. 常态：Admin 修改配置后发送 Kafka 配置事件，IM 消费后更新进程内缓存或本地副本。
+2. 兜底：IM 缓存缺失或启动预热时，调用 Admin 内部只读配置 API。
+
+| 接口 | 用途 |
+| --- | --- |
+| `GET /internal/im-config/tenants/{tenant_code}` | 查询租户状态、名称、路由标识。 |
+| `GET /internal/im-config/tenants/{tenant_code}/limits` | 查询人数、群数、上传大小等限制。 |
+| `GET /internal/im-config/tenants/{tenant_code}/features` | 查询功能开关。 |
+| `GET /internal/im-config/dictionaries?types=oss,file_security,sms,jpush,agora` | 查询字典配置。 |
+| `GET /internal/im-config/app/releases/latest` | 查询 App 版本配置。 |
+
+Admin 内部配置 API 只返回 IM 运行需要的字段，不返回后台管理员账号、菜单权限、审核私有字段。
+
+## 5. Topic 规划
+
+| Topic | 用途 |
+| --- | --- |
+| `im.admin.command` | Admin 发给 IM 的租户业务写命令。 |
+| `im.admin.command.result` | IM 回传命令执行结果。 |
+| `im.config.event` | Admin 发给 IM 的配置、字典、租户状态变更。 |
+| `im.business.event` | IM 内部或 Admin 触发的 C 端业务事件。 |
+| `im.message.persist` | 私聊、群聊消息异步落库。 |
+| `im.message.push` | 离线 Push 任务。 |
+| `im.file.security` | 文件内容安全、恶意文件检测任务。 |
+| `im.file.lifecycle` | 文件引用绑定、释放、回收、合规删除。 |
+| `im.workbench.event` | 会议、日报、月报、信箱、工作台红点事件。 |
+| `im.cache.invalidate` | 跨节点缓存失效。 |
+| `im.audit.event` | 审计事件。 |
+| `im.dead.letter` | 消费失败死信。 |
+
+首版可合并部分 Topic，但事件体必须保留 `biz_type` 和 `event_type`，方便后续拆分。
+
+## 6. 消息结构
+
+统一 Kafka Envelope：
+
+```json
+{
+  "event_id": "evt_01K...",
+  "trace_id": "req_01K...",
+  "tenant_code": "default",
+  "source_service": "hotgo-admin",
+  "target_service": "im",
+  "event_type": "group.member.mute",
+  "biz_type": "group",
+  "biz_id": "grp...",
+  "idempotency_key": "idem_01K...",
+  "version": 3,
+  "occurred_at": "2026-08-26T10:00:00.000Z",
+  "actor": {
+    "type": "admin",
+    "id": "admin_1",
+    "display_name": "管理员"
+  },
+  "payload": {}
+}
+```
+
+Command Result：
+
+```json
+{
+  "event_id": "evt_result_01K...",
+  "trace_id": "req_01K...",
+  "tenant_code": "default",
+  "command_id": "cmd_01K...",
+  "command_event_id": "evt_01K...",
+  "status": "succeeded",
+  "reason": "",
+  "message": "",
+  "result": {},
+  "occurred_at": "2026-08-26T10:00:01.000Z"
+}
+```
+
+失败时 `status=failed`，`reason` 使用稳定错误码，例如 `GROUP_VERSION_CONFLICT`、`FORBIDDEN`、`RESOURCE_NOT_FOUND`、`COMMAND_DUPLICATED`。
+
+## 7. 幂等、事务与重试
+
+### 7.1 生产端
+
+Admin 写操作必须先落 `hotgo.admin_command`，再发送 Kafka。推荐使用 outbox 模式：
+
+1. 同一事务写 `admin_command` 和 `admin_outbox`。
+2. outbox poller 发送 Kafka。
+3. Kafka 发送成功后标记 outbox 已发送。
+4. 发送失败按退避重试。
+
+IM 内部业务事件也按同样方式写租户库 outbox，避免“数据库成功、事件丢失”。
+
+### 7.2 消费端
+
+每个消费者维护消费幂等记录：
+
+| 字段 | 说明 |
+| --- | --- |
+| `event_id` | Kafka 事件唯一 ID。 |
+| `consumer_group` | 消费组。 |
+| `status` | `processing/succeeded/failed/dead`。 |
+| `retry_count` | 重试次数。 |
+| `last_error` | 最近失败原因。 |
+| `created_at/updated_at` | 时间。 |
+
+消费前先插入或锁定 `event_id + consumer_group`。已成功的事件直接跳过；处理中超时可重新抢占。业务表必须再用唯一键兜底，例如 `tenant + command_id`、`tenant + client_mid`、`tenant + topic + seq`。
+
+### 7.3 重试与死信
+
+| 类型 | 策略 |
+| --- | --- |
+| 临时失败 | 指数退避重试。 |
+| 版本冲突 | 不自动重试，回传 failed，由 Admin 刷新后重新发命令。 |
+| 权限失败 | 不重试。 |
+| 对象不存在 | 不重试，除非明确是延迟同步。 |
+| 第三方失败 | 可重试，超过次数写死信和失败表。 |
+
+### 7.4 消费失败处理流程
+
+消费者收到消息后按固定流程处理：
+
+```text
+收到 Kafka 消息
+  -> 校验 Envelope 格式、签名字段、租户和事件类型
+  -> 抢占 event_id + consumer_group 幂等记录
+  -> 已 succeeded：提交 offset，跳过
+  -> processing 超时：允许重新抢占
+  -> 执行业务逻辑
+  -> 成功：标记 succeeded，提交 offset
+  -> 可重试失败：retry_count + 1，按退避策略延迟重试
+  -> 超过最大重试：写入死信，标记 dead，提交 offset
+  -> 不可重试失败：标记 failed 或 dead，必要时回传 command result，提交 offset
+```
+
+重试建议参数：
+
+| 参数 | 建议值 | 说明 |
+| --- | --- | --- |
+| `max_retry_count` | 5～10 | 第三方接口可取高值，权限/参数错误不重试。 |
+| `retry_backoff` | 10s、30s、1m、5m、15m | 指数退避，可加随机抖动。 |
+| `processing_timeout` | 5m～30m | 超过后允许其他消费者重新抢占。 |
+| `dead_letter_retention` | 30～90 天 | 便于排障和人工补偿。 |
+
+### 7.5 死信队列处理
+
+进入死信表示该事件已超过自动恢复能力，系统不能再无限重试。死信必须形成“可查看、可诊断、可重放、可关闭”的闭环。
+
+死信写入两处：
+
+1. Kafka `im.dead.letter` Topic：保留原始事件，便于流式订阅、告警和后续自动补偿。
+2. 数据库失败表：便于 Admin 后台查询、人工处理和审计。
+
+推荐失败表字段：
+
+| 字段 | 说明 |
+| --- | --- |
+| `dead_id` | 死信记录 ID。 |
+| `event_id` | 原 Kafka 事件 ID。 |
+| `source_topic` | 原 Topic。 |
+| `consumer_group` | 失败消费组。 |
+| `tenant_code` | 租户编码。 |
+| `event_type` | 事件类型。 |
+| `biz_type` / `biz_id` | 业务对象。 |
+| `payload` | 原始 Envelope。 |
+| `retry_count` | 已重试次数。 |
+| `last_reason` | 稳定失败原因。 |
+| `last_error` | 最近错误摘要，敏感字段脱敏。 |
+| `status` | `dead/pending_replay/replayed/ignored/resolved`。 |
+| `replay_count` | 人工重放次数。 |
+| `created_at/updated_at` | 时间。 |
+| `resolved_by/resolved_at` | 人工处理人和处理时间。 |
+| `resolve_note` | 处理备注。 |
+
+死信来源分类：
+
+| 分类 | 示例 | 默认处理 |
+| --- | --- | --- |
+| 临时资源失败超过上限 | DB 短暂不可用、第三方超时 | 修复环境后允许重放。 |
+| 业务状态冲突 | 群版本冲突、对象已被删除 | 不自动重放，Admin 刷新状态后重新发命令。 |
+| 权限失败 | 管理员无权限、租户停用 | 不重放，标记 ignored 或 failed result。 |
+| 参数错误 | Envelope 缺字段、payload 非法 | 不重放，修复生产方后关闭。 |
+| 第三方永久失败 | 文件违规、Push token 无效 | 按业务结果落状态，不重放或仅重放特定步骤。 |
+
+Admin 后台需要提供死信处理页：
+
+| 操作 | 说明 |
+| --- | --- |
+| 查看详情 | 展示事件、租户、业务对象、错误原因、重试次数和 trace_id。 |
+| 重放 | 将原事件或修正后的事件重新投递到原 Topic，生成新的 `event_id`，保留 `parent_event_id`。 |
+| 忽略 | 确认该事件无需继续处理，状态改为 `ignored`。 |
+| 标记已处理 | 线下补偿完成后改为 `resolved`。 |
+| 重新生成命令 | 对版本冲突类命令，不直接重放旧事件，而是基于最新状态创建新 Command。 |
+
+重放规则：
+
+1. 重放必须生成新的 `event_id`，原 `event_id` 保留在 `parent_event_id`。
+2. 重放前重新校验租户状态、对象是否存在、操作者权限和业务版本。
+3. 参数错误、权限失败、版本冲突默认禁止直接重放。
+4. 文件安全检测、Push、审计写入等可重试任务允许重放。
+5. 每次重放都写审计，记录处理人、原因、原事件和新事件。
+
+死信告警：
+
+| 指标 | 建议 |
+| --- | --- |
+| 单 Topic 死信数 | 5 分钟内超过阈值告警。 |
+| 同一 `event_type` 连续失败 | 可能是代码或配置问题，立即告警。 |
+| 同一租户大量失败 | 检查租户库、配置或权限状态。 |
+| 死信积压时间 | 超过 24 小时未处理提醒。 |
+
+对 Admin Command 类事件，进入死信后必须回传 `im.admin.command.result`，状态为 `failed` 或 `dead`，让后台操作单结束等待状态。否则后台会长期显示处理中。
+
+## 8. 内部接口鉴权
+
+内部 API 鉴权非常关键，必须同时做网络层、服务层和业务层控制。
+
+### 8.1 网络层
+
+1. `/internal/*` 只允许内网网关或内网地址访问。
+2. 禁止公网直接暴露内部接口。
+3. 有条件时启用 mTLS。
+
+### 8.2 服务签名
+
+内部请求统一携带：
+
+| Header | 说明 |
+| --- | --- |
+| `X-Service-Name` | 调用方服务名，例如 `hotgo-admin` 或 `im-server`。 |
+| `X-Timestamp` | Unix 秒或毫秒时间戳。 |
+| `X-Nonce` | 随机串，短期内不可重复。 |
+| `X-Request-ID` | 请求追踪 ID。 |
+| `X-Signature` | HMAC 签名。 |
+
+签名内容：
+
+```text
+METHOD + "\n" +
+PATH_WITH_QUERY + "\n" +
+BODY_SHA256 + "\n" +
+X-Timestamp + "\n" +
+X-Nonce
+```
+
+校验规则：
+
+1. 时间窗建议 5 分钟。
+2. `nonce` 写 Redis，TTL 5 分钟，防重放。
+3. 每个服务独立 `service_id/service_secret`。
+4. 每个服务配置允许访问的内部接口白名单。
+
+### 8.3 业务授权
+
+Admin 调 IM 查询时，签名 payload 或 Header 中必须包含后台操作者信息：
+
+| 字段 | 说明 |
+| --- | --- |
+| `admin_user_id` | 后台用户 ID。 |
+| `admin_role` | 后台角色。 |
+| `admin_permissions` | 本次已校验过的权限列表。 |
+| `tenant_code` | 被查询租户。 |
+| `reason` | 查询原因或工单号。 |
+
+IM 仍需根据 `tenant_code + permission + resource` 做二次校验，并写内部查询审计。
+
+IM 调 Admin 配置接口时，Admin 只校验服务身份和接口白名单，不返回超出 IM 运行需要的字段。
+
+## 9. 文件与工作台
+
+### 9.1 文件
+
+文件上传下载不走 Kafka，OSS 是文件字节流主链路。Kafka 只处理上传完成后的事件：
+
+1. `im.file.security`：内容安全、恶意文件检测。
+2. `im.file.lifecycle`：业务引用绑定、释放、临时文件回收、合规删除。
+3. `im.business.event`：文件审核失败、合规处置等 C 端通知。
+
+### 9.2 工作台
+
+工作台查询不走 Kafka，状态变化和提醒走 Kafka：
+
+1. 会议创建、更新、取消、提醒、响应：`im.workbench.event`。
+2. 日报/月报提交、撤回、重开、催办：`im.workbench.event`。
+3. 总经理信箱提交、处理结果：`im.workbench.event` + `im.audit.event`。
+4. 工作台模块配置变更：`im.config.event` 或 `im.cache.invalidate`。
+
+## 10. 首批落地建议
+
+| 阶段 | 内容 |
+| --- | --- |
+| 第一步 | 增加 Kafka 配置、生产者、消费者、健康检查、统一 Envelope。 |
+| 第二步 | 增加消费幂等表、outbox 表、死信表或死信 Topic。 |
+| 第三步 | 接入 `im.admin.command` 和 `im.admin.command.result`，先覆盖后台群治理操作。 |
+| 第四步 | 增加 IM 内部只读查询 API，供 Admin 查用户、群、消息、文件快照。 |
+| 第五步 | 增加 Admin 内部配置 API，供 IM 查询租户配置、字典、第三方参数。 |
+| 第六步 | 接入文件安全检测、离线 Push、工作台事件。 |
+| 第七步 | 消息异步落库接入 `im.message.persist`，完善幂等和重试。 |
+
+## 11. 分端任务拆分
+
+### 11.1 Admin/HotGo 侧任务
+
+Admin 侧只访问 `hotgo` 库，负责后台操作入口、配置主数据、命令生产、结果消费和死信处理。
+
+| 模块 | 任务 | 产出 |
+| --- | --- | --- |
+| Kafka 基础 | 增加 Kafka producer/consumer 配置、健康检查、统一 Envelope 组装。 | 可发送 `im.admin.command`、消费 `im.admin.command.result`。 |
+| 操作单 | 新增 `admin_command`、`admin_outbox` 表和状态机。 | `pending/running/succeeded/failed/dead` 操作状态。 |
+| Outbox | 后台写操作单与 outbox 同事务落库，poller 发送 Kafka。 | 防止 hotgo 写成功但 Kafka 丢事件。 |
+| Command 生产 | 群治理、用户封禁/解封、重置密码、审核结果、工作台配置等后台操作生成 Command。 | `im.admin.command` 事件。 |
+| Result 消费 | 消费 IM 回传结果并更新操作单。 | 后台页面可展示最终成功/失败原因。 |
+| 配置事件 | 租户配置、字典、功能开关、第三方配置变更后发送 `im.config.event`。 | IM 刷新缓存或本地副本。 |
+| 配置查询 API | 提供 `/internal/im-config/*` 只读接口。 | IM 启动预热和缓存缺失兜底查询。 |
+| 摘要表 | 建立用户、群、文件、工作台等后台摘要表。 | 后台列表统计优先查 hotgo。 |
+| 死信后台 | 提供死信查看、重放、忽略、标记已处理、重新生成命令。 | 运维闭环。 |
+| 内部鉴权 | 实现服务签名校验、nonce 防重放、接口白名单、审计。 | 保护 Admin 内部配置 API。 |
+| 审计 | 记录后台操作者、租户、资源、Command、Result、死信处理。 | 可追踪后台操作链路。 |
+
+Admin 首批优先级：
+
+1. Kafka 基础配置、Envelope、producer。
+2. `admin_command` + `admin_outbox`。
+3. 群治理 Command 生产。
+4. `im.admin.command.result` 消费。
+5. `/internal/im-config/*` 配置查询 API。
+6. 死信管理页。
+
+### 11.2 IM Server 侧任务
+
+IM Server 侧只访问租户业务库，负责执行 Admin Command、维护租户业务状态、通过 WS 通知 C 端，并向 Admin 回传结果。
+
+| 模块 | 任务 | 产出 |
+| --- | --- | --- |
+| Kafka 基础 | 增加 Kafka producer/consumer 配置、健康检查、统一 Envelope 解析。 | 可消费 Command、生产 Result/Event。 |
+| 消费幂等 | 新增租户库消费幂等表或统一消费日志。 | `event_id + consumer_group` 幂等。 |
+| Command 消费 | 消费 `im.admin.command`。 | 后台命令进入 IM 执行链路。 |
+| 群治理执行器 | 执行群资料、管理员、禁言、踢人、解散、群主转让等命令。 | 更新租户库和 Topic 状态。 |
+| 用户治理执行器 | 执行封禁、解封、重置密码、踢在线等命令。 | 更新用户状态和 `auth_version`。 |
+| Result 生产 | 执行成功/失败后发送 `im.admin.command.result`。 | Admin 操作单闭环。 |
+| WS 通知 | Command 成功后生产 C 端业务事件并投递在线客户端。 | `info.what="im|group"` 下发。 |
+| 配置消费 | 消费 `im.config.event`，刷新进程内缓存或本地副本。 | 租户配置、字典、第三方配置生效。 |
+| 配置兜底查询 | 调 Admin `/internal/im-config/*`。 | IM 启动预热和缓存缺失恢复。 |
+| 内部只读 API | 提供 `/internal/admin-query/*`。 | Admin 实时查询租户业务数据。 |
+| 文件任务 | 上传完成后生产/消费 `im.file.security`、`im.file.lifecycle`。 | 文件审核、引用绑定、回收。 |
+| 消息异步落库 | 接入 `im.message.persist`。 | 私聊/群聊消息削峰落库。 |
+| Push 任务 | 生产 `im.message.push`。 | 离线 Push 异步投递。 |
+| 死信处理 | 写失败表、投 `im.dead.letter`、Command 死信回传 Result。 | 失败可诊断、可补偿。 |
+| 内部鉴权 | 校验 Admin 调用 `/internal/admin-query/*` 的签名、权限和审计。 | 保护租户业务查询。 |
+
+IM Server 首批优先级：
+
+1. Kafka 基础配置、Envelope、consumer/producer。
+2. 消费幂等表和死信写入。
+3. `im.admin.command` 群治理消费执行。
+4. `im.admin.command.result` 回传。
+5. WS 业务事件下发。
+6. `/internal/admin-query/*` 只读查询 API。
+
+### 11.3 双方联调契约
+
+| 契约 | Admin 负责 | IM Server 负责 |
+| --- | --- | --- |
+| Envelope 字段 | 生产完整字段，保证 `event_id/trace_id/tenant_code/event_type/idempotency_key`。 | 校验字段完整性和事件类型白名单。 |
+| Command 状态 | 创建操作单，展示状态。 | 回传成功、失败、死信结果。 |
+| 幂等 | 同一后台操作复用 `command_id/idempotency_key`。 | 同一 Command 重复消费只执行一次。 |
+| 错误码 | 展示 IM 返回的稳定 `reason`。 | 返回稳定 `reason`，不让 Admin 解析错误文本。 |
+| 查询接口 | 带管理员身份、权限、原因和签名。 | 校验签名、权限和租户资源，写审计。 |
+| 配置接口 | 提供最小必要配置字段。 | 不直连 hotgo，使用缓存、事件或内部 API。 |
+| 死信 | 提供处理入口和人工操作审计。 | 写死信、回传 Command dead/failed 状态。 |
+| Trace | 生成并传递 `trace_id`。 | 日志、Kafka、WS 下发沿用同一 `trace_id`。 |
+
+### 11.4 首批联调用例
+
+| 用例 | 预期 |
+| --- | --- |
+| Admin 禁言群成员 | Admin 操作单 pending，IM 消费后更新租户库，C 端收到 `group.mute.updated`，Admin 状态 succeeded。 |
+| Admin 重复提交同一禁言操作 | IM 只执行一次，Result 返回同一最终状态。 |
+| Admin 删除管理员但群版本冲突 | IM 返回 `GROUP_VERSION_CONFLICT`，Admin 操作单 failed，不自动重试。 |
+| IM 消费时临时 DB 失败 | 自动退避重试，未超限不进入死信。 |
+| IM 消费超过重试上限 | 写 `im.dead.letter`，Admin 操作单进入 dead/failed。 |
+| Admin 查询群成员 | Admin 调 `/internal/admin-query/*`，IM 校验签名和权限后返回只读数据。 |
+| IM 启动加载租户配置 | IM 优先读缓存，缺失时调 `/internal/im-config/*`，Admin 只返回必要配置。 |
+
+### 11.5 IM Server 已接入的首批 Admin Command
+
+IM Server 首批消费 `im.admin.command`，执行后回传 `im.admin.command.result`。所有命令必须带 `tenant_code`，`payload.actor_user_id` 必须是租户内 IM 用户 ID，用于落群事件和 C 端通知。
+
+| Command `event_type` | 说明 | 必填 payload |
+| --- | --- | --- |
+| `group.profile.update` | 修改群名称、头像、简介。 | `command_id,actor_user_id,topic,profile,version` |
+| `group.governance.update` | 修改进群审批、全员禁言、成员邀请等治理开关。 | `command_id,actor_user_id,topic,governance,version` |
+| `group.admin.set` | 设置一个或多个管理员。 | `command_id,actor_user_id,topic,user_ids` |
+| `group.admin.remove` | 删除管理员，降为普通成员。 | `command_id,actor_user_id,topic,user_id` |
+| `group.member.mute` | 禁言成员。 | `command_id,actor_user_id,topic,user_id,reason,expires_at` |
+| `group.member.unmute` | 解除禁言。 | `command_id,actor_user_id,topic,user_id` |
+| `group.member.remove` | 移出群成员。 | `command_id,actor_user_id,topic,user_id` |
+| `group.owner.transfer` | 转让群主。 | `command_id,actor_user_id,topic,target_user_id,version` |
+
+当前 IM Server 消费 `im.admin.command` 时已经接入 `im_kafka_consume_log`：
+
+1. 按 `event_id + consumer_group` 抢占消费。
+2. 已成功事件直接跳过，不重复执行业务。
+3. 处理中且未超时的事件跳过，避免并发重复执行。
+4. 失败或处理超时的事件允许重新抢占。
+5. 不可重试错误或超过重试次数后写入 `im_kafka_dead_letters`，并投递 `im.dead.letter`。
+6. Admin Command 进入死信时回传 `im.admin.command.result`，`status=dead`。
+
+### 11.6 IM Server 已接入的配置事件
+
+IM Server 首批消费 `im.config.event`，用于 Admin 修改 HotGo 配置后通知 IM 刷新进程内缓存。当前实现以“缓存失效”为主，收到事件后清除对应缓存，下次业务读取时重新加载。
+
+| Config `event_type` | 说明 | IM 行为 |
+| --- | --- | --- |
+| `tenant.updated` | 租户基础信息变更。 | 清理租户 code/id 缓存。 |
+| `tenant.status.changed` | 租户启停、状态变化。 | 清理租户 code/id 缓存。 |
+| `tenant.limits.updated` | 租户人数、群数、上传限制等变化。 | 清理租户 code/id 缓存。 |
+| `tenant.features.updated` | 租户功能开关变化。 | 清理租户 code/id 缓存。 |
+| `dictionary.updated` | 字典配置变化。 | 清理第三方/字典配置缓存。 |
+| `third_party.updated` | OSS、文件安全、短信、极光、声网等第三方配置变化。 | 按 group 清理第三方配置缓存。 |
+| `registration.config.updated` | 注册、短信开关变化。 | 清理注册配置缓存。 |
+
+事件示例：
+
+```json
+{
+  "event_id": "evt_01K_config",
+  "trace_id": "req_01K",
+  "tenant_code": "default",
+  "source_service": "hotgo-admin",
+  "target_service": "im-server",
+  "event_type": "third_party.updated",
+  "biz_type": "config",
+  "biz_id": "im_third_party",
+  "occurred_at": "2026-08-26T10:05:00.000Z",
+  "payload": {
+    "tenant_code": "default",
+    "group": "im_third_party",
+    "keys": ["oss.endpoint", "file_security.enabled"]
+  }
+}
+```
+
+禁言命令示例：
+
+```json
+{
+  "event_id": "evt_01K_mute",
+  "trace_id": "req_01K",
+  "tenant_code": "default",
+  "source_service": "hotgo-admin",
+  "target_service": "im-server",
+  "event_type": "group.member.mute",
+  "biz_type": "group",
+  "biz_id": "grp...",
+  "idempotency_key": "cmd_01K_mute",
+  "occurred_at": "2026-08-26T10:00:00.000Z",
+  "payload": {
+    "command_id": "cmd_01K_mute",
+    "actor_user_id": "usr_admin",
+    "topic": "grp...",
+    "user_id": "usr_target",
+    "reason": "刷屏",
+    "expires_at": null
+  }
+}
+```
+
+### 11.7 IM Server 已接入的内部只读查询 API
+
+为满足“Admin 不直连租户库”的边界，IM Server 提供内部只读查询接口给 HotGo/Admin 调用。接口默认关闭，通过 `internal_api.enabled=true` 开启。
+
+请求统一鉴权头：
+
+| Header | 说明 |
+| --- | --- |
+| `X-Service-Name` | 调用方服务名，如 `hotgo-admin`。 |
+| `X-Timestamp` | Unix 秒级时间戳，默认 300 秒时间窗。 |
+| `X-Nonce` | 一次性随机串，用于防重放。 |
+| `X-Request-ID` | 调用链路 ID。 |
+| `X-Signature` | HMAC-SHA256 签名，支持 hex 或 base64，可带 `sha256=` 前缀。 |
+
+nonce 防重放优先使用 Redis 短状态 `SETNX + TTL`，Redis 未配置时退化为单节点进程内防重放；生产多节点必须配置 Redis。
+
+签名明文：
+
+```text
+METHOD + "\n" +
+PATH_WITH_QUERY + "\n" +
+SHA256_HEX(BODY) + "\n" +
+X-Timestamp + "\n" +
+X-Nonce
+```
+
+当前首批接口：
+
+| 接口 | 说明 |
+| --- | --- |
+| `GET /internal/admin-query/tenants/{tenant_code}/users/{user_id}` | 查询租户内用户基础资料。 |
+| `GET /internal/admin-query/tenants/{tenant_code}/groups/{topic}` | 查询群资料和治理配置。 |
+| `GET /internal/admin-query/tenants/{tenant_code}/groups/{topic}/members` | 查询群成员分页快照，支持 `limit/cursor/role/eligible_role/q`。 |
+| `GET /internal/admin-query/tenants/{tenant_code}/messages/{topic}/{seq_id}` | 查询单条私聊或群聊消息，`seq_id` 为 `BIGINT`。 |
+| `GET /internal/admin-query/tenants/{tenant_code}/files/{file_id}` | 查询文件元信息和存储位置。 |
+
+配置示例：
+
+```json
+{
+  "internal_api": {
+    "enabled": true,
+    "time_window_seconds": 300,
+    "services": {
+      "hotgo-admin": {
+        "secret": "replace-with-random-secret",
+        "allow": ["admin_query"]
+      }
+    }
+  }
+}
+```
+
+Docker 环境变量：
+
+| 环境变量 | 说明 |
+| --- | --- |
+| `INTERNAL_API_ENABLED` | 是否开启内部接口，默认 `false`。 |
+| `INTERNAL_API_TIME_WINDOW_SECONDS` | 签名时间窗。 |
+| `INTERNAL_API_HOTGO_SERVICE_NAME` | Admin 服务名，默认 `hotgo-admin`。 |
+| `INTERNAL_API_HOTGO_SECRET` | Admin 与 IM 共享签名密钥。 |
+
+### 11.8 IM 访问 Admin 配置查询接口
+
+为满足“IM 服务不直连 hotgo 库”的目标，IM Server 增加 Admin 内部配置查询客户端。该客户端默认关闭，开启后 `store.Tenants`、注册短信开关、第三方配置读取会优先请求 Admin 内部接口，失败时仍可回落旧数据库适配器，便于灰度迁移。
+
+配置示例：
+
+```json
+{
+  "admin_internal_api": {
+    "enabled": true,
+    "base_url": "http://hotgo-admin:8080",
+    "service_name": "im-server",
+    "secret": "replace-with-random-secret",
+    "timeout_ms": 3000
+  }
+}
+```
+
+接口约定：
+
+| 接口 | 用途 |
+| --- | --- |
+| `GET /internal/im-config/tenants/by-code/{tenant_code}` | 按企业码获取租户路由信息，需返回 `id/code/name/state/db_name/db_dsn`。 |
+| `GET /internal/im-config/tenants/by-id/{tenant_id}` | 按租户 ID 获取租户路由信息。 |
+| `GET /internal/im-config/tenants?state=active&limit=1000` | 获取活跃租户列表，用于 Kafka Outbox 扫描。 |
+| `GET /internal/im-config/registration/sms` | 获取注册短信开关，返回 `{"enabled": true}`。 |
+| `GET /internal/im-config/third-party/{group}?keys=a,b` | 获取第三方配置，返回 `{"values": {"a": "..."}}`。 |
+
+鉴权沿用内部接口 HMAC 方案，请求头为 `X-Service-Name`、`X-Timestamp`、`X-Nonce`、`X-Signature`；签名文本为 `METHOD + "\n" + RequestURI + "\n" + BodySHA256 + "\n" + Timestamp + "\n" + Nonce`。
+
+Docker 环境变量：
+
+| 环境变量 | 说明 |
+| --- | --- |
+| `ADMIN_INTERNAL_API_ENABLED` | 是否启用 IM 到 Admin 的配置查询客户端，默认 `false`。 |
+| `ADMIN_INTERNAL_API_BASE_URL` | Admin 内部接口根地址。 |
+| `ADMIN_INTERNAL_API_SERVICE_NAME` | IM 服务名，默认 `im-server`。 |
+| `ADMIN_INTERNAL_API_SECRET` | Admin 与 IM 共享签名密钥。 |
+| `ADMIN_INTERNAL_API_TIMEOUT_MS` | 请求超时时间。 |
+
+### 11.9 IM Server 已接入的消息异步落库
+
+IM Server 已接入 `im.message.persist`，用于把在线发送链路和最终消息落库解耦。
+
+当前处理方式：
+
+1. WS/HTTP 发送入口先同步完成权限校验、业务幂等、`seq_id` 分配和 Topic 游标占用。
+2. Kafka 开启时，发送入口先写租户库 `im_kafka_outbox`，由 Outbox worker 可靠生产 `im.message.persist`，客户端仍立即拿到已分配的 `seq_id`。
+3. Kafka 关闭时，继续走原同步落库路径，兼容本地和未接 Kafka 环境。
+4. 消费者按 `message_kind` 区分私聊与群聊：
+   - `p2p` 写入 `im_messages`。
+   - `group` 写入 `im_group_messages`。
+5. 消费侧复用 `im_kafka_consume_log` 做 `event_id + consumer_group` 幂等。
+6. 失败按统一退避重试，超过上限写入 `im_kafka_dead_letters` 并投递 `im.dead.letter`。
+
+### 11.10 IM Server 已接入的缓存失效消费
+
+IM Server 已订阅 `im.cache.invalidate`，用于接收 Admin 或其他节点发出的通用缓存失效事件。消费侧复用 `im_kafka_consume_log` 做幂等，失败按统一退避重试，超过上限进入死信。
+
+事件体示例：
+
+```json
+{
+  "event_id": "cache:tenant:default:1720000000",
+  "event_type": "cache.tenant.invalidate",
+  "tenant_code": "default",
+  "payload": {
+    "tenant_code": "default",
+    "tenant_id": 1,
+    "namespace": "tenant"
+  }
+}
+```
+
+支持的失效范围：
+
+| `event_type` / `namespace` | 处理方式 |
+| --- | --- |
+| `cache.tenant.invalidate` / `tenant` | 清理租户注册表与租户配置进程内缓存。 |
+| `cache.registration.invalidate` / `registration` | 清理注册短信开关缓存。 |
+| `cache.third_party.invalidate` / `third_party` | 按 `group` 清理第三方配置缓存。 |
+| `cache.dictionary.invalidate` / `dictionary` | 按 `group` 清理字典/配置类缓存。 |
+| `cache.redis_object.invalidate` / 任意 Redis `namespace` | 按 `keys` 删除用户、群、关系、权限、未读等 Redis 对象缓存。 |
+| `cache.group_hot_messages.invalidate` / `group_hot_messages` | 按 `topic` 和可选 `ranges` 清理群热消息缓存。 |
+
+### 11.11 IM Server 已接入的死信处理闭环
+
+IM Server 已将死信从“只写表”补齐为“可查询、可忽略、可解决、可重放”的处理闭环。Admin 不直连租户库，列表和详情通过 IM 内部只读 API 查询；写操作仍通过 `im.admin.command` 投递给 IM。
+
+Admin 查询接口：
+
+| 接口 | 说明 |
+| --- | --- |
+| `GET /internal/admin-query/tenants/{tenant_code}/kafka/dead-letters?status=dead&limit=50&cursor=` | 死信分页列表，支持 `status/biz_type/biz_id/event_type` 过滤。 |
+| `GET /internal/admin-query/tenants/{tenant_code}/kafka/dead-letters/{dead_id}` | 单条死信详情，包含原始 Kafka envelope。 |
+
+Admin 处理命令：
+
+| `event_type` | 说明 | Payload 关键字段 |
+| --- | --- | --- |
+| `kafka.dead_letter.replay` | 删除原消费日志并按原 `source_topic` 重投 envelope，成功后标记 `replayed`。 | `dead_id`、`actor_user_id`、`note` |
+| `kafka.dead_letter.ignore` | 人工确认无需处理，标记 `ignored`。 | `dead_id`、`actor_user_id`、`note` |
+| `kafka.dead_letter.resolve` | 线下修复后标记 `resolved`。 | `dead_id`、`actor_user_id`、`note` |
+
+重放规则：
+
+1. IM 先把 `im_kafka_dead_letters.status` 改为 `pending_replay`，并删除对应 `im_kafka_consume_log`。
+2. IM 按死信记录中的 `source_topic` 重新投递原 envelope。
+3. 投递成功后把死信标记为 `replayed`，并累计 `replay_count`。
+4. 如果重放后仍失败，普通消费者会再次写入新的 dead 记录，保留完整处理痕迹。
+7. 群消息消费成功后继续写入 Redis 热消息缓存，便于 24 小时内热点拉取。
+
+事件示例：
+
+```json
+{
+  "event_id": "msg.persist.1.grpabc.10086",
+  "tenant_code": "default",
+  "source_service": "im-server",
+  "target_service": "im-server",
+  "event_type": "message.persist.group",
+  "biz_type": "message",
+  "biz_id": "grpabc:10086",
+  "idempotency_key": "client-mid-001",
+  "version": 10086,
+  "occurred_at": "2026-08-26T10:10:00.000Z",
+  "actor": {
+    "type": "user",
+    "id": "usr..."
+  },
+  "payload": {
+    "message_kind": "group",
+    "read_by_sender": true,
+    "attachment_urls": [],
+    "message": {
+      "SeqId": 10086,
+      "Topic": "grpabc",
+      "From": "abcdef",
+      "Head": {
+        "x-im-client-mid": "client-mid-001"
+      },
+      "Content": {
+        "txt": "hello"
+      }
+    }
+  }
+}
+```
+
+### 11.9 IM Server 已接入的 Kafka Outbox Worker
+
+IM Server 已接入租户库 `im_kafka_outbox` 通用发送 worker，用于避免“业务库写成功但 Kafka 未发送”的事件丢失。
+
+当前能力：
+
+1. 启动后按 active 租户扫描每个租户库的 `im_kafka_outbox`。
+2. 扫描 `pending/failed` 且已到 `next_retry_at` 的事件。
+3. 发送成功后标记 `sent`、写入 `sent_at`。
+4. 发送失败后标记 `failed`，按 Kafka 配置的 `retry_backoff_ms` 写入下一次重试时间。
+5. 首个接入方为 `im.message.persist`，后续文件生命周期、工作台事件、审计事件可复用同一 outbox。
+
+本轮暂不实现 `im.message.push` 离线 Push Kafka 化，已记录到 [IM 第一至十一章后续增强项](./IM-未实现后续增强项.md)。
+
+### 11.10 IM Server 已接入的文件生命周期事件
+
+IM Server 已接入 `im.file.lifecycle` 的首批生产与消费，用于把文件上传、附件绑定、群文件登记/删除纳入可靠事件链路。
+
+当前事件：
+
+| `event_type` | 生产时机 | 消费行为 |
+| --- | --- | --- |
+| `file.upload.completed` | HTTP/gRPC 上传成功并完成文件记录后。 | 当前作为可靠生命周期事实记录，文件安全任务仍由上传完成事务创建。 |
+| `file.attachments.bind` | `im.message.persist` 消费成功后，如果消息携带附件。 | 私聊写 `im_filemsglinks`；群聊写 `im_group_files`。 |
+| `group.file.created` | 群文件 API 登记成功后。 | 当前作为可靠生命周期事实记录，供后续 Admin 摘要、审计、回收策略复用。 |
+| `group.file.deleted` | 群文件 API 删除成功后。 | 当前作为可靠生命周期事实记录，供后续 Admin 摘要、审计、回收策略复用。 |
+
+说明：
+
+1. Kafka 开启时，消息附件绑定从消息落库消费者中拆出，改由 `im.file.lifecycle` 消费者完成。
+2. Kafka 关闭时，仍沿用原同步绑定路径，兼容本地环境。
+3. 文件对象字节流仍走 OSS/文件服务，Kafka 不承载上传/下载内容。
+4. 合规删除、临时文件 TTL 回收、OSS 删除动作仍保留为后续深化项。
+
+### 11.11 IM Server 已接入的工作台事件
+
+IM Server 已接入 `im.workbench.event` 的首批生产与消费。
+
+当前生产范围：
+
+| 模块 | 事件 |
+| --- | --- |
+| 会议 | `meeting.created`、`meeting.updated`、`meeting.canceled`、`meeting.reminded`、`meeting.response.updated` |
+| 日报 | `daily_report.draft.created`、`daily_report.draft.saved`、`daily_report.submitted`、`daily_report.reminded` |
+| 月报 | `monthly_report.draft.created`、`monthly_report.draft.saved`、`monthly_report.submitted`、`monthly_report.reopened` |
+| 总经理信箱 | `mailbox.submitted` |
+
+当前消费行为：
+
+1. 消费 `im.workbench.event`。
+2. 按 `target_user_ids` 生成系统通知。
+3. 写入 `im_business_events_outbox`，由现有 WS 业务事件投递器下发在线客户端。
+4. 使用 `im_kafka_consume_log` 做消费幂等，失败按统一重试和死信规则处理。
+
+### 11.12 IM Server 已接入的审计事件
+
+IM Server 已接入 `im.audit.event` 的可靠生产，审计事件写入租户库 `im_kafka_outbox` 后由 Kafka Outbox worker 发送。
+
+当前审计范围：
+
+| 类型 | 事件 |
+| --- | --- |
+| 工作台 | 会议、日报、月报、总经理信箱的状态变更。 |
+| Admin Command | 后台群治理命令执行成功。 |
+| Kafka 死信 | `kafka.dead_letter.created`。 |
+| 文件生命周期 | 上传完成、附件绑定、群文件新增/删除。 |
+
+审计事件当前不在 IM 内部落审计表，预期由 Admin/HotGo 消费 `im.audit.event` 后写入 `hotgo` 审计库或审计表。
+
+## 12. 风险与约束
+
+1. Kafka 是异步链路，Admin 后台命令不能默认立即成功，只能显示 `pending/running/succeeded/failed`。
+2. 查询不能通过 Kafka 常规化实现，高频实时查询必须走内部只读 API 或 hotgo 摘要表。
+3. 内部 API 不能暴露公网，签名、nonce、防重放和审计必须首批完成。
+4. 配置事件可能丢失或延迟，IM 必须保留启动预热和缓存缺失时的 Admin 配置查询兜底。
+5. Kafka 消费可能重复，所有消费者和业务写入都必须幂等。
+6. Admin 和 IM 不跨库直连后，排障要依赖 `trace_id` 串联 hotgo 操作单、Kafka 事件、IM 执行日志和 WS 下发日志。
@@ -0,0 +1,89 @@
+# IM Kafka 接入范围识别
+
+> 日期：2026-08-26
+> 依据：[IM 前后端逐图对接协议](./IM-前后端对接文档.md)
+> 目标：从前后端对接文档逐章识别适合接入 Kafka 的链路，明确 Kafka 与 WebSocket、Redis、MySQL、OSS 的边界。
+
+## 1. 总体边界
+
+Kafka 主要用于跨系统异步事件、削峰落库、可靠重试、失败补偿、后台操作通知 C 端和审计流水；不替代 WebSocket 的在线实时连接，不替代 Redis 的短状态和热读缓存，也不替代 MySQL 的最终状态。
+
+| 类型 | 建议承载 | 说明 |
+| --- | --- | --- |
+| 在线实时消息投递 | Redis Pub/Sub/Stream + WebSocket | 低延迟 fanout，节点收到后直接写 WS。 |
+| 异步落库、重试、补偿 | Kafka | 适合消息持久化、通知、Push、审核、审计等可重放任务。 |
+| 短状态、限流、验证码、在线状态 | Redis | TTL 明确，不需要 Kafka。 |
+| 最终业务状态 | MySQL | Kafka 消费成功后写入或更新最终状态。 |
+| 文件对象存储 | OSS | Kafka 只处理文件元数据、安全检测和生命周期事件。 |
+
+## 2. 推荐 Topic
+
+| Topic | 用途 | 典型生产方 | 典型消费方 |
+| --- | --- | --- | --- |
+| `im.message.persist` | 私聊、群聊消息异步落库 | IM WS 节点 | 消息持久化消费者 |
+| `im.message.push` | 离线 Push 提醒 | 消息落库消费者、业务事件生产方 | 极光/厂商 Push 消费者 |
+| `im.business.event` | 好友、群、会议、工作台等 C 端业务事件 | IM HTTP、Admin 后台 | IM 节点事件投递消费者 |
+| `im.group.admin.event` | Admin 后台群操作投递到 C 端 | Admin 后台 | IM 节点 WS 投递消费者 |
+| `im.cache.invalidate` | 跨节点缓存失效 | 业务写接口、后台配置 | IM 节点缓存消费者 |
+| `im.file.security` | 文件内容安全和恶意文件检测 | 上传完成链路 | 阿里云安全检测消费者 |
+| `im.file.lifecycle` | 孤立文件回收、引用绑定、合规删除 | 文件服务、业务写接口 | 文件生命周期消费者 |
+| `im.audit.event` | 审计日志 | 所有敏感写链路 | 审计消费者 |
+| `im.workbench.event` | 工作台模块红点、会议、日报、月报、信箱事件 | 工作台业务服务、Admin 后台 | IM WS 投递、系统通知消费者 |
+| `im.dead.letter` | 失败事件归档 | 各消费者 | 运维补偿任务 |
+
+## 3. 幂等与重试
+
+Kafka 消息统一携带 `event_id`、`trace_id`、`tenant_code`、`biz_type`、`biz_id`、`action`、`version`、`occurred_at` 和 `payload`。消费端按 `event_id + consumer_group` 做幂等记录，业务表也必须保留唯一键兜底。
+
+消息发送链路使用 `x-im-client-mid` 或 HTTP `Idempotency-Key` 作为业务幂等来源；Kafka 只负责可靠投递，不能作为唯一幂等判断。消费者失败按指数退避重试，超过上限写 `im.dead.letter` 或失败表，由后台补偿。
+
+## 4. 逐章识别
+
+| 章节 | 适合 Kafka 的范围 | 不建议 Kafka 的范围 |
+| --- | --- | --- |
+| 0. 公共对接约定 | 产品业务事件 outbox 可改为 Kafka 投递；消息异步落库、系统通知、离线 Push、跨节点缓存失效使用 Kafka；`x-im-client-mid` 幂等结果可作为生产 Kafka 前置校验。 | WebSocket 建连、`hi/login/sub/get/note` 本身不走 Kafka；在线状态继续 Redis。 |
+| 1. 账号注册、登录与身份安全 | 企业注册申请、企业入口反馈、实名提交、密码重置成功、账号封禁/解封、管理员重置密码、审核结果通知、审计日志可走 Kafka。营业执照和反馈截图上传完成后投 `im.file.security`。 | 登录鉴权、验证码校验、Action Token、限流不走 Kafka；这些必须同步返回或走 Redis。 |
+| 2. 消息首页、全局导航与系统通知 | 系统通知创建、已读异步统计、入口红点变更、离线 Push 提醒、消息摘要更新可走 Kafka。 | 首页查询、会话列表拉取、客户端断线重连流程不走 Kafka。 |
+| 3. 单聊会话、会话建立与消息状态 | 私聊消息异步落库、好友申请/通过/拒绝/删除事件、P2P 订阅建立后的通知、媒体消息文件绑定事件、离线 Push 可走 Kafka。 | 在线 P2P 实时投递主链路不建议 Kafka；关系判断和发送权限校验必须同步完成。 |
+| 4. 消息输入、媒体内容与消息操作 | @提醒 Push、消息撤回/编辑事件、收藏批量创建、转发任务、forward bundle 生成、消息搜索索引更新、附件 ACL 绑定可走 Kafka。 | 输入框、草稿、录音状态、上传进度和客户端 pending 队列不走 Kafka。 |
+| 5. 通讯录、好友关系与黑名单 | 好友申请事件、好友关系变更、黑名单变更、二维码使用审计、资料快照更新、搜索索引更新、系统通知生成可走 Kafka。 | 好友列表查询、用户搜索同步结果、二维码解析鉴权不走 Kafka。 |
+| 6. 群聊创建、资料维护与成员治理 | 群创建、成员加入/退出、邀请/审批、公告更新、资料更新、角色变更、禁言、群主转让、解散、群文件登记/删除、Admin 后台群操作投递到 C 端都适合 Kafka。Admin 后台写库后生产 `im.group.admin.event`，IM 节点消费后用 WS 下发给在线客户端。 | 群内在线消息 fanout 主链路继续 Redis + WS；群成员权限校验、成员数上限校验必须同步事务完成。 |
+| 7. 文件下载、收藏管理与聊天记录检索 | 文件安全检测、恶意文件扫描、文件生命周期、收藏快照异步补全、收藏转发、搜索索引更新、合规删除事件可走 Kafka。文件下载本身不走 Kafka。 | OSS 上传/下载字节流、Range 续传、下载进度不走 Kafka；这些走文件服务和客户端任务管理。 |
+| 8. 实时语音与视频通话 | 通话记录落库、未接来电 Push、通话结束审计、后台计费或统计、异常通话风控可走 Kafka。 | WebRTC offer/answer/ICE、接听、挂断等实时信令不建议 Kafka 主链路；仍走 WS。 |
+| 9. 企业工作台与办公协同 | 工作台红点更新、会议创建/更新/取消/提醒/响应、日报/月报提交和催办、总经理信箱提交、工作台系统通知、后台配置变更、审计都适合 Kafka。 | 工作台模块列表、组织架构查询、报表详情查询不走 Kafka；普通查询走 MySQL/Redis 缓存。 |
+| 10. 个人资料、通用设置、隐私与青少年模式 | 资料变更事件、隐私配置变更、青少年模式开启/关闭、多设备退出、Push Token 变更审计、App 发布配置缓存失效可走 Kafka。头像上传后走文件安全检测。 | 本地清缓存、系统权限引导、密码验证、Action Token 不走 Kafka。 |
+| 11. 反诈安全、举报与意见反馈 | 风控确认审计、举报受理、证据文件安全检测、意见反馈、诊断包处理、后台审核通知、合规处置事件可走 Kafka。 | 风险弹窗同步拦截结果、举报原因查询、反馈配置查询不走 Kafka。 |
+| 12. 联调实施清单 | Kafka 需要覆盖消息幂等、系统事件可信生产、文件安全检测、后台群操作到 C 端、离线 Push、失败重试和死信补偿验收。 | 前端基础联调请求不直接依赖 Kafka，除非该接口声明为异步任务。 |
+
+## 5. 文件链路结论
+
+文件上传、下载、Range、ETag、OSS 对象读写不走 Kafka。Kafka 只接入文件完成后的业务事件：
+
+1. 上传完成后投递 `im.file.security`，调用阿里云内容安全和恶意文件检测。
+2. 安全检测完成后更新文件审核状态，并通过 `im.business.event` 或系统通知告知相关用户。
+3. 消息发送、收藏、群文件登记、日报/月报/反馈/举报提交成功后投递 `im.file.lifecycle`，建立业务引用和 ACL。
+4. 业务撤回、删除、合规处置或临时文件 TTL 到期后投递 `im.file.lifecycle`，执行引用释放、禁用下载或 OSS 删除。
+
+## 6. 工作台链路结论
+
+工作台“查询类接口”不需要 Kafka，但工作台“状态变化和提醒类事件”适合 Kafka：
+
+1. 会议创建、更新、取消、提醒、参会响应生产 `im.workbench.event`，消费者生成系统通知、红点并通过 WS 通知在线客户端。
+2. 日报/月报提交、撤回、重开、管理员催办生产 `im.workbench.event`，用于红点、催办 Push 和审计。
+3. 总经理信箱提交生产 `im.workbench.event` 和 `im.audit.event`，后台处理结果再回推 C 端。
+4. 工作台模块配置变更生产 `im.cache.invalidate`，IM 节点刷新进程内配置缓存。
+
+## 7. 已补充：缓存失效与 Admin 配置查询
+
+1. `im.cache.invalidate` 已接入 IM 消费端，支持租户、注册短信、第三方配置、字典配置、Redis 对象缓存、群热消息缓存失效。
+2. IM 已增加 Admin 内部配置查询客户端，开启 `admin_internal_api.enabled=true` 后优先通过 Admin 查询 hotgo 侧配置，旧数据库读取作为灰度兜底。
+3. Admin 侧需要补齐 `/internal/im-config/*` 只读接口，并与 IM 使用同一套 HMAC 签名密钥。
+4. Kafka 死信已补齐查询、忽略、解决、重放闭环：查询走 IM 内部 API，处理走 `im.admin.command`。
+
+## 8. 首批建议实现
+
+1. 先实现 Kafka 基础生产者、消费者、配置、健康检查和消费幂等表。
+2. 接入 `im.group.admin.event`，解决 Admin 后台群操作通过 Kafka 投递到 C 端。
+3. 接入 `im.message.persist`，将消息异步落库和幂等重试闭环。
+4. 接入 `im.file.security`，把 OSS 上传完成后的文件安全检测异步化。
+5. 接入 `im.workbench.event`，先覆盖会议提醒、日报/月报催办、总经理信箱提交通知。