# 小程序端与 Web 端 API 差异说明

## 重要提示 ⚠️

小程序端的 TUICallKit API 与 Web 端有显著差异，不能直接使用 Web 端的事件监听方式。

## 核心差异

### 1. 事件监听方式

#### ❌ Web 端方式（小程序端不支持）
```javascript
// Web 端可以这样使用
TUICallKitServer.setCallback({
  statusChanged: handleStatusChange,
  afterCalling: handleAfterCalling
});

// 或者
TUICallKitAPI.on('onCallReceived', (data) => {
  console.log('收到来电', data);
});
```

#### ✅ 小程序端正确方式
```javascript
// 小程序端不需要手动监听事件
// TUICallKit 组件会自动处理来电显示

// 只需要：
// 1. 初始化 TUICallKit
await TUICallKitAPI.init({
  sdkAppID: Number(sdkAppId),
  userID: userId,
  userSig: userSig,
});

// 2. 挂载 TUICallKit 组件
<TUICallKit v-if="isLogin"></TUICallKit>

// 组件会自动：
// - 监听来电
// - 显示来电界面
// - 处理接听/拒绝
// - 显示通话界面
```

### 2. 状态管理

#### Web 端
使用回调函数处理状态变化：
```javascript
const handleStatusChange = ({ oldStatus, newStatus }) => {
  if (newStatus === STATUS.CALLING_C2C_VIDEO) {
    console.log('通话已接通');
  }
};
```

#### 小程序端
使用 TUIStore 监听状态（如果需要）：
```javascript
import { TUIStore, StoreName, NAME } from '../src/index';

// 监听通话状态
TUIStore.watch(StoreName.CALL, {
  [NAME.CALL_STATUS]: (newValue) => {
    console.log('通话状态变化:', newValue);
  }
});
```

### 3. 发起通话

#### Web 端
```javascript
await TUICallKitServer.call({
  userID: 'patient_2',
  type: TUICallType.VIDEO_CALL
});
```

#### 小程序端
```javascript
await TUICallKitAPI.calls({
  userIDList: ['doctor_1'],
  type: 2,  // 2 表示视频通话
});
```

注意差异：
- Web 端：`call()` 方法，单数
- 小程序端：`calls()` 方法，复数
- Web 端：`userID` 参数，单个用户
- 小程序端：`userIDList` 参数，用户数组

## 小程序端正确的使用流程

### 步骤 1：初始化

```javascript
const loginHandler = async () => {
  // 1. 获取签名
  const signatureData = await getSignatureFromServer(patientId.value);
  const { sdkAppId, userId, userSig } = signatureData;
  
  // 2. 初始化 TUICallKit
  await TUICallKitAPI.init({
    sdkAppID: Number(sdkAppId),
    userID: userId,
    userSig: userSig,
  });
  
  console.log('TUICallKit 初始化成功');
  
  // 3. 设置登录状态（触发组件挂载）
  isLogin.value = true;
  
  // 完成！不需要手动设置事件监听
};
```

### 步骤 2：挂载组件

```vue
<template>
  <view>
    <!-- 登录后才挂载组件 -->
    <TUICallKit v-if="isLogin"></TUICallKit>
    
    <!-- 登录界面 -->
    <view class="loginBox">
      <!-- ... -->
    </view>
  </view>
</template>
```

### 步骤 3：自动处理来电

当有来电时，TUICallKit 组件会自动：
1. 检测到来电信号
2. 显示来电界面
3. 播放铃声
4. 显示接听/拒绝按钮
5. 处理用户操作

**你不需要做任何额外的事情！**

### 步骤 4：发起通话（可选）

```javascript
const callHandler = async () => {
  let targetUserId = patientId.value;
  
  // 如果是纯数字，添加前缀
  if (/^\d+$/.test(patientId.value)) {
    targetUserId = `doctor_${patientId.value}`;
  }
  
  // 发起通话
  await TUICallKitAPI.calls({
    userIDList: [targetUserId],
    type: 2,  // 2 = 视频通话
  });
};
```

## 常见错误

### 错误 1：使用 .on() 方法

```javascript
// ❌ 错误：小程序端不支持
TUICallKitAPI.on('onCallReceived', (data) => {
  console.log('收到来电', data);
});

// 错误信息：
// TUICallKitAPI.on is not a function
```

**解决：** 删除所有 `.on()` 调用，让组件自动处理。

### 错误 2：使用 setCallback

```javascript
// ❌ 错误：小程序端不支持
TUICallKitAPI.setCallback({
  statusChanged: handleStatusChange
});

// 错误信息：
// TUICallKitAPI.setCallback is not a function
```

**解决：** 删除 `setCallback` 调用，使用 TUIStore 监听（如果需要）。

### 错误 3：使用 call() 而不是 calls()

```javascript
// ❌ 错误：小程序端使用 calls()
await TUICallKitAPI.call({
  userID: 'doctor_1',
  type: 2
});

// 错误信息：
// TUICallKitAPI.call is not a function
```

**解决：** 使用 `calls()` 方法，参数为 `userIDList` 数组。

## 如何监听状态（高级用法）

如果你确实需要监听通话状态，使用 TUIStore：

```javascript
import { TUIStore, StoreName, NAME, CallStatus } from '../src/index';

// 在 setup 中
onMounted(() => {
  // 监听通话状态
  TUIStore.watch(StoreName.CALL, {
    [NAME.CALL_STATUS]: (newStatus) => {
      console.log('通话状态变化:', newStatus);
      
      switch (newStatus) {
        case CallStatus.IDLE:
          console.log('空闲状态');
          break;
        case CallStatus.WAITING:
          console.log('等待接听');
          break;
        case CallStatus.CONNECTED:
          console.log('通话中');
          break;
      }
    },
    
    [NAME.IS_GROUP]: (isGroup) => {
      console.log('是否群组通话:', isGroup);
    },
    
    [NAME.CALL_ROLE]: (role) => {
      console.log('通话角色:', role);
    }
  });
});

// 在 onUnmounted 中取消监听
onUnmounted(() => {
  TUIStore.unwatch(StoreName.CALL, {
    [NAME.CALL_STATUS]: () => {},
    [NAME.IS_GROUP]: () => {},
    [NAME.CALL_ROLE]: () => {}
  });
});
```

## 可用的 TUIStore 监听项

```javascript
// 通话状态
NAME.CALL_STATUS        // 通话状态（IDLE, WAITING, CONNECTED）
NAME.CALL_ROLE          // 通话角色（CALLER, CALLEE）
NAME.CALL_MEDIA_TYPE    // 通话类型（VIDEO, AUDIO）
NAME.IS_GROUP           // 是否群组通话

// 用户信息
NAME.LOCAL_USER_INFO    // 本地用户信息
NAME.REMOTE_USER_INFO_LIST  // 远程用户列表

// 设备状态
NAME.IS_MUTED           // 是否静音
NAME.IS_CAMERA_ON       // 摄像头是否开启
NAME.IS_EAR_PHONE       // 是否使用听筒

// 其他
NAME.CALL_DURATION      // 通话时长
NAME.CALLER_USER_INFO   // 主叫用户信息
```

## 完整示例

```vue
<template>
  <view>
    <TUICallKit v-if="isLogin"></TUICallKit>
    <view class="loginBox">
      <input v-model="patientId" placeholder="请输入患者ID" />
      <button @click="loginHandler">登录</button>
      <button v-if="isLogin" @click="callHandler">呼叫</button>
    </view>
  </view>
</template>

<script setup>
import { ref, onMounted, onUnmounted } from "vue";
import { TUICallKitAPI, TUIStore, StoreName, NAME, CallStatus } from "../src/index";
import TUICallKit from "../src/Components/TUICallKit";

const patientId = ref("2");
const isLogin = ref(false);

// 登录
const loginHandler = async () => {
  try {
    // 获取签名
    const signatureData = await getSignatureFromServer(patientId.value);
    const { sdkAppId, userId, userSig } = signatureData;
    
    // 初始化
    await TUICallKitAPI.init({
      sdkAppID: Number(sdkAppId),
      userID: userId,
      userSig: userSig,
    });
    
    console.log('初始化成功');
    isLogin.value = true;
    
  } catch (error) {
    console.error('登录失败:', error);
  }
};

// 发起通话
const callHandler = async () => {
  try {
    await TUICallKitAPI.calls({
      userIDList: ['doctor_1'],
      type: 2,
    });
  } catch (error) {
    console.error('发起通话失败:', error);
  }
};

// 监听状态（可选）
onMounted(() => {
  TUIStore.watch(StoreName.CALL, {
    [NAME.CALL_STATUS]: (newStatus) => {
      console.log('通话状态:', newStatus);
    }
  });
});

onUnmounted(() => {
  TUIStore.unwatch(StoreName.CALL, {
    [NAME.CALL_STATUS]: () => {}
  });
});
</script>
```

## 总结

### ✅ 小程序端应该做的

1. 初始化 TUICallKit
2. 挂载 TUICallKit 组件
3. 让组件自动处理来电

### ❌ 小程序端不应该做的

1. 使用 `.on()` 方法监听事件
2. 使用 `setCallback()` 设置回调
3. 使用 `call()` 而不是 `calls()`
4. 手动显示来电界面

### 🎯 关键点

- **TUICallKit 组件会自动处理一切**
- **你只需要初始化和挂载组件**
- **如果需要监听状态，使用 TUIStore**
- **不要尝试使用 Web 端的 API**

---

**最后更新：** 2024-03-04
**版本：** 1.0