@tencentcloud/sdk-mcp 1.6.7 → 1.7.0

package/resource/knowledge/callkit/preset/react/api.md

@@ -1,8 +1,7 @@
-TUICallKit 是音视频通话组件的**含 UI 接口**，使用 TUICallKit API，您可以通过简单接口快速实现一个类微信的音视频通话场景；更详细的接入步骤，详见：快速接入 TUICallKit。
+TUICallKit 是音视频通话组件的**含 UI 接口**，使用 TUICallKit API，您可以通过简单接口快速实现一个类微信的音视频通话场景；更详细的接入步骤。
 
 > **说明：**
->
-> 为提供更优质的音视频通信能力， TUICallKit npm 包 [@trtc/calls-uikit-react](https://www.npmjs.com/package/@trtc/calls-uikit-react)、[@trtc/calls-uikit-vue](https://www.npmjs.com/package/@trtc/calls-uikit-vue)、[@trtc/calls-uikit-vue2](https://www.npmjs.com/package/@trtc/calls-uikit-vue2)、[@trtc/calls-uikit-vue2.6](https://www.npmjs.com/package/@trtc/calls-uikit-vue2.6) 在 4.0.0 版本进行了重大升级。
+> 为提供更优质的音视频通信能力， TUICallKit npm 包 [@trtc/calls-uikit-react](https://www.npmjs.com/package/@trtc/calls-uikit-react) 在 4.0.0 版本进行了重大升级。
 >
 
 ## API 概览
@@ -65,127 +64,6 @@ function handleAfterCalling() {
 }
 ```
 
-【Vue3】
-``` bash
-<template>
-   <TUICallKit
-    :allowedMinimized="true"
-    :allowedFullScreen="true"
-    :videoDisplayMode="VideoDisplayMode.CONTAIN"
-    :videoResolution="VideoResolution.RESOLUTION_1080P"
-    :beforeCalling="beforeCalling"
-    :afterCalling="afterCalling"
-    :onMinimized="onMinimized"
-    :kickedOut="handleKickedOut"
-    :statusChanged="handleStatusChanged"
-  />
-</template>
-
-<script lang="ts" setup>
-import { TUICallKit, TUICallKitAPI, VideoDisplayMode, VideoResolution, STATUS } from "@trtc/calls-uikit-vue";
-
-function beforeCalling(type: string, error: any) {
-  console.log("[TUICallkit Demo] beforeCalling:", type, error);
-}
-function afterCalling() {
-  console.log("[TUICallkit Demo] afterCalling");
-}
-function onMinimized(oldStatus: string, newStatus: string) {
-  console.log("[TUICallkit Demo] onMinimized: " + oldStatus + " -> " + newStatus);
-}
-function kickedOut() {
-  console.log("[TUICallkit Demo] kickedOut");
-}
-function statusChanged(args: { oldStatus: string; newStatus: string; }) {
-  const { oldStatus, newStatus } = args;
-  if (newStatus === STATUS.CALLING_C2C_VIDEO) {
-    console.log(`[TUICallkit Demo] statusChanged: ${oldStatus} -> ${newStatus}`);
-  }
-}
-</script>
-
-```
-
-【Vue2.7】
-``` javascript
-<template>
-   <TUICallKit
-    :allowedMinimized="true"
-    :allowedFullScreen="true"
-    :videoDisplayMode="VideoDisplayMode.CONTAIN"
-    :videoResolution="VideoResolution.RESOLUTION_1080P"
-    :beforeCalling="beforeCalling"
-    :afterCalling="afterCalling"
-    :onMinimized="onMinimized"
-    :kickedOut="handleKickedOut"
-    :statusChanged="handleStatusChanged"
-  />
-</template>
-
-<script lang="ts" setup>
-import { TUICallKit, TUICallKitAPI, VideoDisplayMode, VideoResolution, STATUS } from "@trtc/calls-uikit-vue2";
-
-function beforeCalling(type: string, error: any) {
-  console.log("[TUICallkit Demo] beforeCalling:", type, error);
-}
-function afterCalling() {
-  console.log("[TUICallkit Demo] afterCalling");
-}
-function onMinimized(oldStatus: string, newStatus: string) {
-  console.log("[TUICallkit Demo] onMinimized: " + oldStatus + " -> " + newStatus);
-}
-function kickedOut() {
-  console.log("[TUICallkit Demo] kickedOut");
-}
-function statusChanged(args: { oldStatus: string; newStatus: string; }) {
-  const { oldStatus, newStatus } = args;
-  if (newStatus === STATUS.CALLING_C2C_VIDEO) {
-    console.log(`[TUICallkit Demo] statusChanged: ${oldStatus} -> ${newStatus}`);
-  }
-}
-</script>
-```
-
-【Vue2.6】
-``` javascript
-<template>
-   <TUICallKit
-    :allowedMinimized="true"
-    :allowedFullScreen="true"
-    :videoDisplayMode="VideoDisplayMode.CONTAIN"
-    :videoResolution="VideoResolution.RESOLUTION_1080P"
-    :beforeCalling="beforeCalling"
-    :afterCalling="afterCalling"
-    :onMinimized="onMinimized"
-    :kickedOut="handleKickedOut"
-    :statusChanged="handleStatusChanged"
-  />
-</template>
-
-<script lang="ts" setup>
-import { TUICallKit, TUICallKitAPI, VideoDisplayMode, VideoResolution, STATUS } from "@trtc/calls-uikit-vue2.6";
-
-function beforeCalling(type: string, error: any) {
-  console.log("[TUICallkit Demo] beforeCalling:", type, error);
-}
-function afterCalling() {
-  console.log("[TUICallkit Demo] afterCalling");
-}
-function onMinimized(oldStatus: string, newStatus: string) {
-  console.log("[TUICallkit Demo] onMinimized: " + oldStatus + " -> " + newStatus);
-}
-function kickedOut() {
-  console.log("[TUICallkit Demo] kickedOut");
-}
-function statusChanged(args: { oldStatus: string; newStatus: string; }) {
-  const { oldStatus, newStatus } = args;
-  if (newStatus === STATUS.CALLING_C2C_VIDEO) {
-    console.log(`[TUICallkit Demo] statusChanged: ${oldStatus} -> ${newStatus}`);
-  }
-}
-</script>
-```
-
 ## TUICallKitAPI API 详情
 
 【React】
@@ -193,21 +71,6 @@ function statusChanged(args: { oldStatus: string; newStatus: string; }) {
 import { TUICallKitAPI } from "@trtc/calls-uikit-react";
 ```
 
-【Vue3】
-``` javascript
-import { TUICallKitAPI } from "@trtc/calls-uikit-vue";
-```
-
-【Vue2.7】
-``` javascript
-import { TUICallKitAPI } from "@trtc/calls-uikit-vue2";
-```
-
-【Vue2.6】
-``` javascript
-import { TUICallKitAPI } from "@trtc/calls-uikit-vue2.6";
-```
-
 ### init
 
 初始化 TUICallKit。
@@ -225,7 +88,7 @@ try {
 参数如下表所示：
 | 参数 | 类型 | 是否必填 | 含义 |
 | --- | --- | --- | --- |
-| SDKAppID | Number | 是 | 应用的 SDKAppID，您可以在实时音视频控制台中找到您的 SDKAppID，具体详见：开通服务。 |
+| SDKAppID | Number | 是 | 应用的 SDKAppID，您可以在实时音视频控制台中找到您的 SDKAppID，具体。 |
 | userID | String | 是 | 即用户名，只允许包含英文字母（a-z 和 A-Z）、数字（0-9）、连词符（-）和下划线（_）。<br><strong>注意：</strong>不支持同一个 userID 在两台不同的设备上同时进入同一个房间通话，否则会相互干扰。 |
 | userSig | String | 是 | 使用 SecretKey 对 SDKAppID、UserID 等信息进行加密，就可以得到 userSig。<br>它是一个鉴权用的票据，用于腾讯云识别当前用户是否能够使用 TRTC 的服务，获取方式请参见 <a href="https://cloud.tencent.com/document/product/647/17275">UserSig</a>。 |
 | tim | TencentCloudChat | 否 | tim 是 <a href="https://www.npmjs.com/package/@tencentcloud/chat">TencentCloudChat</a> SDK 的实例。 |
@@ -291,7 +154,6 @@ TUICallKitAPI.setLanguage("zh-cn"); // "en" | "zh-cn" | "ja_JP"
 设置当前用户昵称和头像。
 
 > **注意：**
->
 > **通话中使用该接口修改用户信息，UI 不会立即更新，需要等到下次通话才能看到变化**。
 >
 
@@ -410,13 +272,6 @@ try {
 
 隐藏功能按钮，目前仅支持 摄像头，麦克风和切换前后置按钮。
 
-【Vue】
-``` javascript
-import { TUICallKitAPI, FeatureButton } from "@trtc/calls-uikit-vue";
-
-TUICallKitAPI.hideFeatureButton(FeatureButton.Camera);
-```
-
 【React】
 ``` javascript
 import { TUICallKitAPI, FeatureButton } from "@trtc/calls-uikit-react";
@@ -463,12 +318,6 @@ TUICallKitAPI.setRemoteViewBackgroundImage(userId, url);
 
 设置通话界面布局模式。
 
-【Vue】
-``` javascript
-import { TUICallKitAPI, LayoutMode } from "@trtc/calls-uikit-vue";
-TUICallKitAPI.setLayoutMode(LayoutMode.LocalInLargeView);
-```
-
 【React】
 ``` javascript
 import { TUICallKitAPI, LayoutMode } from "@trtc/calls-uikit-react";

package/resource/knowledge/callkit/preset/vue/api.md

@@ -1,8 +1,7 @@
-TUICallKit 是音视频通话组件的**含 UI 接口**，使用 TUICallKit API，您可以通过简单接口快速实现一个类微信的音视频通话场景；更详细的接入步骤，详见：快速接入 TUICallKit。
+TUICallKit 是音视频通话组件的**含 UI 接口**，使用 TUICallKit API，您可以通过简单接口快速实现一个类微信的音视频通话场景；更详细的接入步骤。
 
 > **说明：**
->
-> 为提供更优质的音视频通信能力， TUICallKit npm 包 [@trtc/calls-uikit-react](https://www.npmjs.com/package/@trtc/calls-uikit-react)、[@trtc/calls-uikit-vue](https://www.npmjs.com/package/@trtc/calls-uikit-vue)、[@trtc/calls-uikit-vue2](https://www.npmjs.com/package/@trtc/calls-uikit-vue2)、[@trtc/calls-uikit-vue2.6](https://www.npmjs.com/package/@trtc/calls-uikit-vue2.6) 在 4.0.0 版本进行了重大升级。
+> 为提供更优质的音视频通信能力， TUICallKit npm 包 [@trtc/calls-uikit-vue](https://www.npmjs.com/package/@trtc/calls-uikit-vue)、[@trtc/calls-uikit-vue2](https://www.npmjs.com/package/@trtc/calls-uikit-vue2)、[@trtc/calls-uikit-vue2.6](https://www.npmjs.com/package/@trtc/calls-uikit-vue2.6) 在 4.0.0 版本进行了重大升级。
 >
 
 ## API 概览
@@ -46,25 +45,6 @@ TUICallKit 是音视频通话组件的**含 UI 接口**，使用 TUICallKit API
 
 ### 示例代码
 
-【React】
-``` bash
-import { TUICallKit, VideoDisplayMode, VideoResolution } from "@trtc/calls-uikit-react";
-
-<TUICallKit
-    videoDisplayMode={VideoDisplayMode.CONTAIN}
-    videoResolution={VideoResolution.RESOLUTION_1080P}
-    beforeCalling={handleBeforeCalling}
-    afterCalling={handleAfterCalling}
-/>
-
-function handleBeforeCalling(type: string, error: any) {
-  console.log("[TUICallkit Demo] handleBeforeCalling:", type, error);
-}
-function handleAfterCalling() {
-  console.log("[TUICallkit Demo] handleAfterCalling");
-}
-```
-
 【Vue3】
 ``` bash
 <template>
@@ -188,11 +168,6 @@ function statusChanged(args: { oldStatus: string; newStatus: string; }) {
 
 ## TUICallKitAPI API 详情
 
-【React】
-``` javascript
-import { TUICallKitAPI } from "@trtc/calls-uikit-react";
-```
-
 【Vue3】
 ``` javascript
 import { TUICallKitAPI } from "@trtc/calls-uikit-vue";
@@ -225,7 +200,7 @@ try {
 参数如下表所示：
 | 参数 | 类型 | 是否必填 | 含义 |
 | --- | --- | --- | --- |
-| SDKAppID | Number | 是 | 应用的 SDKAppID，您可以在实时音视频控制台中找到您的 SDKAppID，具体详见：开通服务。 |
+| SDKAppID | Number | 是 | 应用的 SDKAppID，您可以在实时音视频控制台中找到您的 SDKAppID，具体。 |
 | userID | String | 是 | 即用户名，只允许包含英文字母（a-z 和 A-Z）、数字（0-9）、连词符（-）和下划线（_）。<br><strong>注意：</strong>不支持同一个 userID 在两台不同的设备上同时进入同一个房间通话，否则会相互干扰。 |
 | userSig | String | 是 | 使用 SecretKey 对 SDKAppID、UserID 等信息进行加密，就可以得到 userSig。<br>它是一个鉴权用的票据，用于腾讯云识别当前用户是否能够使用 TRTC 的服务，获取方式请参见 <a href="https://cloud.tencent.com/document/product/647/17275">UserSig</a>。 |
 | tim | TencentCloudChat | 否 | tim 是 <a href="https://www.npmjs.com/package/@tencentcloud/chat">TencentCloudChat</a> SDK 的实例。 |
@@ -291,7 +266,6 @@ TUICallKitAPI.setLanguage("zh-cn"); // "en" | "zh-cn" | "ja_JP"
 设置当前用户昵称和头像。
 
 > **注意：**
->
 > **通话中使用该接口修改用户信息，UI 不会立即更新，需要等到下次通话才能看到变化**。
 >
 
@@ -417,13 +391,6 @@ import { TUICallKitAPI, FeatureButton } from "@trtc/calls-uikit-vue";
 TUICallKitAPI.hideFeatureButton(FeatureButton.Camera);
 ```
 
-【React】
-``` javascript
-import { TUICallKitAPI, FeatureButton } from "@trtc/calls-uikit-react";
-
-TUICallKitAPI.hideFeatureButton(FeatureButton.Camera);
-```
-
 参数列表：
 
 |参数|类型|是否必填|含义|
@@ -469,12 +436,6 @@ import { TUICallKitAPI, LayoutMode } from "@trtc/calls-uikit-vue";
 TUICallKitAPI.setLayoutMode(LayoutMode.LocalInLargeView);
 ```
 
-【React】
-``` javascript
-import { TUICallKitAPI, LayoutMode } from "@trtc/calls-uikit-react";
-TUICallKitAPI.setLayoutMode(LayoutMode.LocalInLargeView);
-```
-
 参数列表：
 
 |参数|类型|是否必填|含义|

package/resource/knowledge/chat/best-practice/common/avchatroom-message-loss-diagnosis.md

@@ -0,0 +1,71 @@
+---
+title: Web/小程序 Chat SDK 直播群（AVChatRoom）消息丢失排查与保障方案
+product: chat
+frameworks: [web, miniprogram]
+scope: platform_common
+tags: [AVChatRoom, 消息丢失, 直播群, MESSAGE_RECEIVED, 长轮询, MsgPriority, priority, restapi, 限频, 40条每秒]
+version_range: ">=3.0.0"
+---
+
+# Web/小程序 Chat SDK 直播群（AVChatRoom）消息丢失排查与保障方案
+
+## 1. 核心结论
+
+- 场景 1（批量发送时丢消息）：根因是业务侧消费 `MESSAGE_RECEIVED` 回调逻辑错误。该回调一次可能返回多条消息，必须读取完整列表 `event.data`。
+- 场景 2（刷屏时重要消息没收到）：根因是触发后台群消息限频。默认每群 `40` 条/秒，超过后会丢弃消息；可通过消息优先级提升重要消息保留概率。
+- 场景 3（网络不稳或长时间后台后丢消息）：符合直播群机制预期。应用后台超过 `2` 分钟后恢复，无法拉取超过缓存窗口的历史消息。
+- 直播群消息不存漫游，后台默认只缓存 `2` 分钟内消息且上限 `2000` 条；超过窗口或上限后，被淘汰消息无法通过长轮询补回。
+
+## 2. 字段语义对照
+
+| 字段/能力 | 作用 | 说明 |
+|---|---|---|
+| `EVENT.MESSAGE_RECEIVED` | 消息接收回调 | 一次回调可返回多条消息，业务必须遍历 `event.data` 全量处理 |
+| `priority`（SDK） | SDK 发消息优先级 | `createXXXMessage` 可设置，超限频时高优先级消息更不易被丢弃 |
+| `MsgPriority`（REST API） | REST API 发消息优先级 | 在消息体设置优先级，配合高并发场景保障关键通知 |
+| 群限频（默认 `40` 条/秒） | 后台流控阈值 | 超过阈值会发生丢弃，长轮询无法拉取被丢弃消息 |
+| 直播群缓存窗口（`2` 分钟/`2000` 条） | 临时缓存边界 | 超过时间或数量上限后，最早缓存消息会被清理 |
+
+## 3. 机制/时序
+
+业务发送消息（SDK/REST API）-> AVChatRoom 后台按群限频处理（默认 `40` 条/秒）-> 客户端通过长轮询接收消息并触发 `MESSAGE_RECEIVED` -> 业务消费回调列表。
+当应用长时间后台（超过 `2` 分钟）后回前台：WebSocket 重连成功 -> 恢复长轮询 -> 仅可拉取缓存窗口内消息（`2` 分钟且最多 `2000` 条）。
+
+## 4. 标准用法
+
+1. **修正接收逻辑（场景 1）**：在 `MESSAGE_RECEIVED` 中按 `event.data` 全量遍历处理，禁止只处理 `event.data[0]`。
+2. **保障重要消息（场景 2）**：将抽奖、商品上下架等关键消息设置为高优先级。
+   - SDK 发送：`createXXXMessage` 里设置 `priority`。
+   - REST API 发送：消息体设置 `MsgPriority`。
+3. **控制发送速率（场景 2）**：业务侧对批量消息做限流/合并，避免持续超过每群 `40` 条/秒。
+4. **处理后台恢复预期（场景 3）**：将“长时间后台后可能缺失直播群历史消息”作为产品预期告知，并用业务态兜底（如关键状态重拉接口）。
+
+## 5. 结果判定
+
+- 批量发消息压测时，`MESSAGE_RECEIVED` 回调中的每条 `event.data` 均被消费，无“只收第一条”问题。
+- 发送速率超过 `40` 条/秒时，低优先级消息优先被丢弃，高优先级关键通知到达率提升。
+- REST API 与 SDK 发送链路均已配置优先级字段（`MsgPriority` / `priority`）。
+- 应用后台超过 `2` 分钟后回前台，业务侧能通过兜底机制恢复关键业务状态。
+
+## 6. 常见误区
+
+- 误区 1：把 `MESSAGE_RECEIVED` 当作单条消息回调，只处理 `event.data[0]`。
+- 误区 2：高并发直播群不设置消息优先级，导致关键消息与刷屏消息同等级竞争。
+- 误区 3：把直播群当作漫游群使用，默认期望长时间后台后仍可补齐全部历史消息。
+
+## 7. 问题定义（检索辅助，极简）
+
+Web Chat SDK 在直播群（`AVChatRoom`）场景下出现“丢消息”现象，业务希望保证抽奖、商品上架/下架等重要消息不丢失。
+
+## 8. 同义问法覆盖（检索召回，极简）
+
+- AVChatRoom 为什么会丢消息？
+- 直播群刷屏时怎么保证商品下架消息一定送达？
+- `MESSAGE_RECEIVED` 回调一次返回多条消息怎么处理？
+- 直播群后台后重连为什么拉不到之前消息？
+
+## 9. 参考来源（可选）
+
+- `MESSAGE_RECEIVED` 事件说明：`https://web.sdk.qcloud.com/im/doc/v3/zh-cn/module-EVENT.html#.MESSAGE_RECEIVED`
+- SDK 消息优先级（`createTextMessage` 示例）：`https://web.sdk.qcloud.com/im/doc/v3/zh-cn/SDK.html#createTextMessage`
+- REST API `MsgPriority` 说明：`https://cloud.tencent.com/document/product/269/1629`

package/resource/knowledge/chat/best-practice/common/group-conversation-cleanup-on-system-notice.md

@@ -0,0 +1,67 @@
+---
+title: Web/小程序 Chat SDK 退群/解散群后会话残留移除方案
+product: chat
+frameworks: [web, miniprogram]
+scope: platform_common
+tags: [quitGroup, dismissGroup, deleteConversation, TIMGroupSystemNoticeElem, operationType, 会话列表, 退群, 解散群]
+version_range: ">=3.0.0"
+---
+
+# Web/小程序 Chat SDK 退群/解散群后会话残留移除方案
+
+## 1. 核心结论
+
+- `quitGroup` / `dismissGroup` 后会话残留是 SDK 体验设计行为：登录态有效时，群会话仍可保留用于查看历史消息。
+- 要实现“彻底从会话列表移除”，需要在接收群系统通知（`TIMGroupSystemNoticeElem`）后主动调用 `deleteConversation`。
+- 删除触发条件由 `message.payload.operationType` 决定：`4`（被踢出群组）、`5`（群组被解散）、`8`（用户主动退群）。
+- 仅依赖 `quitGroup` / `dismissGroup` 的返回结果，不会自动删除会话列表项。
+
+## 2. 字段语义对照
+
+| 字段/能力 | 作用 | 说明 |
+|---|---|---|
+| `TIMGroupSystemNoticeElem` | 群系统通知类型 | 标识群成员变更、解散、退群等系统事件 |
+| `message.payload.operationType` | 通知动作码 | `4` 被踢出、`5` 群解散、`8` 主动退群 |
+| `deleteConversation` | 删除会话接口 | 满足触发条件时调用，用于从会话列表移除对应群会话 |
+| `quitGroup` / `dismissGroup` | 群管理动作 | 执行退群/解散，不负责会话列表彻底清理 |
+
+## 3. 机制/时序
+
+业务调用 `quitGroup` 或 `dismissGroup` -> SDK 保留对应群会话（登录态有效）-> 收到 `TIMGroupSystemNoticeElem` -> 业务根据 `operationType` 判断是否触发删除 -> 命中 `4/5/8` 时调用 `deleteConversation` -> 会话列表移除该群会话。
+
+## 4. 标准用法
+
+1. 无 UI 集成场景：直接通过 `chat.on` 监听 `MESSAGE_RECEIVED`，在回调中处理群系统通知。
+2. 含 UI 集成场景：先从 `TUILogin.getContext()` 拿到 `chat` 实例，再通过 `chat.on` 监听 `MESSAGE_RECEIVED` 获取系统通知。
+3. 在回调中筛选 `TIMGroupSystemNoticeElem` 类型消息。
+4. 读取 `message.payload.operationType`，仅对 `4`、`5`、`8` 进入删除分支。
+5. 根据群会话 ID 调用 `deleteConversation` 删除会话，并在成功后刷新会话列表状态，避免本地缓存残留。
+
+## 5. 结果判定
+
+- 调用 `quitGroup` 后，收到 `operationType=8` 通知并成功触发 `deleteConversation`。
+- 调用 `dismissGroup` 后，收到 `operationType=5` 通知并成功移除群会话。
+- 被管理员踢出群时，收到 `operationType=4` 后会话被自动清理。
+- 会话列表刷新后不再出现目标群会话，且不会因系统通知重复回显。
+
+## 6. 常见误区
+
+- 误区 1：认为 `quitGroup` / `dismissGroup` 会自动删除会话列表项。
+- 误区 2：收到群系统通知后未读取 `operationType` 就直接忽略。
+- 误区 3：只做本地 UI 删除，不调用 `deleteConversation`，导致会话再次出现。
+
+## 7. 问题定义（检索辅助，极简）
+
+Web Chat SDK 调用 `quitGroup` 或 `dismissGroup` 后，会话列表中的群聊会话仍然存在；收到系统消息“您已退出该群聊”后，会话又出现在列表中。业务侧需要在退群/解散群后彻底移除该群聊会话。
+
+## 8. 同义问法覆盖（检索召回，极简）
+
+- 调用 `quitGroup` 后为什么群会话还在会话列表？
+- `dismissGroup` 后会话为什么又回来了？
+- 收到“您已退出该群聊”后如何删除会话？
+- 群系统通知如何联动 `deleteConversation`？
+
+## 9. 参考来源（可选）
+
+- GroupSystemNoticePayload：`https://web.sdk.qcloud.com/im/doc/v3/zh-cn/Message.html#.GroupSystemNoticePayload`
+- deleteConversation：`https://web.sdk.qcloud.com/im/doc/v3/zh-cn/SDK.html#deleteConversation`

package/resource/knowledge/chat/best-practice/common/image-message-url-lifecycle.md

@@ -0,0 +1,63 @@
+---
+title: Chat SDK 图片消息 URL 的生命周期（blob 与 imageUrl）
+product: chat
+frameworks: [web, miniprogram]
+scope: platform_common
+tags: [sendMessage, createImageMessage, imageInfoArray, imageUrl, url, blob, https, 图片消息, 上传进度, 生命周期]
+version_range: ">=3.0.0"
+---
+
+# Chat SDK 图片消息 URL 的生命周期（blob 与 imageUrl）
+
+## 1. 核心结论
+
+- `imageInfoArray[x].url` 主要用于本地预览，发送成功后仍是 `blob:` 内存 URL。
+- 需要云端可访问 URL 时，读取发送成功返回消息中的 `imageInfoArray[x].imageUrl`。
+- 刷新并重新登录后，拉取漫游消息时，`imageInfoArray[x].url` 为服务端 URL。
+- 需要上传进度时，在 `createImageMessage` 时传入 `onProgress` 回调。
+
+## 2. 字段语义对照
+
+| 字段/能力 | 阶段 | 语义 |
+|---|---|---|
+| `imageInfoArray[x].url` | 发送中/发送后 | 本地预览地址，可为 `blob:`，不保证自动更新为云端地址 |
+| `imageInfoArray[x].imageUrl` | 发送成功后 | 服务端可访问地址，作为对外可访问 URL 使用 |
+| `onProgress` | 上传过程中 | 文件上传进度回调，用于展示上传进度 |
+
+## 3. 机制/时序
+
+`createImageMessage` -> `sendMessage` -> 内部上传流程 -> 上传成功并发送到 IM 后台 -> 从返回消息读取 `imageInfoArray[x].imageUrl` -> 刷新重登后拉取漫游消息时 `imageInfoArray[x].url` 为服务端 URL。
+
+## 4. 标准用法
+
+1. 调用 `createImageMessage` 创建图片消息（如需进度，传入 `onProgress`）。
+2. 调用 `sendMessage` 发送消息。
+3. 发送成功后，从返回消息中读取 `imageInfoArray[x].imageUrl` 作为云端 URL。
+4. 前端渲染图片的正确方式：渲染消息时读取 `imageInfoArray[x].url` 即可，发送时使用 `blob` 地址能够更快渲染图片。
+
+## 5. 结果判定
+
+- 发送后检查同一条消息：
+  - `imageInfoArray[x].url` 仍为 `blob:`；
+  - `imageInfoArray[x].imageUrl` 为服务端可访问地址。
+- 刷新并重新登录后，拉取历史消息时，`imageInfoArray[x].url` 为服务端 URL。
+
+## 6. 常见误区
+
+- 误区 1：默认认为 `url` 会在上传后自动变成云端链接。
+
+## 7. 问题定义（检索辅助，极简）
+
+用户在发送图片消息后，看到 `imageInfoArray[x].url` 仍是 `blob:` 本地 URL，期望它自动变成腾讯云 `https` URL；同时希望明确上传完成后应读取哪个字段作为最终可访问地址。
+
+## 8. 同义问法覆盖（检索召回，极简）
+
+- 图片消息发送后 `url` 为什么还是 `blob:`？
+- 云端 `https` 图片地址应该从哪个字段取？
+- `sendMessage` 成功后如何拿图片最终 URL？
+- `imageInfoArray[x].url` 和 `imageInfoArray[x].imageUrl` 有什么区别？
+- 刷新后历史消息里的图片 URL 为什么变了？
+
+## 9. 参考来源（可选）
+
+- Message 结构文档：[Message](https://web.sdk.qcloud.com/im/doc/v3/zh-cn/Message.html)

package/resource/knowledge/chat/best-practice/common/login-repeat-2025-diagnosis.md

@@ -0,0 +1,65 @@
+---
+title: Web Chat SDK login 返回 2025（重复登录）排查与修复
+product: chat
+frameworks: [web, miniprogram]
+scope: platform_common
+tags: [login, 2025, 重复登录, repeatLogin, web, miniprogram, 并发调用, 防抖]
+version_range: ">=3.0.0"
+---
+
+# Web Chat SDK login 返回 2025（重复登录）排查与修复
+
+## 1. 核心结论
+
+- `2025` 的直接原因是业务侧在短时间内连续调用 `login`，且 SDK 还未收到第一次登录请求的后台回包。
+- 在首次 `login` 发起后的约 `15s` 窗口内，若前一次登录仍未回包，SDK 会直接拦截后续 `login`，并返回 `2025`。
+- 如果 SDK 已经收到登录回包，后续使用同一 `userID` 再次调用 `login`，不会走 `2025` 拦截分支，而是在 `login.then` 中返回 `imResponse.data.repeatLogin = true`。
+- 解决方向是业务侧治理 `login` 调用逻辑：保证同一会话只存在一个进行中的 `login` 请求。
+
+## 2. 字段语义对照
+
+| 字段/能力 | 作用 | 说明 |
+|---|---|---|
+| 错误码 `2025` | 重复登录拦截信号 | 前一次 `login` 未回包时，短时间内再次调用被 SDK 直接拦截 |
+| `imResponse.data.repeatLogin` | 重复登录标识 | SDK 已收到回包后，再次使用同一 `userID` 登录时在 `then` 中返回 `true` |
+| `login` in-flight 状态 | 并发控制关键状态 | 业务侧需确保同一时刻仅一个 `login` 在执行 |
+
+## 3. 机制/时序
+
+第一次调用 `login` -> SDK 发起登录请求 -> 后台回包未返回 -> 业务侧在约 `15s` 内再次调用 `login` -> SDK 直接拦截并返回 `2025`。
+第一次调用 `login` -> SDK 已收到后台回包 -> 业务侧再次使用同一 `userID` 调用 `login` -> 在 `login.then` 中拿到 `imResponse.data.repeatLogin = true`。
+
+## 4. 标准用法
+
+1. 业务侧实现登录单飞（single-flight）：同一 `userID` 在前一次 `login` 完成前禁止重复发起。
+2. 为 `login` 增加状态机（`idle`/`logging_in`/`logged_in`）或 Promise 复用，复用进行中的登录结果。
+3. 收到 `2025` 时不立即重试，先等待当前 in-flight 登录完成，再按结果决定后续动作。
+4. 在 `login.then` 中检查 `imResponse.data.repeatLogin`，按“已登录”分支处理，不重复初始化会话。
+
+## 5. 结果判定
+
+- 同一 `userID` 连续触发登录时，业务侧只发出一次真实 `login` 请求。
+- 压测快速点击登录入口，不再出现 `2025`。
+- 已回包后再次调用 `login` 时，可在 `then` 中稳定观察到 `repeatLogin` 标识并走预期分支。
+- 登录态初始化逻辑仅执行一次，无重复拉取会话或重复监听。
+
+## 6. 常见误区
+
+- 误区 1：收到 `2025` 后立即再次调用 `login`，造成重复拦截循环。
+- 误区 2：把 `2025` 与 `repeatLogin=true` 当成同一阶段错误处理。
+- 误区 3：页面 `onShow`、路由切换、重连回调中未做幂等保护，导致并发登录。
+
+## 7. 问题定义（检索辅助，极简）
+
+Web Chat SDK 调用 `login` 时，在短时间内重复触发登录请求，会返回 `2025`。业务侧需要明确：`2025` 在什么条件下触发，以及与 `imResponse.data.repeatLogin = true` 的区别。
+
+## 8. 同义问法覆盖（检索召回，极简）
+
+- Web IM SDK 调 `login` 为什么报 2025？
+- `login` 返回 2025 是什么含义？
+- 什么情况下会出现重复登录错误码 2025？
+- `repeatLogin=true` 和 `2025` 有什么区别？
+
+## 9. 参考来源（可选）
+
+- Chat SDK `login` 文档：`https://web.sdk.qcloud.com/im/doc/v3/zh-cn/SDK.html#login`

package/resource/knowledge/chat/best-practice/common/message-read-report-and-receipt.md

@@ -0,0 +1,72 @@
+---
+title: Web Chat SDK 会话已读上报和消息已读回执方案（setMessageRead 与 sendMessageReadReceipt）
+product: chat
+frameworks: [web, miniprogram]
+scope: platform_common
+tags: [setMessageRead, sendMessageReadReceipt, 已读回执, MESSAGE_READ_BY_PEER, MESSAGE_READ_RECEIPT_RECEIVED, needReadReceipt, 群消息已读]
+version_range: ">=3.0.0"
+---
+
+# Web Chat SDK 会话已读上报和消息已读回执方案（setMessageRead 与 sendMessageReadReceipt）
+
+## 1. 核心结论
+
+- 进入会话后自动发送消息级已读回执的推荐流程是：先通过 `getMessageList` 拉漫游消息，再调用 `sendMessageReadReceipt` 上报对应消息已读。
+- `setMessageRead` 是会话维度已读上报：调用成功会清空当前会话未读数；单聊场景对端可通过 `MESSAGE_READ_BY_PEER` 更新消息已读状态。
+- `sendMessageReadReceipt` 是单条消息维度已读回执：不影响会话未读数，仅影响消息已读/未读状态；群消息要实现消息级已读状态必须使用该能力。
+- 消息已读回执能力有使用限制：体验版/标准版不可用；创建消息需设置 `needReadReceipt=true`；群已读回执要求群人数上限 `200` 且需在控制台开启群消息已读回执开关（控制台 > 功能配置 > 群组配置 > 群消息已读回执）。
+
+## 2. 字段语义对照
+
+| 字段/能力 | 作用 | 说明 |
+|---|---|---|
+| `setMessageRead` | 会话维度已读上报 | 清空当前会话未读数；单聊可触发对端 `MESSAGE_READ_BY_PEER` |
+| `sendMessageReadReceipt` | 消息维度已读回执 | 不清空会话未读数，只更新消息已读/未读状态 |
+| `needReadReceipt` | 消息已读回执开关 | 创建消息时必须设为 `true` 才能使用消息级回执 |
+| `MESSAGE_READ_BY_PEER` | 单聊对端已读事件 | 用于更新单聊消息已读状态 |
+| `MESSAGE_READ_RECEIPT_RECEIVED` | 消息回执接收事件 | 用于处理收到的消息已读回执更新 |
+
+## 3. 机制/时序
+
+进入会话 -> 调用 `getMessageList` 拉取漫游消息 -> 将消息列表传给 `sendMessageReadReceipt`（SDK 内部过滤处理）-> SDK 下发已读回执事件（如 `MESSAGE_READ_RECEIPT_RECEIVED`）-> 业务更新消息已读/未读展示。
+若调用 `setMessageRead`：会话未读数被清空；单聊对端可收到 `MESSAGE_READ_BY_PEER`。
+
+## 4. 标准用法
+
+1. 会话进入时先调用 `getMessageList` 拉取消息列表。
+2. 将 `getMessageList` 返回的消息列表直接传给 `sendMessageReadReceipt`，由 SDK 内部过滤并完成消息级已读上报。
+3. 仅在需要处理会话未读数时调用 `setMessageRead`，不要用它替代群消息已读回执。
+4. 创建需要回执的消息时设置 `needReadReceipt = true`。
+5. 订阅并处理 `MESSAGE_READ_BY_PEER`、`MESSAGE_READ_RECEIPT_RECEIVED`，同步更新消息已读状态。
+
+## 5. 结果判定
+
+- 进入群聊后，拉取到的消息可成功触发 `sendMessageReadReceipt`。
+- 调用 `sendMessageReadReceipt` 后，会话未读数不被清空，但消息已读状态发生更新。
+- 调用 `setMessageRead` 后，会话未读数被清空，单聊对端可观测到 `MESSAGE_READ_BY_PEER`。
+- 群聊已读场景下，已正确开通套餐、开启控制台开关，且群人数不超过 `200`。
+
+## 6. 常见误区
+
+- 误区 1：用 `setMessageRead` 代替 `sendMessageReadReceipt` 实现群消息已读状态。
+- 误区 2：未设置 `needReadReceipt=true` 就期望收到消息级已读回执。
+- 误区 3：未开通旗舰版以上套餐或未开启群消息已读回执开关就上线群已读能力。
+
+## 7. 问题定义（检索辅助，极简）
+
+Web 端进入群聊会话后，如何自动发送已读回执给消息发送方？`setMessageRead` 和 `sendMessageReadReceipt` 的区别是什么？
+
+## 8. 同义问法覆盖（检索召回，极简）
+
+- 进入会话后怎么自动上报已读？
+- 群聊已读/未读显示要用哪个接口？
+- `setMessageRead` 和 `sendMessageReadReceipt` 有什么区别？
+- 为什么调用 `setMessageRead` 后消息已读状态没有按预期变化？
+
+## 9. 参考来源（可选）
+
+- 套餐购买：`https://buy.cloud.tencent.com/avc?from=17182`
+- setMessageRead：`https://web.sdk.qcloud.com/im/doc/v3/zh-cn/SDK.html#setMessageRead`
+- sendMessageReadReceipt：`https://web.sdk.qcloud.com/im/doc/v3/zh-cn/SDK.html#sendMessageReadReceipt`
+- MESSAGE_READ_BY_PEER：`https://web.sdk.qcloud.com/im/doc/v3/zh-cn/module-EVENT.html#.MESSAGE_READ_BY_PEER`
+- MESSAGE_READ_RECEIPT_RECEIVED：`https://web.sdk.qcloud.com/im/doc/v3/zh-cn/module-EVENT.html#.MESSAGE_READ_RECEIPT_RECEIVED`