docs: update WishFulfilled knowledge base

wishfulfilled-wiki/05_需求文档/通用IM业务流程与接口频率限制说明.md

@@ -0,0 +1,309 @@
+# 通用 IM 业务流程与接口频率限制说明
+
+更新时间：2026-05-26
+
+## 1. 文档目标
+
+本文用于新的 IM 子系统重构设计，目标是在功能保持一致的前提下，将现有 IM 业务抽象成通用流程，便于后续拆分服务、设计数据模型、规划 Kafka 消费链路、控制腾讯云 IM REST API 调用频率。
+
+## 2. 总体架构
+
+通用 IM 链路由以下组件组成：
+
+| 组件 | 职责 |
+| --- | --- |
+| App 客户端 | 用户通过 App 使用腾讯云 IM SDK 发送和接收消息 |
+| 腾讯云 IM | 负责即时消息投递、账号体系、消息格式、离线推送、服务端 REST API、回调触发 |
+| App 后台 | 接收腾讯云 IM 回调，识别需要管理后台处理的消息，并写入 Kafka |
+| Kafka | 解耦 App 后台与管理后台 IM 子系统，承接入站消息、推送消息、异步任务 |
+| IM 子系统 / 管理后台 | 消费 Kafka 消息，维护本地会话、消息、工单、分配、状态流转和客服操作 |
+| 本地数据库 | 作为管理后台 IM 业务的长期数据源，保存消息流水、会话状态、工单状态、操作记录 |
+| Redis / 缓存 | 保存在线状态、分配触发标记、限流计数、幂等键、临时游标 |
+| WebSocket / 站内通知 | 将新消息、分配变化、发送结果、状态变化推送给管理后台前端 |
+
+## 3. 总体消息流
+
+```mermaid
+flowchart TD
+    A["用户在 App 发送 IM 消息"] --> B["腾讯云 IM SDK 投递消息"]
+    B --> C["腾讯云 IM 回调 App 后台"]
+    C --> D["App 后台校验回调并识别管理后台相关消息"]
+    D --> E["App 后台写入 Kafka"]
+    E --> F["IM 子系统消费 Kafka"]
+    F --> G["幂等校验与消息解析"]
+    G --> H["写入本地消息表"]
+    H --> I["更新会话、工单、未读数、最后消息时间"]
+    I --> J["触发分配、提醒或状态流转"]
+    J --> K["管理后台客服前端展示"]
+```
+
+核心原则：
+
+1. App 客户端消息先进入腾讯云 IM。
+2. 腾讯云 IM 将消息回调给 App 后台。
+3. App 后台不直接写管理后台业务库，而是将管理后台关心的消息写入 Kafka。
+4. 管理后台 IM 子系统消费 Kafka 后入库，并维护本地会话、工单和客服状态。
+5. 管理后台后续展示、检索、统计、客服处理，应以本地数据库为主数据源。
+
+## 4. 核心数据模型
+
+新子系统建议至少抽象以下数据对象：
+
+| 对象 | 说明 |
+| --- | --- |
+| IM 账号 | 业务用户、品牌账号、客服账号在腾讯云 IM 中的账号映射 |
+| 消息 Message | 本地保存的消息流水，包含方向、发送方、接收方、消息类型、消息体、腾讯消息 ID、业务扩展字段 |
+| 会话 Conversation | 用户与品牌/客服之间的当前会话指针，包含未读数、最后消息时间、当前工单 ID |
+| 工单 Ticket / ChatRecord | 一次客服处理过程，包含状态、负责人、团队、首次响应时间、关闭时间 |
+| 分配记录 Assignment | 自动分配、手动接手、转接、释放、代班等操作记录 |
+| 节点日志 NodeLog | 工单生成、分配、首次回复、转接、未解决、转化中、关闭等关键节点 |
+| 推送任务 PushTask | 运营或策略创建的 IM 推送任务 |
+| 推送记录 PushRecord | 单个用户、单条内容的实际待发送记录和发送结果 |
+
+## 5. 入站消息流程
+
+### 5.1 用户发送消息
+
+1. 用户在 App 中通过腾讯云 IM SDK 发送文本、图片、视频、自定义卡片或其他消息。
+2. 腾讯云 IM 完成消息投递，并根据配置触发服务端回调。
+3. App 后台接收腾讯云 IM 回调，完成签名、来源、事件类型和消息结构校验。
+4. App 后台判断该消息是否需要管理后台处理。
+5. 需要管理后台处理的消息，由 App 后台写入 Kafka。
+6. IM 子系统消费 Kafka，执行幂等校验，解析消息体。
+7. IM 子系统写入本地消息流水，并更新会话和工单状态。
+8. 若消息产生新的待处理工单，则进入分配流程。
+9. 管理后台前端通过列表查询、WebSocket 或站内通知看到新消息。
+
+### 5.2 幂等与顺序
+
+腾讯云回调、App 后台写 Kafka、Kafka 消费都可能出现重试，因此 IM 子系统必须做幂等处理。
+
+建议幂等键优先级：
+
+1. 腾讯云 IM 消息唯一标识。
+2. 发送方、接收方、消息随机数、消息序列号、消息时间组合。
+3. App 后台写入 Kafka 时生成的业务事件 ID。
+
+同一会话内需要尽量按消息时间和腾讯云消息顺序展示。若存在乱序到达，应允许入库后按消息时间、序列号或腾讯消息 ID 排序展示。
+
+## 6. 客服处理流程
+
+### 6.1 会话和工单状态
+
+通用状态建议如下：
+
+| 状态 | 说明 |
+| --- | --- |
+| 待接入 | 用户有新消息，尚未分配或尚未被客服处理 |
+| 服务中 | 客服已接入并正在处理 |
+| 已转接 | 工单被转给其他客服或团队，等待新处理人接手 |
+| 未解决 | 客服标记暂未解决，需要后续跟进 |
+| 转化中 | 进入转化或商机跟进阶段 |
+| 已关闭 | 本次客服处理结束 |
+
+状态值可以由新子系统自行定义，但需要保证列表筛选、统计口径、自动关闭、转接和重新打开逻辑一致。
+
+### 6.2 自动分配
+
+自动分配通常在新消息入库后触发：
+
+1. 找到待接入工单。
+2. 根据品牌、站点、团队、语言、业务线等条件确定可服务团队。
+3. 获取在线客服列表。
+4. 按客服接单上限、当前处理数、最近分配时间等规则筛选。
+5. 选择目标客服并更新工单负责人。
+6. 写入分配记录和节点日志。
+7. 通知管理后台前端。
+
+建议将分配能力独立成可重试任务，避免 Kafka 入站消费被复杂分配逻辑拖慢。
+
+### 6.3 客服打开会话
+
+客服打开会话时，系统通常需要：
+
+1. 校验客服是否在线、是否有处理权限。
+2. 查询会话和工单详情。
+3. 拉取本地消息列表。
+4. 清理当前客服视角下的未读数。
+5. 必要时将工单从待接入或已转接推进到服务中。
+6. 记录读取、接手或首次处理节点。
+
+### 6.4 客服发送消息
+
+客服发送消息的通用链路：
+
+```mermaid
+flowchart TD
+    A["客服在管理后台发送消息"] --> B["IM 子系统校验权限、会话、工单状态"]
+    B --> C["组装腾讯云 IM 消息体"]
+    C --> D["调用腾讯云 REST API"]
+    D --> E{"腾讯云返回结果"}
+    E -->|成功| F["写入本地消息流水并更新会话"]
+    E -->|失败| G["记录失败原因并进入重试或人工处理"]
+    F --> H["通知管理后台前端发送成功"]
+    G --> I["通知管理后台前端发送失败"]
+```
+
+发送前建议校验：
+
+1. 当前客服必须具备客服身份。
+2. 当前客服必须有该会话或工单处理权限。
+3. 工单不能处于已关闭状态，除非业务允许重新打开。
+4. 消息体大小、消息类型、媒体文件大小必须符合业务和腾讯云限制。
+5. 对运营推送和客服消息应区分业务来源，方便统计和风控。
+
+### 6.5 转接、释放和自动关闭
+
+通用处理规则：
+
+1. 手动转接给个人：校验当前处理人权限，更新负责人，记录转接节点。
+2. 手动转接给团队：记录目标团队，等待团队内客服接手或自动分配。
+3. 客服离线释放：如果负责人离线且有未读用户消息，可释放为待分配。
+4. 超时未处理释放：待接入或已转接超过配置时间后，重新进入分配池。
+5. 自动关闭：服务中会话在配置时间内无新用户消息或无新客服动作时，自动关闭。
+
+## 7. 运营 IM 推送流程
+
+运营推送与客服消息都可能调用腾讯云 IM REST API，但应在业务上区分：
+
+```mermaid
+flowchart TD
+    A["后台创建推送任务"] --> B["审核或直接进入待发送"]
+    B --> C["按标签、站点、产品、用户状态筛选目标人群"]
+    C --> D["生成 PushRecord"]
+    D --> E["写入 Kafka 推送队列"]
+    E --> F["推送消费者限速发送"]
+    F --> G["调用 sendmsg 或 batchsendmsg"]
+    G --> H["保存腾讯云返回结果"]
+    H --> I["汇总任务完成状态"]
+```
+
+建议：
+
+1. 大批量运营推送优先评估 `batchsendmsg`，减少单发接口压力。
+2. 推送消费者必须按 SDKAppID 和接口维度做限速。
+3. 推送记录需要保存发送状态、错误码、重试次数、腾讯云返回结果。
+4. 发送失败应区分可重试错误和不可重试错误。
+5. 推送消息应写入业务扩展字段，便于后续归因和统计。
+
+## 8. 本地存储与历史消息
+
+管理后台 IM 子系统建议以本地数据库作为长期主数据源。
+
+腾讯云 IM 漫游消息适合用于消息补偿、短期核对或异常排查，不建议作为客服记录、统计报表和审计的唯一长期来源。原因是历史消息存储时长与套餐、增值服务和控制台配置有关，且可能产生额外费用。
+
+建议本地保存：
+
+1. 入站用户消息。
+2. 客服发送消息。
+3. 系统提示消息。
+4. 运营推送消息及发送结果。
+5. 转接、关闭、分配、未解决、转化等节点日志。
+
+## 9. 腾讯云 IM 接口频率限制说明
+
+以下为腾讯云官方文档口径，实际限制可能随套餐、数据中心、控制台配置和商务协议变化，最终以腾讯云控制台和合同为准。
+
+### 9.1 通用限制
+
+| 项目 | 限制 |
+| --- | --- |
+| 单聊、群聊单条消息长度 | 最大 12KB |
+| UserID | 长度不超过 32 字节，不支持特殊字符，建议使用英文字母或数字 |
+| REST API 通用调用频率 | 多数 REST API 默认最高 200 次/秒 |
+| 导入多个账号、删除账号、查询账号 | 默认最高 100 次/秒 |
+| 查询在线状态 | 单次请求最多查询 500 个用户 |
+| 批量发单聊消息 | 单次最多给 500 个用户发送 |
+| 导入多个账号 | 单次最多导入 100 个用户名 |
+| 单个用户好友数 | 默认支持 3000 个好友 |
+| 单个用户黑名单数 | 最多 1000 人 |
+
+### 9.2 常用 REST API 频率
+
+| 接口 | 默认频率限制 | 叠加包增量 | 说明 |
+| --- | --- | --- | --- |
+| `v4/openim/sendmsg` 单发单聊消息 | 200 次/秒 | 每个叠加包 +100 次/秒 | 体验版和开发版每日累计发送量限制为 1000 条/天 |
+| `v4/openim/batchsendmsg` 批量发单聊消息 | 200 次/秒，同时 12000 条/分钟 | 每个叠加包 +6000 条/分钟 | 条数按接收方数量计算，一次发给 500 人计 500 条 |
+| `v4/profile/portrait_set` 设置资料 | 200 次/秒 | 每个叠加包 +100 次/秒 | 用于更新头像、昵称等资料 |
+| `v4/profile/portrait_get` 拉取资料 | 200 次/秒 | 每个叠加包 +100 次/秒 | 用于查询资料 |
+| `v4/openim/query_online_status` 查询在线状态 | 200 次/秒 | 每个叠加包 +100 次/秒 | 单次最多查询 500 个用户 |
+| `v4/openim/get_c2c_unread_msg_num` 查询单聊未读数 | 200 次/秒 | 每个叠加包 +100 次/秒 | 如新系统需要同步未读数需注意限频 |
+| `v4/group_open_http_svc/send_group_msg` 群内发普通消息 | 200 次/秒 | 每个叠加包 +100 次/秒 | 单个群发送频率上限为 40 条/秒 |
+| `v4/sns/black_list_get` 拉取黑名单 | 200 次/秒 | 每个叠加包 +100 次/秒 | 关系链相关能力需控制调用频率 |
+
+### 9.3 调频收费说明
+
+腾讯云 IM 服务端 API 调频属于增值服务。官方公告口径为：
+
+| 数据中心 | 服务端 API 调用频率叠加包价格 |
+| --- | --- |
+| 国内数据中心 | 10 元/个/日，日结后付费 |
+| 境外数据中心 | 20 元/个/日，日结后付费 |
+
+注意事项：
+
+1. 调频对单个 SDKAppID 生效，多个 SDKAppID 需要分别配置。
+2. 每个调频项按当日配置的最高数值计费，次日出账。
+3. 体验版不支持调整服务端 API 调用频率上限。
+4. 如果新子系统存在大规模运营推送，必须提前评估 `sendmsg` 与 `batchsendmsg` 的峰值。
+
+## 10. 新子系统设计建议
+
+### 10.1 按接口维度做限流
+
+建议在 IM 子系统服务端增加统一腾讯云 IM Client，并在 Client 内按以下维度做限流：
+
+1. SDKAppID。
+2. API 路径，例如 `openim/sendmsg`、`openim/batchsendmsg`。
+3. 业务来源，例如客服消息、运营推送、系统通知。
+
+Kafka 消费者不能只依赖消费并发控制，否则高峰期可能瞬间打满腾讯云 API 限频。
+
+### 10.2 单发和批量发送分流
+
+建议策略：
+
+| 场景 | 推荐接口 |
+| --- | --- |
+| 客服一对一即时回复 | `openim/sendmsg` |
+| 系统给单个用户发送提示 | `openim/sendmsg` |
+| 运营批量推送相同或相似内容 | 优先评估 `openim/batchsendmsg` |
+| 需要强个性化卡片、每人内容不同 | 可用 `sendmsg`，但必须限速 |
+
+### 10.3 错误处理和重试
+
+建议将发送结果分为：
+
+1. 成功：腾讯云返回 `ErrorCode=0` 且业务认为发送完成。
+2. 部分成功：批量发送时部分账号失败，需要保存失败账号列表。
+3. 可重试失败：网络异常、超时、腾讯云内部错误、限频。
+4. 不可重试失败：账号不存在、消息体非法、权限错误、消息包超长。
+
+重试建议采用延迟重试，并设置最大重试次数。超过次数后进入失败表或死信队列，供人工排查。
+
+### 10.4 回调链路可观测性
+
+入站链路建议记录以下指标：
+
+1. 腾讯云回调接收量。
+2. App 后台写 Kafka 成功量和失败量。
+3. Kafka 积压量。
+4. IM 子系统消费延迟。
+5. 入库成功量和幂等重复量。
+6. 会话创建量、工单创建量、分配成功量。
+
+发送链路建议记录：
+
+1. 每个 API 的 QPS。
+2. 限流等待时间。
+3. 腾讯云错误码分布。
+4. 发送成功率。
+5. 可重试失败量和最终失败量。
+
+## 11. 参考来源
+
+- 腾讯云 IM 使用限制：https://cloud.tencent.com/document/product/269/32429
+- 腾讯云 IM 单发单聊消息：https://cloud.tencent.com/document/product/269/2282
+- 腾讯云 IM 批量发单聊消息：https://cloud.tencent.com/document/product/269/1612
+- 腾讯云 IM 服务端 API 调频收费公告：https://cloud.tencent.com/document/product/269/93324
+