新增功能

2026-03-24 16:32:56 +08:00
parent 250d173c2f
commit 9160c36735
248 changed files with 3063 additions and 250 deletions
@@ -0,0 +1,144 @@
+# 本地录制修复总结
+
+## 问题根源
+
+通过分析实际日志发现，本地录制失败的根本原因是：
+
+1. **录制启动太晚**：1200ms 延迟导致录制在对方挂断后才启动
+2. **SDK 提前销毁轨道**：`stopLocalVideo/stopLocalAudio` 在录制完成前就销毁了视频轨道
+3. **时间窗口极短**：从对方离开到轨道销毁只有 200-300ms
+
+## 关键时间线（问题场景）
+
+```
+15:30:51.841 - 对方离开（USER_LEAVE 事件）
+15:30:51.xxx - beginStopNow 被调用（但录制还未启动！）
+15:30:52.072 - stopLocalVideo/stopLocalAudio（轨道被销毁）
+15:30:52.102 - exitRoom
+15:30:52.374 - MediaRecorder 已启动（太晚了！）
+15:30:52.xxx - 数据块数: 0（因为轨道已销毁）
+```
+
+## 修复方案
+
+### 1. 大幅缩短录制启动延迟
+- **从 1200ms 缩短到 500ms**
+- 使用 300ms 间隔快速重试（最多 10 次）
+- 目标：在通话接通后 1 秒内启动录制
+
+### 2. 在通话结束事件时立即停止录制
+- 监听 `TUICallEvent.USER_LEAVE`、`CALL_END`、`ON_CALL_NOT_CONNECTED`
+- 检测到事件时立即调用 `beginStopNow()`
+- 抢在 SDK 销毁轨道前完成录制
+
+### 3. 缩短停止延迟
+- **从 300ms 缩短到 100ms**
+- 减少等待时间，避免 SDK 提前销毁轨道
+
+### 4. 智能视频元素检测
+- 首先检查容器内的视频
+- 如果没有，检查 body（TUICallKit Teleport）
+- 过滤出有活跃视频流的元素
+- 验证 readyState >= HAVE_CURRENT_DATA
+
+## 修改的文件
+
+1. **admin/src/components/chat-dialog/index.vue**
+   - 缩短录制启动延迟（1200ms → 500ms）
+   - 添加快速重试机制（300ms 间隔，最多 10 次）
+   - 在 `bindEngineRoomEvents` 中添加立即停止逻辑
+   - 增强日志输出
+
+2. **admin/src/utils/call-local-recorder.ts**
+   - 缩短停止延迟（300ms → 100ms）
+   - 增强日志输出
+   - 添加详细的状态跟踪
+
+3. **LOCAL_RECORDING_DEBUG_GUIDE.md**
+   - 完整的调试指南
+   - 常见问题诊断
+   - 测试建议
+
+4. **admin/test-local-recording.html**
+   - 独立的测试工具
+   - 浏览器兼容性检测
+   - MediaRecorder 功能测试
+
+## 测试步骤
+
+### 1. 清除浏览器缓存
+确保使用最新的代码。
+
+### 2. 打开控制台
+F12 打开开发者工具，切换到 Console 标签。
+
+### 3. 发起视频通话
+点击视频通话按钮。
+
+### 4. 观察关键日志
+
+#### 接通后应该看到（1 秒内）：
+```
+[chat-dialog] 尝试启动本地录制（第 1 次）
+[chat-dialog] 视频元素已就绪，立即启动录制
+[call-local-recorder] MediaRecorder.start() 调用成功
+[call-local-recorder] MediaRecorder 已启动
+[chat-dialog] ✅ 本地录制已成功启动
+```
+
+#### 通话过程中应该看到（每 250ms）：
+```
+[call-local-recorder] 收到数据块，大小: 12345 (总计: 1 块)
+[call-local-recorder] 收到数据块，大小: 15678 (总计: 2 块)
+```
+
+#### 挂断时应该看到：
+```
+[chat-dialog] 检测到通话结束事件，立即停止录制
+[call-local-recorder] beginStopNow 被调用
+[call-local-recorder] 准备停止 MediaRecorder，当前状态: recording 已收集数据块: 15
+[call-local-recorder] 生成 Blob: 1234567 bytes
+[chat-dialog] 开始上传录制文件
+本地录制已上传并关联到通话记录
+```
+
+### 5. 验证结果
+- 检查诊单是否有录制文件
+- 播放录制文件验证内容
+
+## 预期效果
+
+### 修复前
+- 录制成功率：0%
+- 数据块数：0
+- Blob 大小：null
+
+### 修复后
+- 录制成功率：>95%（通话时长 > 2 秒）
+- 数据块数：>= 通话秒数 * 4
+- Blob 大小：>= 通话秒数 * 50KB
+
+## 注意事项
+
+1. **最短通话时长**：建议至少 2 秒，否则可能来不及启动录制
+2. **浏览器兼容性**：Chrome/Edge 85+、Firefox 78+、Safari 14.1+
+3. **网络状况**：网络差时视频流可能不稳定，影响录制质量
+4. **权限问题**：确保浏览器已授予摄像头和麦克风权限
+
+## 如果问题仍然存在
+
+1. 查看完整的控制台日志
+2. 确认录制是否在接通后 1 秒内启动
+3. 确认是否有 "收到数据块" 日志
+4. 检查通话时长是否 > 2 秒
+5. 参考 `LOCAL_RECORDING_DEBUG_GUIDE.md` 进行详细诊断
+
+## 进一步优化方向
+
+如果修复后仍有问题，可以考虑：
+
+1. **进一步缩短启动延迟**：300ms 或更短
+2. **使用 MutationObserver**：监听视频元素添加，立即启动
+3. **添加录制状态监控**：定期检查 MediaRecorder 状态
+4. **添加降级方案**：本地录制失败时提示用户
+5. **添加手动控制**：让用户手动开始/停止录制