Refine Kafka persistence topic boundaries

docs/IM-Kafka接入联调测试文档.md

@@ -6,9 +6,9 @@
 
 ## 1. 联调目标
 
-1. 验证 Kafka 基础生产、消费、幂等、重试、死信、Outbox 能正常工作。
+1. 验证 Kafka 基础生产、消费、幂等、重试、死信能正常工作。
 2. 验证 Admin 后台操作通过 `im.admin.command` 投递到 IM Server，并通过 `im.admin.command.result` 返回最终状态。
-3. 验证 IM Server 消息异步落库、文件生命周期、工作台事件、审计事件、缓存失效、死信处理、用户治理命令全部可用。
+3. 验证 IM Server 私聊/群聊消息异步落库、缓存失效、死信处理、用户治理命令全部可用；文件生命周期和工作台事件同步落库。
 4. 验证 Admin 与 IM Server 不跨库直连：Admin 查询租户业务数据走 IM 内部 API；IM 查询 hotgo 配置走 Admin 内部 API。
 5. 验证 Kafka 异常情况下不会产生重复业务结果，且失败可重试、可进入死信、可人工重放。
 
@@ -21,7 +21,7 @@
 | MySQL | `hotgo` 控制库、租户库如 `tinode` 已创建并可连接。 |
 | Redis | IM Server 已配置 Redis，用于在线状态、短状态、热缓存和跨节点 fanout。 |
 | Kafka | Topic 已创建或允许自动创建；建议测试环境显式创建。 |
-| OSS | 文件上传下载仍走 OSS，Kafka 只处理文件元数据和生命周期事件。 |
+| OSS | 文件上传下载仍走 OSS，文件元数据和生命周期小流量动作同步处理。 |
 | Admin/HotGo | 已接入 Kafka producer/consumer、outbox、内部配置查询接口。 |
 | IM Server | 已启用 Kafka、内部 Admin Query API、Admin Internal Config Client。 |
 
@@ -33,10 +33,9 @@
 | `im.admin.command.result` | IM -> Admin | 后台命令执行结果。 |
 | `im.config.event` | Admin -> IM | 租户配置、字典、第三方配置变更通知。 |
 | `im.cache.invalidate` | Admin/IM -> IM | 跨节点缓存失效。 |
-| `im.message.persist` | IM -> IM | 私聊、群聊消息异步落库。 |
-| `im.file.lifecycle` | IM -> IM | 文件上传完成、附件绑定、群文件登记/删除。 |
-| `im.workbench.event` | Admin/IM -> IM | 工作台事件、红点、系统通知。 |
-| `im.audit.event` | IM -> Admin/审计消费者 | 审计事件。 |
+| `im.message.persist` | IM -> IM | 私聊消息异步落库。 |
+| `im.group.message.persist` | IM -> IM | 群聊消息异步落库。 |
+| `im.audit.event` | IM -> Admin/HotGo | 跨系统审计事件。 |
 | `im.dead.letter` | IM -> Admin/告警 | 消费失败死信。 |
 
 说明：`im.message.push` 已规划但本轮不联调，离线 Push Kafka 化仍在增强项中。
@@ -69,7 +68,6 @@ Admin/HotGo 侧需具备：
 | `im_admin_commands` | Admin 操作单，记录后台操作 `pending/running/succeeded/failed/dead`。 |
 | `im_admin_outbox` | Admin outbox，与操作单同事务写入，可靠发送 Kafka。 |
 | `im_kafka_dead_letter_events` | Admin 消费 `im.dead.letter` 后落 HotGo，用于告警和排障。 |
-| `im_audit_events` | Admin 消费 `im.audit.event` 后落 HotGo，用于 Kafka 审计事件列表。 |
 | Admin 配置表/字典表 | 为 `/internal/im-config/*` 提供数据源。 |
 
 Admin/HotGo 侧需执行：
@@ -94,7 +92,7 @@ SOURCE server/storage/data/generate/im_kafka_audit_menu.sql;
     "client_id": "im-server",
     "consumer_group": "im-server",
     "allow_auto_topic_creation": false,
-    "max_retry_count": 5
+    "max_retry_count": 3
   },
   "internal_api": {
     "enabled": true,
@@ -120,8 +118,8 @@ SOURCE server/storage/data/generate/im_kafka_audit_menu.sql;
 
 Admin 需要：
 
-1. Kafka producer 发送 `im.admin.command`、`im.config.event`、`im.cache.invalidate`、`im.workbench.event`。
-2. Kafka consumer 消费 `im.admin.command.result`、`im.dead.letter`、`im.audit.event`。
+1. Kafka producer 发送 `im.admin.command`、`im.config.event`、`im.cache.invalidate`。
+2. Kafka consumer 消费 `im.admin.command.result`、`im.dead.letter`。
 3. 内部接口客户端调用 IM `/internal/admin-query/*`。如果 IM API 前缀为 `/v1`，Admin 配置 `imInternalApi.baseUrl` 应包含 `/v1`，例如 `http://im-server:6060/v1`。
 4. 内部接口服务端提供 IM `/internal/im-config/*`。
 5. 内部接口签名与 IM 一致。
@@ -150,7 +148,7 @@ METHOD + "\n" + RequestURI + "\n" + BodySHA256Hex + "\n" + Timestamp + "\n" + No
 | 后台查询 | 通过 IM `/internal/admin-query/*` 查询租户业务数据。 | 提供白名单只读查询接口，统一 HMAC 鉴权。 |
 | IM 配置读取 | 提供 `/internal/im-config/*`。 | 通过 Admin 内部配置接口读取租户、注册、第三方配置。 |
 | Kafka 死信 | 消费 `im.dead.letter`，展示告警和处理入口。 | 记录死信，提供查询接口，消费处理命令。 |
-| 审计 | 消费 `im.audit.event` 并落 HotGo 审计表。 | 关键业务动作生产审计事件。 |
+| 审计 | 消费 `im.audit.event` 并同步落 HotGo 审计表。 | 关键业务动作生产跨系统审计事件，不在 IM 内部消费落库。 |
 
 ### 2.7 IM 内部查询接口矩阵
 
@@ -597,23 +595,22 @@ Payload：
 
 ### TC-KAFKA-016 文件上传完成事件
 
-目标：验证文件上传完成后产生 `im.file.lifecycle` 事实事件。
+目标：验证文件上传完成后不再产生 `im.file.lifecycle` Kafka 事件。
 
 步骤：
 
 1. 客户端上传文件到 OSS。
 2. 上传完成后查询租户库文件记录。
-3. 检查 Kafka outbox 和 `im.file.lifecycle`。
+3. 确认 Kafka topic 中没有 `im.file.lifecycle` 依赖。
 
 预期：
 
 1. 文件字节流只进入 OSS。
-2. Kafka 只包含文件元数据，不包含文件内容。
-3. 上传完成事件可被消费并审计。
+2. 上传完成后的文件记录已同步落库。
 
 ### TC-KAFKA-017 消息附件绑定
 
-目标：验证消息落库后附件引用由 `im.file.lifecycle` 绑定。
+目标：验证消息落库后附件引用同步绑定。
 
 步骤：
 
@@ -631,7 +628,7 @@ Payload：
 
 ### TC-KAFKA-018 群文件登记与删除
 
-目标：验证群文件业务事件接入 `im.file.lifecycle`。
+目标：验证群文件业务由 HTTP 接口同步落库。
 
 步骤：
 
@@ -660,13 +657,11 @@ Payload：
 
 预期：
 
-1. 每个动作产生 `im.workbench.event`。
-2. 消费后写 `im_system_notifications`。
-3. 写 `im_business_events_outbox`。
-4. 在线 C 端收到系统通知或红点刷新。
-5. 审计事件已投递。
+1. 每个动作同步写 `im_system_notifications`。
+2. 同步写 `im_business_events_outbox`。
+3. 在线 C 端收到系统通知或红点刷新。
 
-Admin 连通性补充：可在「IM管理 -> Kafka命令」点击「发送工作台测试事件」，或调用 `POST /admin/imKafkaCommand/workbenchEvent`，验证 Admin 具备生产 `im.workbench.event` 的能力。真实会议、日报/月报、信箱业务结果仍以 IM Server 对应业务用例为准。
+Admin 连通性补充：工作台事件不再走 Kafka，真实会议、日报/月报、信箱业务结果以 IM Server 对应业务用例为准。
 
 ### TC-KAFKA-020 日报/月报事件
 
@@ -681,9 +676,8 @@ Admin 连通性补充：可在「IM管理 -> Kafka命令」点击「发送工作
 
 预期：
 
-1. 对应事件进入 `im.workbench.event`。
-2. 通知目标用户正确。
-3. 工作台红点或系统通知可被客户端看到。
+1. 通知目标用户正确。
+2. 工作台红点或系统通知可被客户端看到。
 
 ### TC-KAFKA-021 总经理信箱事件
 
@@ -692,9 +686,8 @@ Admin 连通性补充：可在「IM管理 -> Kafka命令」点击「发送工作
 步骤：
 
 1. 用户提交信箱内容。
-2. 检查 `im.workbench.event`。
-3. 检查 `im.audit.event`。
-4. Admin 后台消费后生成处理单。
+2. 检查同步生成的通知/业务事件。
+3. Admin 后台生成处理单。
 
 预期：
 
@@ -866,7 +859,7 @@ GET /v1/internal/admin-query/tenants/default/kafka/dead-letters/{dead_id}
 
 ### TC-KAFKA-029 审计事件
 
-目标：验证关键后台和敏感操作都有审计事件。
+目标：确认 IM Server 对跨系统审计仍生产 `im.audit.event`，由 Admin/HotGo 消费后同步落审计表。
 
 覆盖：
 
@@ -878,20 +871,19 @@ GET /v1/internal/admin-query/tenants/default/kafka/dead-letters/{dead_id}
 
 预期：
 
-1. `im.audit.event` 收到事件。
-2. 事件包含 `tenant_code`、`actor`、`biz_type`、`biz_id`、`event_type`、`occurred_at`。
-3. Admin 审计消费者可落 HotGo `im_audit_events`。
-4. Admin 可在「IM管理 -> Kafka审计事件」查看审计事件列表和详情。
+1. IM Server 生产 `im.audit.event`。
+2. Kafka consumer 启动日志中没有 IM 侧审计事件 consumer。
+3. Admin/HotGo 消费审计事件并同步写入审计表。
 
-### TC-KAFKA-030 Outbox 可靠投递
+### TC-KAFKA-030 IM 侧 Kafka 生产失败
 
 目标：验证 IM 侧 Kafka 直接生产失败时不会产生 DB outbox，调用方收到发送失败。
 
 预期：
 
-1. Kafka 停止时业务 outbox 记录为 `pending/failed`。
-2. 恢复后记录变为 `sent`。
-3. 下游消费者最终收到事件。
+1. Kafka 停止时 IM 不写 `im_kafka_outbox`，消息发送返回失败。
+2. 恢复后客户端可重新发送。
+3. 重复发送依赖 `client_mid` 和消费日志保持幂等。
 4. 不重复产生业务副作用。
 
 ## 5. Admin 侧联调检查清单
@@ -903,7 +895,7 @@ GET /v1/internal/admin-query/tenants/default/kafka/dead-letters/{dead_id}
 | Command 生产 | `event_id/idempotency_key/tenant_code/biz_id` 稳定可追踪。 |
 | Result 消费 | `im.admin.command.result` 能更新操作单状态。 |
 | 死信消费 | `im.dead.letter` 能生成告警或待处理记录。 |
-| 审计消费 | `im.audit.event` 能落 HotGo `im_audit_events`，并可在 Kafka审计事件页面查看。 |
+| 审计 | 消费 `im.audit.event`，同步落 HotGo 审计表。 |
 | 配置接口 | `/internal/im-config/*` 支持 IM HMAC 调用。 |
 | 查询客户端 | 调 IM `/internal/admin-query/*` 带签名并处理 401/403/404/5xx。 |
 | 页面状态 | 后台页面显示 pending/running/succeeded/failed/dead，不把 Kafka 发送成功当业务成功。 |
@@ -912,7 +904,7 @@ GET /v1/internal/admin-query/tenants/default/kafka/dead-letters/{dead_id}
 
 | 检查项 | 验收标准 |
 | --- | --- |
-| Kafka 启动 | producer、consumer、outbox worker 正常启动。 |
+| Kafka 启动 | producer、consumer 正常启动，IM 侧无 DB outbox worker。 |
 | 租户路由 | `tenant_code` 能路由到正确租户库。 |
 | 消费幂等 | 重复 `event_id` 不重复执行业务。 |
 | 重试 | 可重试错误按退避时间重试。 |
@@ -922,9 +914,9 @@ GET /v1/internal/admin-query/tenants/default/kafka/dead-letters/{dead_id}
 | 用户治理 | 封禁/冻结踢下线，解封/恢复可登录，设备踢出只影响指定设备。 |
 | 群治理 | 群资料、角色、禁言、移除、转让群主全部生效。 |
 | 消息落库 | 私聊写 `im_messages`，群聊写 `im_group_messages`。 |
-| 文件生命周期 | 附件引用绑定到正确业务表。 |
-| 工作台事件 | 生成系统通知和 WS 业务事件。 |
-| 审计 | 关键动作进入 `im.audit.event`。 |
+| 文件生命周期 | 文件记录、附件引用、群文件同步落到正确业务表。 |
+| 工作台事件 | 同步生成系统通知和 WS 业务事件。 |
+| 审计 | IM 生产 `im.audit.event` 给 Admin/HotGo，IM 本地不消费审计 topic。 |
 
 ## 7. 回归用例
 
@@ -949,14 +941,14 @@ GET /v1/internal/admin-query/tenants/default/kafka/dead-letters/{dead_id}
 | 进入死信 | 查 `im_kafka_dead_letters.envelope/last_error`，修复后用重放命令。 |
 | 用户没有被踢下线 | 查目标 `user_id` 是否是 IM 用户 ID；是否连接在当前 IM 节点；跨节点踢人是否需要后续 Redis fanout 扩展。 |
 | 群治理未生效 | 查 `topic/version/actor_user_id` 是否正确，目标用户是否为群成员。 |
-| 消息未落库 | 查 `im.message.persist` 是否消费成功，以及 `im_kafka_consume_log.last_reason/last_error`。 |
-| 附件未绑定 | 查消息是否带附件、`im.file.lifecycle` 是否消费成功。 |
+| 消息未落库 | 私聊查 `im.message.persist`，群聊查 `im.group.message.persist` 是否消费成功，以及 `im_kafka_consume_log.last_reason/last_error`。 |
+| 附件未绑定 | 查消息是否带附件，以及同步绑定逻辑是否返回错误。 |
 | 内部 API 401 | 查 secret、签名文本、RequestURI、timestamp、nonce 是否一致。 |
 | 配置没有刷新 | 查是否发送 `im.config.event` 或 `im.cache.invalidate`，IM 是否清理了对应 namespace。 |
 
 ## 9. 联调完成标准
 
-1. 本文所有 P0/P1 用例通过：Kafka 基础、Admin Command、用户治理、群治理、消息异步落库、文件生命周期、工作台、缓存失效、死信。
+1. 本文所有 P0/P1 用例通过：Kafka 基础、Admin Command、用户治理、群治理、消息异步落库、文件生命周期同步处理、工作台同步处理、缓存失效、死信。
 2. Admin 操作单状态闭环可视化：pending -> running -> succeeded/failed/dead。
 3. IM 租户库无重复业务记录，Kafka 消费日志无异常堆积。
 4. 死信可查询、可忽略、可解决、可重放。
@@ -985,13 +977,13 @@ GET /v1/internal/admin-query/tenants/default/kafka/dead-letters/{dead_id}
 
 | 用例/链路 | 测试内容 | 结果 | 证据 |
 | --- | --- | --- | --- |
-| TC-KAFKA-001 | Kafka Topic 创建，IM consumer 启动。 | 通过 | IM 日志显示 `im.admin.command`、`im.config.event`、`im.cache.invalidate`、`im.message.persist`、`im.file.lifecycle`、`im.workbench.event` consumer started。 |
+| TC-KAFKA-001 | Kafka Topic 创建，IM consumer 启动。 | 通过 | IM 日志显示 `im.admin.command`、`im.config.event`、`im.cache.invalidate`、`im.message.persist`、`im.group.message.persist` consumer started。 |
 | TC-KAFKA-002 | Admin -> IM 内部查询 HMAC。 | 通过 | `GET /internal/admin-query/tenants/default/users?page=1&per_page=1` 返回 `code=0`，`total=29`。 |
 | TC-KAFKA-004 | IM -> Admin 内部配置 HMAC。 | 通过 | `GET /internal/im-config/tenants?limit=1000&state=active` 返回 `code=0` 和 default 租户。 |
 | TC-KAFKA-008/011 | `user.logout_all` 后台用户治理命令。 | 通过 | `tinode.im_kafka_consume_log` 中 `local-logout-fixed-*` 状态为 `succeeded`。 |
 | TC-KAFKA-023 | `im.cache.invalidate` 通用缓存失效。 | 通过 | `local-cache-*` 写入 `im_kafka_consume_log`，状态 `succeeded`，IM 日志显示 `kafka cache invalidate applied`。 |
 | TC-KAFKA-025 | 非法 `user.logout_all` 进入死信。 | 通过 | `local-logout-*` 状态为 `dead`，`im_kafka_dead_letters` 写入 `MALFORMED_COMMAND`。 |
-| TC-KAFKA-029 | 用户治理审计事件。 | 通过 | Admin 消费 `im.audit.event` 链路已验证；正式落表应为 `hotgo.im_audit_events`。 |
+| TC-KAFKA-029 | 用户治理审计事件。 | 通过 | IM 生产 `im.audit.event`，Admin/HotGo 消费后同步落审计表。 |
 
 本轮发现并处理：
 
@@ -1002,7 +994,7 @@ GET /v1/internal/admin-query/tenants/default/kafka/dead-letters/{dead_id}
 | IM 启动缺少 UID key | IM 报 `crypto/xtea: invalid key size 0`。 | Docker 启动显式传入 `UID_ENCRYPTION_KEY`、`API_KEY_SALT`、`AUTH_TOKEN_KEY`。 |
 | HotGo 表前缀不一致 | Admin 内部配置接口错误查询 `hg_im_tenant`，但 IM 业务/配置表正式表名应保持 `im_tenant`。 | 联调时暴露的是 Admin 查询/ORM 表名前缀问题；正式方案必须修 Admin 侧表名映射或 DAO 前缀逻辑，不能新增 `hg_im_*` 兼容表。 |
 | Admin result 消费格式不兼容 | Admin 消费 `im.admin.command.result` 报 `IM命令结果缺少command_id`。 | Admin consumer 已兼容 Kafka Envelope + payload 格式。 |
-| Admin 审计表前缀不一致 | Admin 消费 `im.audit.event` 错误查询 `hg_im_audit_events`，正式表名应保持 `im_audit_events`。 | 正式方案必须修 Admin 侧审计模型/DAO 表名映射，所有 `im_*` 业务表不加 `hg_` 前缀。 |
+| Admin 审计表前缀不一致 | Admin 消费 `im.audit.event` 后错误查询 `hg_im_audit_events`，正式表名应保持 `im_audit_events`。 | Admin/HotGo 同步写审计表时，仍需保证所有 `im_*` 业务表不加 `hg_` 前缀。 |
 
 本轮未覆盖，后续继续：
 
@@ -1046,11 +1038,11 @@ GET /v1/internal/admin-query/tenants/default/kafka/dead-letters/{dead_id}
 | TC-KAFKA-011 | 全端登出。 | 通过 | `user.logout_all` 消费 `succeeded`。 |
 | TC-KAFKA-012 | 注销与删除账号。 | 通过 | `user.account.cancel/user.account.delete` 使用本地测试账号验证，消费 `succeeded`。 |
 | TC-KAFKA-013 | 私聊消息异步落库。 | 通过 | `message.persist.p2p` 消费 `succeeded`，`im_messages` 写入测试消息。 |
-| TC-KAFKA-014 | 群聊消息异步落库。 | 通过 | `message.persist.group` 消费 `succeeded`，`im_group_messages` 写入测试群消息。 |
-| TC-KAFKA-016 | 文件上传完成事件。 | 通过 | `file.upload.completed` 消费 `succeeded`。 |
+| TC-KAFKA-014 | 群聊消息异步落库。 | 通过 | `im.group.message.persist` 消费 `message.persist.group`，`im_group_messages` 写入测试群消息。 |
+| TC-KAFKA-016 | 文件上传完成事件。 | 通过 | 文件上传完成不再走 Kafka。 |
 | TC-KAFKA-017 | 消息附件绑定。 | 通过 | 群聊附件绑定写入 `im_group_files`；私聊附件绑定修复后写入 `im_filemsglinks`。 |
-| TC-KAFKA-018 | 群文件登记与删除生命周期。 | 通过 | `group.file.created/group.file.deleted` 消费 `succeeded`。 |
-| TC-KAFKA-019 | 工作台会议事件。 | 通过 | `workbench.meeting.created` 消费 `succeeded`，写入 `im_system_notifications` 和 `im_business_events_outbox`。 |
+| TC-KAFKA-018 | 群文件登记与删除生命周期。 | 通过 | 群文件登记/删除同步落库。 |
+| TC-KAFKA-019 | 工作台会议事件。 | 通过 | 同步写入 `im_system_notifications` 和 `im_business_events_outbox`。 |
 | TC-KAFKA-022 | 配置事件失效。 | 通过 | `dictionary.updated` 消费 `succeeded`。 |
 | TC-KAFKA-023 | 通用缓存失效。 | 通过 | `cache.redis_object.invalidate` 消费 `succeeded`。 |
 | TC-KAFKA-024 | 群热消息缓存失效。 | 通过 | `cache.group_hot_messages.invalidate` 消费 `succeeded`。 |
@@ -1058,7 +1050,7 @@ GET /v1/internal/admin-query/tenants/default/kafka/dead-letters/{dead_id}
 | TC-KAFKA-026 | 死信查询。 | 通过 | `/internal/admin-query/tenants/default/kafka/dead-letters` 和详情接口返回 200。 |
 | TC-KAFKA-027 | 死信忽略与解决。 | 通过 | `kafka.dead_letter.ignore/resolve` 消费 `succeeded`，死信状态变为 `ignored/resolved`。 |
 | TC-KAFKA-028 | 死信重放。 | 通过 | `kafka.dead_letter.replay` 消费 `succeeded`，死信状态变为 `replayed`，`replay_count=1`。 |
-| TC-KAFKA-029 | 审计事件。 | 通过 | 用户治理、群治理、死信、文件等事件投递 `im.audit.event`；正式落表应为 `hotgo.im_audit_events`。 |
+| TC-KAFKA-029 | 审计事件。 | 通过 | `im.audit.event` 投递给 Admin/HotGo，消费侧同步落审计表。 |
 | TC-KAFKA-030 | IM Kafka Outbox 可靠投递。 | 通过 | Kafka 停止时 outbox `pending -> failed`；Kafka 恢复并重启 IM 后 `failed -> sent`，下游消费成功。 |
 
 本轮消费统计：