新增功能

2026-03-04 15:32:30 +08:00
parent a07e844c47
commit ab77f5488d
2266 changed files with 177942 additions and 3444 deletions
@@ -0,0 +1,520 @@
+# 修改清单 - 小程序端无法接听来电修复
+
+## 修改的文件
+
+### 1. wx/TUICallKit/pages/call.vue ✅
+
+**修改内容：**
+
+#### 修改 1：条件渲染 TUICallKit 组件
+```vue
+<!-- 第 3 行 -->
+<TUICallKit v-if="isLogin"></TUICallKit>
+```
+
+#### 修改 2：更新输入框提示
+```vue
+<!-- 第 6-9 行 -->
+<input
+  class="input-box"
+  v-model="patientId"
+  :placeholder="!isLogin ? '请输入患者ID（数字）' : '输入医生ID或完整userId（如：doctor_1）'"
+  placeholder-style="color:#BBBBBB;"
+/>
+```
+
+#### 修改 3：增强状态显示
+```vue
+<!-- 第 20-23 行 -->
+<view v-if="isLogin" class="status-info">
+  <text>当前登录: {{ currentUserId }}</text>
+  <text class="tip">提示：呼叫医生请输入医生ID（如：1）或完整ID（如：doctor_1）</text>
+</view>
+```
+
+#### 修改 4：增强登录日志
+```javascript
+// 第 84-87 行
+console.log('=== 小程序端登录信息 ===');
+console.log('sdkAppId:', sdkAppId);
+console.log('userId:', userId);
+console.log('userSig 长度:', userSig?.length);
+```
+
+#### 修改 5：移除不支持的事件监听代码
+```javascript
+// 第 100-107 行
+console.log('TUICallKit 初始化成功, userId:', userId);
+
+// 等待一下确保初始化完成
+await new Promise(resolve => setTimeout(resolve, 1000));
+
+// 小程序端使用 TUIStore 监听状态变化，而不是 .on() 方法
+// TUICallKit 组件会自动处理来电显示
+console.log('=== TUICallKit 初始化完成，等待来电 ===');
+
+isLogin.value = true;
+```
+
+**重要说明：**
+- 小程序端不支持 `.on()` 方法
+- TUICallKit 组件会自动处理来电
+- 不需要手动设置事件监听
+
+#### 修改 6：增强 userId 格式处理
+```javascript
+// 第 158-167 行
+// 构建目标用户ID - 确保格式一致
+let targetUserId = patientId.value;
+if (/^\d+$/.test(patientId.value)) {
+  // 纯数字，添加 doctor_ 前缀（患者呼叫医生）
+  targetUserId = `doctor_${patientId.value}`;
+}
+
+console.log('准备呼叫用户:', targetUserId);
+```
+
+#### 修改 7：增强样式
+```css
+/* 第 213-227 行 */
+.status-info {
+  margin-top: 20px;
+  padding: 10px;
+  background-color: #f0f0f0;
+  border-radius: 5px;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 8px;
+}
+
+.status-info .tip {
+  font-size: 12px;
+  color: #999;
+  text-align: center;
+  line-height: 1.5;
+}
+```
+
+## 新增的文档
+
+### 1. wx/TUICallKit/CANNOT_RECEIVE_CALL_FIX.md ✅
+详细的问题诊断与修复指南，包含：
+- 根本原因分析
+- 已实施的修复
+- 测试步骤
+- 常见错误及解决方案
+- 调试技巧
+- 后端日志检查
+
+### 2. wx/TUICallKit/CALL_DEBUG_GUIDE.md ✅
+调试指南，包含：
+- 常见原因及解决方案
+- 调试步骤
+- 测试方案
+- 后端接口检查
+- 常用调试命令
+- 问题排查清单
+
+### 3. wx/TUICallKit/QUICK_FIX.md ✅
+快速修复指南，包含：
+- 核心问题说明
+- 立即检查步骤
+- 快速修复步骤
+- 常见错误及解决
+- 验证清单
+- 测试命令
+
+### 4. wx/TUICallKit/TEST_GUIDE.md ✅
+完整的测试指南，包含：
+- 测试前准备
+- 5 个测试场景
+- 常见问题排查
+- 测试检查清单
+- 测试报告模板
+
+### 5. wx/TUICallKit/FIX_SUMMARY.md ✅
+修复总结，包含：
+- 问题描述
+- 根本原因
+- 已实施的修复
+- 测试验证
+- 相关文档
+- 注意事项
+- 常见问题
+
+### 6. wx/TUICallKit/START_HERE.md ✅
+快速开始指南，包含：
+- 快速开始步骤
+- 问题排查
+- 文档导航
+- 关键日志
+- 配置检查
+- 测试场景
+
+### 7. wx/TUICallKit/MINIAPP_API_DIFFERENCE.md ✅
+小程序端与 Web 端 API 差异说明，包含：
+- 核心差异说明
+- 事件监听方式对比
+- 正确的使用流程
+- 常见错误及解决
+- 完整示例代码
+
+### 8. CHANGES.md ✅
+问题排查清单，包含：
+- 8 个检查步骤
+- 常见错误代码
+- 后端接口检查
+- 网络抓包分析
+- 问题解决方案汇总
+- 成功标志
+
+### 8. CHANGES.md ✅
+本文件，记录所有修改内容
+
+## 修改统计
+
+- **修改文件数：** 1
+- **新增文档数：** 8
+- **代码修改行数：** 约 50 行
+- **新增文档行数：** 约 2000 行
+
+## 核心修改点
+
+### 1. 组件挂载时机 ⭐⭐⭐
+**问题：** TUICallKit 组件在登录前就已挂载
+**修复：** 改为登录后才挂载（`v-if="isLogin"`）
+**影响：** 确保组件在正确的时机初始化
+
+### 2. 事件监听设置 ⭐⭐⭐
+**问题：** 初始化后没有设置来电事件监听
+**修复：** 添加完整的事件监听代码
+**影响：** 能够正确接收和处理来电
+
+### 3. 初始化等待 ⭐⭐
+**问题：** 初始化后立即设置监听可能失效
+**修复：** 添加 1 秒等待时间
+**影响：** 确保初始化完全完成
+
+### 4. userId 格式处理 ⭐⭐
+**问题：** 输入纯数字时格式不匹配
+**修复：** 自动添加前缀（`doctor_`）
+**影响：** 减少用户输入错误
+
+### 5. 日志增强 ⭐
+**问题：** 缺少关键日志，难以调试
+**修复：** 添加详细的日志输出
+**影响：** 便于问题排查
+
+## 测试建议
+
+### 必须测试的场景
+
+1. **Web → 小程序**（最重要）
+   - 小程序端登录
+   - Web 端发起呼叫
+   - 小程序端接听
+   - 正常通话
+   - 挂断
+
+2. **小程序 → Web**
+   - 小程序端登录
+   - 小程序端发起呼叫
+   - Web 端接听
+   - 正常通话
+   - 挂断
+
+3. **拒绝通话**
+   - 发起呼叫
+   - 接收方拒绝
+   - 确认正常结束
+
+4. **超时未接听**
+   - 发起呼叫
+   - 等待 30 秒
+   - 确认自动挂断
+
+### 测试检查点
+
+- [ ] 小程序能正常登录
+- [ ] 控制台显示"事件监听已设置"
+- [ ] 能收到来电通知
+- [ ] 能正常接听
+- [ ] 视频和音频都正常
+- [ ] 能正常挂断
+- [ ] 能正常拒绝
+- [ ] 超时能正常处理
+
+## 回滚方案
+
+如果修改后出现问题，可以回滚到原始版本：
+
+### 回滚步骤
+
+1. 使用 Git 回滚：
+```bash
+git checkout HEAD -- wx/TUICallKit/pages/call.vue
+```
+
+2. 或者手动恢复：
+   - 移除 `v-if="isLogin"`
+   - 移除事件监听代码
+   - 移除初始化等待代码
+
+### 原始代码关键部分
+
+```vue
+<!-- 原始的组件挂载 -->
+<TUICallKit></TUICallKit>
+
+<!-- 原始的初始化代码 -->
+await TUICallKitAPI.init({
+  sdkAppID: Number(sdkAppId),
+  userID: userId,
+  userSig: userSig,
+});
+
+console.log('TUICallKit 初始化成功, userId:', userId);
+
+isLogin.value = true;
+```
+
+## 注意事项
+
+### ⚠️ 重要提示
+
+1. **清除缓存**
+   - 修改后必须清除缓存
+   - 开发者工具和真机都要清除
+
+2. **userId 格式**
+   - 必须确保 Web 端和小程序端格式一致
+   - 推荐使用 `prefix_number` 格式
+
+3. **SDKAppID**
+   - 必须确保双方使用同一个
+   - 检查后端配置
+
+4. **权限授予**
+   - 摄像头权限
+   - 麦克风权限
+   - 网络权限
+
+5. **小程序状态**
+   - 必须在前台运行
+   - 切换到后台可能无法接收来电
+
+## 后续优化
+
+### 可以考虑的改进
+
+1. **添加心跳检测**
+   - 定期检查连接状态
+   - 确保在线状态准确
+
+2. **添加重连机制**
+   - 网络中断后自动重连
+   - 提高稳定性
+
+3. **优化错误提示**
+   - 根据错误码给出具体提示
+   - 提供解决建议
+
+4. **添加通话质量监控**
+   - 实时监控通话质量
+   - 自动调整参数
+
+5. **添加通话记录**
+   - 记录通话历史
+   - 便于查询和统计
+
+## 文档使用指南
+
+### 按问题类型查找
+
+- **无法登录** → `START_HERE.md` → 问题排查 → 问题 1
+- **无法接听** → `CANNOT_RECEIVE_CALL_FIX.md` → 测试步骤
+- **对方不在线** → `QUICK_FIX.md` → 快速修复步骤
+- **完整测试** → `TEST_GUIDE.md` → 测试场景
+- **详细排查** → `CALL_TROUBLESHOOTING_CHECKLIST.md` → 检查清单
+
+### 按角色查找
+
+- **开发人员** → `FIX_SUMMARY.md` + `CALL_DEBUG_GUIDE.md`
+- **测试人员** → `TEST_GUIDE.md` + `START_HERE.md`
+- **运维人员** → `CALL_TROUBLESHOOTING_CHECKLIST.md`
+- **用户** → `START_HERE.md`
+
+---
+
+**修改日期：** 2024-03-04
+**修改版本：** 2.0
+**修改人员：** Kiro AI Assistant
+**测试状态：** 待验证
+
+### 1. wx/TUICallKit/MINIAPP_API_DIFFERENCE.md ✅ (新增)
+小程序端与 Web 端 API 差异说明，包含：
+- 核心差异说明
+- 事件监听方式对比（重要！）
+- 正确的使用流程
+- 常见错误及解决
+- 完整示例代码
+- TUIStore 监听方式
+
+### 2. wx/TUICallKit/CANNOT_RECEIVE_CALL_FIX.md ✅
+详细的问题诊断与修复指南
+
+### 3. wx/TUICallKit/CALL_DEBUG_GUIDE.md ✅
+调试指南
+
+### 4. wx/TUICallKit/QUICK_FIX.md ✅
+快速修复指南
+
+### 5. wx/TUICallKit/TEST_GUIDE.md ✅
+完整的测试指南
+
+### 6. wx/TUICallKit/FIX_SUMMARY.md ✅
+修复总结
+
+### 7. wx/TUICallKit/START_HERE.md ✅
+快速开始指南
+
+### 8. CALL_TROUBLESHOOTING_CHECKLIST.md ✅
+问题排查清单
+
+### 9. CHANGES.md ✅
+本文件
+
+## 修改统计
+
+- **修改文件数：** 1
+- **新增文档数：** 9
+- **代码修改行数：** 约 30 行
+- **新增文档行数：** 约 2500 行
+
+## 核心修改点
+
+### 1. 组件挂载时机 ⭐⭐⭐
+**问题：** TUICallKit 组件在登录前就已挂载
+**修复：** 改为登录后才挂载（`v-if="isLogin"`）
+**影响：** 确保组件在正确的时机初始化
+
+### 2. 移除不支持的 API ⭐⭐⭐
+**问题：** 使用了小程序端不支持的 `.on()` 方法
+**修复：** 移除所有 `.on()` 调用，让组件自动处理
+**影响：** 避免 "is not a function" 错误
+
+### 3. 初始化等待 ⭐⭐
+**问题：** 初始化后立即操作可能失效
+**修复：** 添加 1 秒等待时间
+**影响：** 确保初始化完全完成
+
+### 4. userId 格式处理 ⭐⭐
+**问题：** 输入纯数字时格式不匹配
+**修复：** 自动添加前缀（`doctor_`）
+**影响：** 减少用户输入错误
+
+### 5. 日志增强 ⭐
+**问题：** 缺少关键日志，难以调试
+**修复：** 添加详细的日志输出
+**影响：** 便于问题排查
+
+## 重要提示 ⚠️
+
+### 小程序端与 Web 端的关键差异
+
+1. **事件监听方式不同**
+   - ❌ Web 端：`TUICallKitServer.setCallback()` 或 `.on()`
+   - ✅ 小程序端：TUICallKit 组件自动处理，或使用 TUIStore
+
+2. **发起通话方法不同**
+   - ❌ Web 端：`call({ userID, type })`
+   - ✅ 小程序端：`calls({ userIDList, type })`
+
+3. **组件行为不同**
+   - Web 端：需要手动控制显示/隐藏
+   - 小程序端：组件自动处理来电显示
+
+### 必读文档
+
+如果你遇到 API 相关的错误，请务必阅读：
+**wx/TUICallKit/MINIAPP_API_DIFFERENCE.md**
+
+这个文档详细说明了小程序端和 Web 端的所有差异。
+
+## 测试建议
+
+### 必须测试的场景
+
+1. **登录测试**
+   - 输入患者ID
+   - 点击登录
+   - 确认显示"=== TUICallKit 初始化完成，等待来电 ==="
+   - 确认没有错误
+
+2. **接听测试**（最重要）
+   - 小程序端登录
+   - Web 端发起呼叫
+   - 小程序端应自动弹出来电界面
+   - 点击接听
+   - 确认视频和音频正常
+
+3. **发起通话测试**
+   - 小程序端登录
+   - 输入医生ID
+   - 点击呼叫
+   - Web 端应收到来电
+
+### 测试检查点
+
+- [ ] 小程序能正常登录
+- [ ] 控制台没有 "is not a function" 错误
+- [ ] 能收到来电通知
+- [ ] 能正常接听
+- [ ] 视频和音频都正常
+- [ ] 能正常挂断
+
+## 回滚方案
+
+如果修改后出现问题，可以回滚：
+
+```bash
+git checkout HEAD -- wx/TUICallKit/pages/call.vue
+```
+
+## 后续优化
+
+### 可以考虑的改进
+
+1. **使用 TUIStore 监听状态**
+   - 如果需要自定义来电处理
+   - 参考 MINIAPP_API_DIFFERENCE.md
+
+2. **添加心跳检测**
+   - 定期检查连接状态
+
+3. **优化错误提示**
+   - 根据错误码给出具体提示
+
+## 文档使用指南
+
+### 按问题类型查找
+
+- **API 错误（is not a function）** → `MINIAPP_API_DIFFERENCE.md`
+- **无法登录** → `START_HERE.md`
+- **无法接听** → `CANNOT_RECEIVE_CALL_FIX.md`
+- **对方不在线** → `QUICK_FIX.md`
+- **完整测试** → `TEST_GUIDE.md`
+
+### 按角色查找
+
+- **开发人员** → `MINIAPP_API_DIFFERENCE.md` + `FIX_SUMMARY.md`
+- **测试人员** → `TEST_GUIDE.md` + `START_HERE.md`
+- **运维人员** → `CALL_TROUBLESHOOTING_CHECKLIST.md`
+
+---
+
+**修改日期：** 2024-03-04
+**修改版本：** 3.0（修复 API 错误）
+**修改人员：** Kiro AI Assistant
+**测试状态：** 待验证