@tencentcloud/sdk-mcp 1.7.7 → 1.7.9-beta.1

package/resource/knowledge/iot/app/wechat-call/device-call-miniprogram.md

@@ -0,0 +1,204 @@
+---
+product: iot
+framework:
+  - minprogram
+types:
+  - feature
+retrievable_scope: always
+feature_domain: app
+---
+
+TWeCall 是腾讯云物联网开发平台提供的设备与微信小程序之间的双向音视频通话能力。设备端一键呼叫后，微信通过「服务通知」强提醒用户，点击即可进入通话，达到微信原生通话体验。
+
+本文将介绍小程序端如何接入 TWeCall（微信通话），实现**接听设备端发起的音视频呼叫**，帮助您快速完成设备呼叫微信场景的小程序端接入。
+
+## 前提条件
+- 已完成 集成与登录 文档中的登录功能，小程序成功登录。
+
+- 已在物联网开发平台完成 TWeCall 服务激活与小程序授权。
+
+- 已完成小程序的硬件设备接入并获取 model_id：在小程序管理后台的**设置 > 基本设置 > 服务类目**中添加「工具 > 设备管理」类目，然后在**功能 > 硬件设备**中添加设备，审核通过后平台在设备管理列表分配 model_id。详细流程请参见 开通服务 的 小程序申请硬件能力 章节及微信官方 [硬件设备接入指引](https://developers.weixin.qq.com/miniprogram/dev/framework/device/device-access)。
+
+## 接入流程
+
+小程序端接入分为以下四步：
+1. 绑定设备到家庭：设备须先归属某个家庭，才能对该设备发起呼叫。
+
+2. 接入 wmpf-voip 插件：通话接听页由微信官方 wmpf-voip 插件承载。
+
+3. 注册 VoIP 通话权限：为指定设备完成微信侧授权，授权后设备才能呼叫当前用户。
+
+4. 查询与管理授权状态：查询设备已授权的用户，或注销设备的 VoIP 通话权限。
+
+## 接入步骤
+
+### 步骤 1：绑定设备到家庭
+
+用户使用 TWeCall 前，需要先把设备绑定到家庭中。绑定凭证为设备绑定签名（deviceBindSignature），由设备配网流程或设备机身二维码提供，详细绑定流程。
+``` javascript
+const plugin = requirePlugin('tx-iot-sdk');
+const engine = plugin.TXIoTEngine.getInstance();
+const familyManager = engine.getFamilyManager();
+const deviceManager = engine.getDeviceManager();
+
+// 1. 获取家庭列表；首次使用可先通过 createFamily 创建家庭
+const families = await familyManager.getFamilyList();
+const familyId = families[0]?.familyId;
+
+// 2. 使用设备绑定签名将设备绑定到家庭
+// deviceBindSignature 由设备配网流程或扫描设备机身二维码获取
+const deviceBindSignature = 'YOUR_DEVICE_BIND_SIGNATURE';
+const deviceInfo = await deviceManager.bindDevice(familyId, deviceBindSignature);
+```
+
+绑定成功后，设备会出现在 getDeviceList 的返回结果中。相关接口说明。
+
+### 步骤 2：接入 wmpf-voip 插件
+
+接听 UI 由微信官方 **wmpf-voip** 插件（AppID：wxf830863afde621eb）的通话页承载，宿主小程序需在 **app.json** 中声明插件：
+``` json
+{
+  "plugins": {
+    "wmpf-voip": {
+      "version": "latest",
+      "provider": "wxf830863afde621eb"
+    }
+  }
+}
+```
+
+在小程序启动时（如 App 的 `onLaunch` 中）对插件进行初始化：
+``` javascript
+const wmpfVoip = requirePlugin('wmpf-voip').default;
+
+// 接听页 UI 定制（按需配置）
+wmpfVoip.setUIConfig({
+  // ...
+});
+
+// 通话结束后跳转的宿主小程序页面路径
+wmpfVoip.setVoipEndPagePath({
+  url: '/pages/call-end/call-end',
+  key: 'Call',
+});
+
+// 监听通话事件
+wmpfVoip.onVoipEvent((event) => {
+  console.log(event.eventName, event);
+});
+```
+
+### 步骤 3：注册微信 VoIP 通话权限
+
+设备只能呼叫已完成微信 VoIP 授权的用户。注册流程分为三个子步骤，需依次完成。
+
+#### 3.1 获取授权票据
+
+调用 requestVoIPSnTicket 获取设备的 SN 与 snTicket（授权票据）：
+``` javascript
+const deviceManager = engine.getDeviceManager();
+
+// deviceId：设备标识，productId / deviceName 为物联网开发平台上的产品 ID 与设备名称
+const deviceId = { productId: 'YOUR_PRODUCT_ID', deviceName: 'YOUR_DEVICE_NAME' };
+// modelId：微信公众平台「设备接入」分配的 model_id
+const modelId = 'YOUR_MODEL_ID';
+// appId：当前宿主小程序的 AppID
+const appId = 'YOUR_MINIPROGRAM_APPID';
+
+const { sn, snTicket } = await deviceManager.requestVoIPSnTicket(deviceId, modelId, appId);
+```
+
+#### 3.2 拉起微信授权弹窗
+
+使用上一步获取的票据调用 `wx.requestDeviceVoIP`，拉起微信侧授权弹窗。该接口为微信原生 API，必须由宿主小程序在小程序上下文调用（插件上下文无此 API）：
+``` javascript
+wx.requestDeviceVoIP({
+  sn,
+  snTicket,  // 第 3.1 步获取，5 分钟内有效
+  modelId,
+  deviceName: "设备名称",  // 授权弹窗中显示的设备名，不超过 13 个字符
+  success(res) {
+    console.log('requestDeviceVoIP success:', res);
+    // 授权成功，继续执行第 3.3 步完成授权登记
+  },
+  fail(err) {
+    // errCode 10001 表示用户此前已授权，可视为成功
+    console.error('requestDeviceVoIP fail:', err);
+  },
+});
+```
+
+> **注意：**
+> - 用户拒绝过授权后，再次调用 `wx.requestDeviceVoIP` 不再弹窗，须引导用户到小程序设置页手动开启。
+> - 用户删除小程序后重新打开，授权状态会失效，需要重新执行本步骤。查询设备的授权状态参见步骤4中的 查询小程序已授权的设备。
+
+#### 3.3 添加到设备的联系人列表中
+
+微信侧授权成功后，调用 registerVoIPNotificationForDevice 将当前用户的微信 OpenID 添加到设备的联系人列表中，完成授权闭环：
+``` javascript
+// wxOpenId：当前用户的微信 OpenID
+const wxOpenId = 'USER_WX_OPENID';
+
+await deviceManager.registerVoIPNotificationForDevice(deviceId, modelId, appId, wxOpenId);
+```
+
+授权登记成功后，设备端即可发起呼叫，呼叫到达时微信会弹出「服务通知」提醒用户接听。
+
+### 步骤 4：查询与管理授权状态
+
+#### 查询设备联系人列表
+
+调用 getAuthorizedVoIPUserList 获取允许呼叫对应设备的微信用户 OpenID 列表，设备端 SDK 不允许呼叫联系人列表以外的用户：
+``` javascript
+const openIds = await deviceManager.getAuthorizedVoIPUserList(deviceId);
+const isInContactList = openIds.includes(wxOpenId);
+```
+
+#### 查询微信授权的设备列表
+
+调用 [wx.getDeviceVoIPList](https://developers.weixin.qq.com/miniprogram/dev/api/open-api/device-voip/wx.getDeviceVoIPList.html) 获取哪些设备允许通过微信 VoIP 呼叫当前用户。小程序被删除后再重新打开，已授权的设备会被清空。通过判断设备是否在本列表中，决定是否要重新执行步骤3。
+``` javascript
+const wxAny = wx as any;
+if (typeof wxAny.getDeviceVoIPList === 'function') {
+  wxAny.getDeviceVoIPList({
+    success: (res: { list?: any[] }) => {
+      // 判断 res.list 中是否包含目标设备的 sn (sn 由 productId + deviceName 组成)
+    },
+    fail: (err: { errMsg?: string }) => {
+      console.warn('[device] wx.getDeviceVoIPList fail:', err && err.errMsg);
+    },
+  });
+}
+```
+
+#### 从设备联系人列表中移除
+
+当用户不想再接收来自设备的呼叫时，调用 unregisterVoIPNotificationForDevice 将自己从设备联系人列表中移除，移除后设备再呼叫该用户时不会触发微信提醒：
+``` javascript
+await deviceManager.unregisterVoIPNotificationForDevice(deviceId, modelId, appId, wxOpenId);
+```
+
+## 常见问题
+
+### model_id 在哪里查看？
+
+在小程序管理后台的**功能 > 硬件设备 > 设备管理**列表中查看。设备需先通过微信审核（约1-3天），审核通过后平台才会分配 model_id。
+
+### 授权弹窗没有弹出？
+- 检查 snTicket 是否在5分钟有效期内，过期需重新调用 `requestVoIPSnTicket`。
+
+- 用户此前拒绝过授权的，微信不再自动弹窗，须引导用户到小程序设置页手动开启。
+
+- `fail` 回调中 errCode 为 10001 表示用户已授权，属于成功场景，可直接进入授权登记。
+
+### 设备呼叫后用户收不到提醒？
+- 确认用户已完成步骤3的授权登记，可通过 `getAuthorizedVoIPUserList` 校验。
+
+- 确认用户未删除过小程序；删除后重新打开授权状态会失效，需重新注册。
+
+## 相关文档
+- TXIoTDeviceManager：设备绑定、VoIP 授权等接口的完整说明。
+
+- 设备端接入：设备侧呼叫微信的对接流程。
+
+- 集成与登录：小程序 SDK 集成与登录。

package/resource/knowledge/iot/app/wechat-call/miniprogram-call-device.md

@@ -0,0 +1,193 @@
+---
+product: iot
+framework:
+  - minprogram
+types:
+  - feature
+retrievable_scope: always
+feature_domain: app
+---
+
+本文将介绍小程序端如何接入 TWeCall（微信通话），实现**向设备端发起音视频呼叫**，帮助您快速完成小程序呼叫设备场景的接入。
+
+TWeCall 是腾讯云物联网开发平台提供的设备与微信小程序之间的双向音视频通话能力。小程序端通过 TXIoTCallSession 发起呼叫，设备端接听后即可进行音视频通话。
+
+## 前提条件
+- 已完成 集成与登录 文档中的登录功能，小程序成功登录。
+
+- 已在物联网开发平台完成 TWeCall 服务激活与小程序授权。
+
+## 接入流程
+
+小程序向设备端发起呼叫分为以下三步：
+1. 绑定设备到家庭：设备须先归属某个家庭，才能对其发起通话。
+
+2. 添加渲染组件：在通话页面放置 `iot-pusher` 与 `iot-player` 组件。
+
+3. 发起通话：获取通话会话、监听通话事件、绑定渲染组件后呼叫设备。
+
+## 接入步骤
+
+### 步骤 1：绑定设备到家庭
+
+设备必须先绑定到家庭后才能发起通话。通过 bindDevice 使用设备绑定签名直接绑定，详细流程。
+``` javascript
+const plugin = requirePlugin('tx-iot-sdk');
+const engine = plugin.TXIoTEngine.getInstance();
+const familyManager = engine.getFamilyManager();
+const deviceManager = engine.getDeviceManager();
+
+// 1. 获取家庭列表；首次使用可先通过 createFamily 创建家庭
+const families = await familyManager.getFamilyList();
+const familyId = families[0]?.familyId;
+
+// 2. 使用设备绑定签名将设备绑定到家庭
+// deviceBindSignature 由设备配网流程或扫描设备机身二维码获取
+const deviceBindSignature = 'YOUR_DEVICE_BIND_SIGNATURE';
+const deviceInfo = await deviceManager.bindDevice(familyId, deviceBindSignature);
+```
+
+绑定成功后，设备会出现在 getDeviceList 的返回结果中。
+
+### 步骤 2：添加渲染组件
+
+通话页面需要放置两个渲染组件：`iot-pusher` 负责本端音视频的采集与推流，`openMicrophone`、`openCamera` 等接口采集的声音和画面通过该组件推送给设备端；`iot-player` 负责渲染设备端的音视频画面与声音。
+
+首先在页面 JSON 中声明组件：
+``` json
+{
+  "usingComponents": {
+    "iot-pusher": "plugin://tx-iot-sdk/iot-pusher",
+    "iot-player": "plugin://tx-iot-sdk/iot-player"
+  }
+}
+```
+
+然后在页面 wxml 中放置组件，并通过 `component-id` 指定组件 ID（后续 `setIoTPlayer` 绑定时需要用到）：
+``` xml
+<!-- 本端画面预览与推流 -->
+<iot-pusher />
+
+<!-- 远端画面与声音渲染 -->
+<iot-player component-id="remotePlayer" />
+```
+
+> **注意：**
+> 即使发起的是音频通话，也需要放置 `iot-player` 组件——通话中远端的声音通过该组件播放。
+>
+
+### 步骤 3：发起通话
+
+#### 3.1 获取通话会话
+
+登录成功后，通过 TXIoTEngine.getCallSession 获取通话会话对象：
+``` javascript
+const callSession = engine.getCallSession();
+```
+
+> **说明：**
+> 未登录或初始化未完成时 `getCallSession` 返回 null，请先确认登录成功后再调用。
+>
+
+#### 3.2 监听通话事件
+
+通过 addListener 注册事件回调，只需实现自己关心的回调方法，未实现的方法不会被调用：
+``` javascript
+callSession.addListener({
+  onCallBegin: (mediaType) => {
+    // 通话接通
+  },
+  onCallEnd: (mediaType, reason) => {
+    // 通话结束，reason 为结束原因
+  },
+  onCallRejected: (callUser) => {
+    // 对方拒接
+  },
+  onCallNoResponse: (callUser) => {
+    // 对方无应答
+  },
+  onCallLineBusy: (callUser) => {
+    // 对方占线
+  },
+  onCallUserOffline: (callUser) => {
+    // 对方离线
+  },
+  onCallUserVideoAvailable: (callUser, available) => {
+    // 远端视频可用；
+  },
+  onCallUserAudioAvailable: (callUser, available) => {
+    // 远端音频可用性变化
+  },
+  onError: (code, msg) => {
+    // 通话发生错误
+  },
+});
+```
+
+#### 3.3 绑定渲染组件
+
+通过 setIoTPlayer 将远端用户与 `iot-player` 组件绑定，SDK 会在该组件上渲染远端用户的音视频。`CallSession.setIoTPlayer` 第二个参数 iotPlayerComponentId 传入 wxml 中 `component-id` 指定的值：
+``` javascript
+const sdk = requirePlugin('tx-iot-sdk');
+
+// 构造对端用户；deviceId 为被叫设备的设备标识（含 productId / deviceName）
+const deviceId = { productId: 'YOUR_PRODUCT_ID', deviceName: 'YOUR_DEVICE_NAME' };
+const callUser = new sdk.TXIoTCallUser(deviceId);
+
+// 与 wxml 中的 <iot-player component-id="remotePlayer" /> 绑定
+callSession.setIoTPlayer(callUser, 'remotePlayer');
+callSession.startRemoteView(callUser);
+```
+
+#### 3.4 发起呼叫
+
+调用 callDevice 向设备发起通话，`callType` 指定通话类型：`AUDIO` 音频通话、`VIDEO` 视频通话（见 TXIoTCallMediaType）：
+``` javascript
+// 发起视频通话；音频通话传 sdk.TXIoTCallMediaType.AUDIO
+callSession.callDevice(deviceId, sdk.TXIoTCallMediaType.VIDEO);
+```
+
+呼叫结果通过 第3.2步 注册的回调通知：接通时收到 `onCallBegin`；对端拒接、无应答、占线、离线时分别收到 `onCallRejected`、`onCallNoResponse`、`onCallLineBusy`、`onCallUserOffline`。
+
+#### 3.5 开启本端媒体
+
+通话接通前后，都可以按需开启本端媒体：
+``` javascript
+// 开启本端麦克风
+callSession.openMicrophone();
+
+// 视频通话：开启本端摄像头（前置）
+callSession.openCamera(sdk.TXIoTCamera.FRONT);
+```
+
+#### 3.6 挂断通话
+
+调用 hangup 挂断当前通话。通话结束后收到 `onCallEnd` 回调，`reason` 为结束原因（本端挂断、对端挂断、网络错误等，见 TXIoTCallEndReason）：
+``` typescript
+callSession.hangup();
+```
+
+完整的通话接口说明（含 `switchCamera` 切换摄像头、`selectAudioPlaybackDevice` 切换扬声器/听筒等）。
+
+## 常见问题
+
+### 通话接通后听不到远端声音？
+
+确认页面已放置 `iot-player` 组件。音频通话场景下远端声音也通过该组件播放，组件缺失会导致无声。
+
+### getCallSession 返回 null？
+
+`getCallSession` 依赖 TXIoTEngine 创建与登录完成。请在登录成功的回调之后再获取通话会话对象，并确认 `tx-iot-sdk` 插件已正确集成。
+
+### 呼叫后立即收到对端离线回调？
+
+收到 `onCallUserOffline` 表示设备端不在线。请确认设备已激活 TWeCall 服务并成功登录上线，设备端接入流程。
+
+## 相关文档
+- 设备端接入：设备侧接入流程，含呼叫小程序与接听小程序呼叫。
+
+- 设备呼叫小程序：对端方向（设备呼叫微信）的小程序端接入。
+
+- TXIoTCallSession：通话接口的完整说明。
+
+- TXIoTDeviceManager：设备绑定等接口的完整说明。

package/resource/knowledge/iot/client-api/app/android/txiotcallsession.md

@@ -0,0 +1,189 @@
+---
+product: iot
+framework:
+  - android
+types:
+  - api
+retrievable_scope: always
+feature_domain: client_api
+---
+
+## 概述
+
+TXIoTCallSession 负责与设备之间的音视频通话，包括发起呼叫、挂断、远端画面渲染、麦克风/摄像头控制及音频输出设备选择。TXIoTCallSession 通过 TXIoTEngine.getCallSession 获取实例，需在登录成功后调用。
+
+> **说明：**
+> 回调模型：通话事件通过 `TXIoTCallListener` 接口回调，所有 Listener 回调在主线程触发，公共类型与错误码定义见 TXIoTEngineDef。
+>
+
+## 方法列表
+
+|方法签名|描述|
+|---------|---------|
+|addListener|添加通话事件监听器。|
+|removeListener|移除通话事件监听器。|
+|callDevice|向设备发起通话（音频/视频）。|
+|hangup|挂断当前通话。|
+|startRemoteView|开始渲染远端视频。|
+|stopRemoteView|停止渲染远端视频。|
+|openMicrophone|打开麦克风。|
+|closeMicrophone|关闭麦克风。|
+|openCamera|打开摄像头并设置本地预览视图。|
+|closeCamera|关闭摄像头。|
+|switchCamera|切换摄像头（前后置）。|
+|selectAudioPlaybackDevice|选择音频播放设备（扬声器/听筒）。|
+
+### addListener
+
+**添加通话事件监听器**
+
+|参数|描述|
+|---------|---------|
+|listener|`TXIoTCallListener`；监听器实例。|
+
+### removeListener
+
+**移除通话事件监听器**
+
+|参数|描述|
+|---------|---------|
+|listener|`TXIoTCallListener`；监听器实例。|
+
+### callDevice
+
+**向设备发起通话（音频/视频）**
+
+|参数|描述|
+|---------|---------|
+|deviceId|TXIoTDeviceId；设备标识（含 productId / deviceName）。|
+|callType|TXIoTCallMediaType；通话类型（音频/视频）。|
+
+### hangup
+
+**挂断当前进行中的通话**
+
+### startRemoteView
+
+**开始渲染远端视频**
+
+|参数|描述|
+|---------|---------|
+|callUser|TXIoTCallUser；参与通话的用户。|
+|videoView|`TXCloudVideoView`；视频渲染视图。|
+
+### stopRemoteView
+
+**停止渲染远端视频**
+
+|参数|描述|
+|---------|---------|
+|callUser|TXIoTCallUser；参与通话的用户。|
+
+### openMicrophone
+
+**打开麦克风**
+
+### closeMicrophone
+
+**关闭麦克风**
+
+### openCamera
+
+**打开摄像头并设置本地预览视图**
+
+|参数|描述|
+|---------|---------|
+|camera|TXIoTCamera；摄像头（前置/后置）。|
+|videoView|`TXCloudVideoView`；视频渲染视图。|
+
+### closeCamera
+
+**关闭摄像头**
+
+### switchCamera
+
+**切换摄像头（前后置）**
+
+|参数|描述|
+|---------|---------|
+|camera|TXIoTCamera；摄像头（前置/后置）。|
+
+### selectAudioPlaybackDevice
+
+**选择音频播放设备（扬声器/听筒）**
+
+|参数|描述|
+|---------|---------|
+|device|TXIoTAudioPlaybackDevice；音频播放设备（扬声器/听筒）。|
+
+## 通话事件回调
+
+|回调方法|说明|
+|---------|---------|
+|`onError(TXIoTErrorCode code, String msg)`|通话发生错误。|
+|`onCallBegin(TXIoTCallMediaType mediaType)`|通话开始。|
+|`onCallEnd(TXIoTCallMediaType mediaType, TXIoTCallEndReason reason)`|通话结束，携带结束原因。|
+|`onCallRejected(TXIoTCallUser callUser)`|通话被对方拒接。|
+|`onCallNoResponse(TXIoTCallUser callUser)`|对方无应答。|
+|`onCallLineBusy(TXIoTCallUser callUser)`|对方占线。|
+|`onCallUserOffline(TXIoTCallUser callUser)`|对方离线。|
+|`onCallUserAudioAvailable(TXIoTCallUser callUser, boolean available)`|远端用户音频状态发生变化。|
+|`onCallUserVideoAvailable(TXIoTCallUser callUser, boolean available)`|远端用户视频状态发生变化。|
+|`onCallNetworkQualityChanged(TXIoTQuality localQuality, List<TXIoTQuality> remoteQualityList)`|网络质量变化通知。|
+
+## 通话相关数据结构与枚举
+
+### TXIoTCallMediaType
+
+|枚举|说明|
+|---------|---------|
+|AUDIO|音频通话。|
+|VIDEO|视频通话。|
+
+### TXIoTCallEndReason
+
+|枚举|说明|
+|---------|---------|
+|UNKNOWN|未知原因。|
+|LOCAL_HANGUP|本地挂断。|
+|REMOTE_HANGUP|远端挂断。|
+|CALL_PERMISSION_DENIED|呼叫权限被拒绝。|
+|NETWORK_ERROR|网络错误。|
+
+### TXIoTAudioPlaybackDevice
+
+|枚举|说明|
+|---------|---------|
+|SPEAKER_PHONE|扬声器（外放）。|
+|EAR_PIECE|听筒。|
+
+### TXIoTCamera
+
+|枚举|说明|
+|---------|---------|
+|FRONT|前置摄像头。|
+|BACK|后置摄像头。|
+
+### TXIoTNetworkQuality
+
+|枚举|说明|
+|---------|---------|
+|EXCELLENT|极佳|
+|GOOD|良好|
+|POOR|较差|
+|BAD|差|
+|VERY_BAD|很差|
+|DOWN|网络不可用|
+
+### TXIoTCallUser
+
+|字段|说明|
+|---------|---------|
+|deviceId|参与通话的设备 ID。|
+
+### TXIoTQuality
+
+|字段|说明|
+|---------|---------|
+|callUser|网络质量对应的通话用户。|
+|quality|网络质量等级。|

package/resource/knowledge/iot/client-api/app/android/txiotcloudstorage.md

@@ -0,0 +1,77 @@
+---
+product: iot
+framework:
+  - android
+types:
+  - api
+retrievable_scope: always
+feature_domain: client_api
+---
+
+## 概述
+
+`TXIoTCloudStorage` 是云存功能模块，通过 `TXIoTEngine.getCloudStorage(TXIoTDeviceId)` 获取，提供设备云端录像的日期列表与事件列表查询能力。
+
+> **说明：**
+> 线程模型：SDK 接口可在任意线程调用；回调均在主线程（UI 线程）触发，调用方可在回调中直接操作 UI。
+>
+
+## 方法列表
+
+|方法签名|描述|
+|---------|---------|
+|`getDayList`|查询指定通道有云端录像的日期列表。|
+|`getEventList`|分页查询指定日期的云存事件列表。|
+
+### getDayList
+
+**查询有云端录像的日期列表**
+
+|参数|描述|
+|---------|---------|
+|channelId|通道 ID，从 0 开始计数；单通道设备填 0。|
+|timeZone|按天统计录像所用的时区；传 `null` 时使用系统默认时区。|
+|callback|结果回调。`onSuccess` 返回有云端录像的日期字符串列表，格式为`yyyy-MM-dd`（如`2026-08-20`）；`onError` 返回错误码与错误描述。|
+
+### getEventList
+
+**分页查询指定日期的云存事件列表**
+
+|参数|描述|
+|---------|---------|
+|channelId|通道 ID，从 0 开始计数；单通道设备填 0。|
+|timeZone|按天统计事件所用的时区；传 `null` 时使用系统默认时区。|
+|date|要查询的日期，格式为`yyyy-MM-dd`（如`2026-08-20`），通常取自 `getDayList` 的返回结果。|
+|nextPageToken|分页标记。首次查询传空字符串 `""`；翻页时传入上一次回调返回的 `TXIoTPageResult.nextPageToken`。|
+|callback|结果回调。`onSuccess` 返回分页结果，`dataList` 为本页事件列表，`nextPageToken` 为空字符串表示没有更多数据；`onError` 返回错误码与错误描述。|
+
+> **注意：**
+> `date` 不能为空字符串，否则回调 `onError` 并返回参数错误。
+>
+
+## 云存相关数据结构
+
+### TXIoTEvent
+
+**云存事件，包含事件类型、缩略图、发生时间及关联录像文件**
+
+|字段|说明|
+|---------|---------|
+|eventType|事件类型标识，可能为空字符串，调用方可按需过滤。|
+|thumbnailUrl|事件缩略图 URL。|
+|eventTimeMs|事件发生时间，Unix 毫秒级时间戳。|
+|durationMs|事件时长，单位毫秒。|
+|videoFiles|事件关联的录像文件列表，元素类型为 `TXIoTVideoFile`。|
+
+### TXIoTVideoFile
+
+**云存录像文件，包含播放地址与云点播（VOD）播放信息**
+
+|字段|说明|
+|---------|---------|
+|videoUrl|录像文件播放地址。|
+|vodAppId|云点播应用 ID，用于通过 VOD 播放器播放。|
+|vodFileId|云点播文件 ID，用于通过 VOD 播放器播放。|
+|vodPlaySign|云点播播放签名。|
+|startTimeMs|录像片段起始时间，Unix 毫秒级时间戳。|
+|durationMs|录像片段时长，单位毫秒。|