feat: batch kafka message persistence

docs/IM-Kafka接入方案.md

@@ -724,11 +724,19 @@ IM Server 已接入 `im.message.persist`，用于把在线发送链路和最终
 1. WS/HTTP 发送入口先完成权限校验，并由 topic 内存态分配 `seq_id`。
 2. Kafka 开启时，私聊发送入口直接生产 `im.message.persist`，群聊发送入口直接生产 `im.group.message.persist`，不查库、不落库、不写 DB outbox；客户端在 Kafka 写入成功后拿到已分配的 `seq_id`。
 3. Kafka 关闭时，继续走原同步落库路径，兼容本地和未接 Kafka 环境。
-4. 消费者按 `message_kind` 区分私聊与群聊：
-   - `p2p` 写入 `im_messages`。
-   - `group` 写入 `im_group_messages`。
+4. 私聊和群聊使用独立 Topic、独立消费组和独立物理表：私聊批量写入租户分表 `im_%03d_messages`，群聊按租户和月份批量写入 `im_%03d_group_messages_YYYYMM`。
 5. 消费侧复用 `im_kafka_consume_log` 做 `event_id + consumer_group` 幂等。
-6. 失败按统一退避重试 3 次，超过上限先投递 `im.dead.letter`，再由 dead letter consumer 写入 `im_kafka_dead_letters`。
+6. 消费者最多聚合 `message_batch_size` 条消息，在 `message_batch_wait_ms` 时间窗内形成批次并执行一条多值 `INSERT`。
+7. 批量写入失败后逐条降级；每条执行首次写入和 `message_single_retry_count` 次重试，默认共尝试 4 次。
+8. 单条仍失败时，完成 `im.dead.letter` 投递和 `im_kafka_dead_letters` 终态写入后才提交该批 offset；提交失败会持续重试，避免跳过失败消息。
+
+消息批量落库参数：
+
+| 配置项 | 默认值 | 说明 |
+| --- | ---: | --- |
+| `message_batch_size` | `100` | 单批最大消息数，上限 500。 |
+| `message_batch_wait_ms` | `10` | 从取得第一条消息开始的批次聚合等待时间。 |
+| `message_single_retry_count` | `3` | 批量失败后单条额外重试次数，不含首次执行。 |
 
 ### 11.10 IM Server 已接入的缓存失效消费