zyt/admin/TROUBLESHOOTING.md

# 音视频通话功能 - 故障排查指南

## 常见错误及解决方案

### 1. 导入错误：does not provide an export named 'default'

**错误信息**:
```
SyntaxError: The requested module '/admin/node_modules/.vite/deps/@tencentcloud_call-uikit-vue.js?v=xxx' does not provide an export named 'default'
```

**原因**: TUICallKit 不支持默认导入，需要使用命名导入。

**解决方案**:
```typescript
// ❌ 错误的导入方式
import TUICallKit from '@tencentcloud/call-uikit-vue'

// ✅ 正确的导入方式
import { TUICallKit, TUICallKitServer, TUICallType } from '@tencentcloud/call-uikit-vue'
```

---

### 2. 类型错误：Property 'init' does not exist

**错误信息**:
```
Property 'init' does not exist on type 'typeof import(...)'
```

**原因**: TUICallKit 是一个组件，不是通过 `init` 方法初始化的。

**解决方案**:
```typescript
// ❌ 错误的使用方式
const tuiCallKit = TUICallKit.init({ ... })

// ✅ 正确的使用方式
// 1. 在模板中使用组件
<TUICallKit class="tui-call-kit" />

// 2. 使用 TUICallKitServer 进行初始化和调用
await TUICallKitServer.init({
  userID: 'user_123',
  userSig: 'xxx',
  SDKAppID: 1400000000
})

await TUICallKitServer.call({
  userID: 'target_user',
  type: TUICallType.VIDEO_CALL
})
```

---

### 3. 获取签名失败

**错误信息**:
```
获取签名失败
```

**可能原因**:
1. 后端配置错误
2. SDKAppID 或 SecretKey 不正确
3. 网络请求失败

**排查步骤**:

1. 检查后端配置
```bash
# 查看 .env 文件
cat server/.env | grep TRTC

# 应该看到：
# TRTC_SDK_APP_ID=1400000000
# TRTC_SECRET_KEY=your_secret_key
# TRTC_ENABLE=true
```

2. 测试 API 接口
```bash
curl -X POST http://localhost/adminapi/tcm.diagnosis/getCallSignature \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"diagnosis_id": 1, "patient_id": 10001}'
```

3. 查看后端日志
```bash
tail -f server/runtime/log/error.log
```

---

### 4. 摄像头/麦克风权限被拒绝

**错误信息**:
```
NotAllowedError: Permission denied
```

**解决方案**:

1. 检查浏览器权限设置
   - Chrome: 地址栏左侧 → 网站设置 → 摄像头/麦克风
   - Edge: 同 Chrome
   - Safari: Safari → 偏好设置 → 网站 → 摄像头/麦克风

2. 确保使用 HTTPS 或 localhost
   ```
   ✅ https://your-domain.com
   ✅ http://localhost:5173
   ❌ http://192.168.1.100:5173
   ```

3. 重新授权
   - 刷新页面
   - 清除浏览器缓存
   - 重新点击"允许"

---

### 5. 通话无画面

**可能原因**:
1. 摄像头被其他应用占用
2. 摄像头驱动问题
3. 网络连接问题

**排查步骤**:

1. 测试摄像头
```javascript
// 在浏览器控制台执行
navigator.mediaDevices.getUserMedia({ video: true, audio: true })
  .then(stream => {
    console.log('摄像头正常', stream)
    stream.getTracks().forEach(track => track.stop())
  })
  .catch(err => console.error('摄像头错误', err))
```

2. 检查网络连接
   - 打开浏览器开发者工具 → Network
   - 查看是否有请求失败
   - 检查 WebSocket 连接状态

3. 查看控制台错误
   - F12 打开开发者工具
   - 查看 Console 标签页
   - 查找红色错误信息

---

### 6. 对方无法接听

**可能原因**:
1. 对方未登录系统
2. 对方的 userId 不正确
3. 对方未集成 TUICallKit

**解决方案**:

1. 确认对方 userId
```typescript
// 确保 userId 格式正确
const userId = `patient_${patientId}` // 例如: patient_10001
```

2. 检查对方是否在线
   - 对方需要登录系统
   - 对方需要初始化 TUICallKit
   - 对方需要监听来电事件

3. 测试环境
   - 可以在两个浏览器窗口测试
   - 使用不同的 userId 登录

---

### 7. 通话中断/掉线

**可能原因**:
1. 网络不稳定
2. 防火墙阻止
3. 服务器问题

**解决方案**:

1. 检查网络质量
   - 使用有线网络
   - 关闭其他占用带宽的应用
   - 测试网络延迟

2. 配置防火墙
   - 允许 UDP 端口
   - 允许 WebRTC 连接
   - 检查企业防火墙设置

3. 查看 TRTC 控制台
   - 登录腾讯云控制台
   - 查看实时监控
   - 检查用量和质量

---

### 8. 初始化未完成错误

**错误信息**:
```
API<getDeviceList>: init or login is not complete, this API needs to be used after init.
TUICallEngine 初始化登录未完成，需要在 init 或 login 完成后使用此 API
<ERROR_INIT_FAIL: -1201>
```

**原因**: TUICallKit 组件在初始化完成之前就被渲染了。

**解决方案**:

已在代码中修复，确保：

1. 初始化完成后再显示组件
```typescript
// 初始化
await TUICallKitServer.init({ ... })

// 等待初始化完全完成
await new Promise(resolve => setTimeout(resolve, 500))

// 设置标志，显示组件
isInitialized.value = true

// 等待组件渲染
await new Promise(resolve => setTimeout(resolve, 300))

// 发起通话
await TUICallKitServer.call({ ... })
```

2. 使用条件渲染
```vue
<!-- 只在初始化完成后显示组件 -->
<TUICallKit v-if="isInitialized" class="tui-call-kit" />
```

3. 添加状态提示
```vue
<div v-if="!isInitialized" class="call-waiting">
  <p>{{ statusText }}</p>
  <!-- 显示：正在获取签名... → 正在初始化... → 初始化完成 -->
</div>
```

**验证修复**:
1. 点击"视频通话"按钮
2. 观察状态提示的变化
3. 等待初始化完成
4. 应该不再出现 ERROR_INIT_FAIL 错误

---

### 9. 编译错误

**错误信息**:
```
Module not found: Can't resolve '@tencentcloud/call-uikit-vue'
```

**解决方案**:

1. 安装依赖
```bash
cd admin
npm install @tencentcloud/call-uikit-vue
```

2. 清除缓存
```bash
rm -rf node_modules/.vite
npm run dev
```

3. 检查 package.json
```json
{
  "dependencies": {
    "@tencentcloud/call-uikit-vue": "^2.3.2"
  }
}
```

---

### 9. 样式问题

**问题**: TUICallKit 组件样式不正常

**解决方案**:

1. 导入样式文件
```typescript
// 在 main.ts 中添加
import '@tencentcloud/call-uikit-vue/dist/style.css'
```

2. 设置容器尺寸
```vue
<TUICallKit style="width: 650px; height: 500px;" />
```

3. 检查 CSS 冲突
   - 使用浏览器开发者工具检查元素
   - 查看是否有样式被覆盖
   - 调整 z-index

---

### 10. 性能问题

**问题**: 通话卡顿、延迟高

**解决方案**:

1. 优化视频参数
```typescript
await TUICallKitServer.call({
  userID: 'target_user',
  type: TUICallType.VIDEO_CALL,
  // 可以添加更多配置
})
```

2. 降低视频质量
   - 使用语音通话替代视频通话
   - 降低视频分辨率
   - 降低帧率

3. 优化网络
   - 使用有线网络
   - 关闭其他应用
   - 选择就近的服务器

---

## 调试技巧

### 1. 启用详细日志

```typescript
// 在初始化前设置
TUICallKitServer.setLogLevel(0) // 0-详细 1-普通 2-警告 3-错误
```

### 2. 监听所有事件

```typescript
// 监听通话开始
TUICallKitServer.on('onCallBegin', () => {
  console.log('通话开始')
})

// 监听通话结束
TUICallKitServer.on('onCallEnd', () => {
  console.log('通话结束')
})

// 监听错误
TUICallKitServer.on('onError', (error) => {
  console.error('通话错误', error)
})
```

### 3. 使用浏览器开发者工具

1. 打开开发者工具 (F12)
2. 查看 Console 标签页
3. 查看 Network 标签页
4. 查看 Application → Local Storage

### 4. 查看后端日志

```bash
# 实时查看错误日志
tail -f server/runtime/log/error.log

# 查看最近的日志
tail -n 100 server/runtime/log/error.log
```

---

## 联系支持

如果以上方法都无法解决问题，请提供以下信息：

1. 错误截图或日志
2. 浏览器版本和操作系统
3. 操作步骤
4. 配置信息（脱敏后）
5. 网络环境

联系方式：
- 技术支持邮箱: support@example.com
- 腾讯云工单: https://console.cloud.tencent.com/workorder

---

## 参考资料

- [TUICallKit 官方文档](https://cloud.tencent.com/document/product/647/78742)
- [TRTC 常见问题](https://cloud.tencent.com/document/product/647/43018)
- [WebRTC 调试指南](https://webrtc.org/getting-started/testing)