2026-04-16-20-46-50 - 压缩关键帧分辨率并增加存储错误日志，修复 LocalStorage 超限导致的关键帧丢失

工程分析/经验记录.md

@@ -234,3 +234,53 @@ if ((settings.autoInsertDelay || 0) > 0) {
 - 在异步循环中，如果某个操作不需要依赖前一步的完成结果，**绝对不要使用 `await` 阻塞主循环**，应改用 `setTimeout` 或 `Promise.all` 实现并行/异步解耦。
 - 当多个定时任务需要按顺序执行时，可以通过索引计算累积延迟（`delay * (index + 1)`），实现简单的"队列式"顺序触发，而不需要阻塞主流程。
 - 在 `setTimeout` 等异步回调中操作 DOM 时，应在回调触发时"实时查询"目标元素，而不是在循环中提前捕获元素引用，以防 DOM 在延迟期间已被用户修改。
+
+
+---
+
+## 记录 11：关键帧在路由切换后丢失——压缩 Canvas 分辨率并增加存储错误日志
+
+**A. 具体问题**
+报告编辑器内容和视频列表在路由切换后能正常保留，但视频分析面板中的自动摘取关键帧和手动截图全部丢失。
+
+**B. 产生问题原因**
+1. **LocalStorage 5MB 容量限制**：当前抽帧逻辑使用视频原始分辨率 + JPEG 质量 0.9：
+   ```tsx
+   canvas.width = video.videoWidth;
+   canvas.height = video.videoHeight;
+   const dataUrl = canvas.toDataURL('image/jpeg', 0.9);
+   ```
+   对于 1080p/4K 视频，单张 Base64 图片可达 300KB~1MB，十几张关键帧即可超过 5MB。
+2. **静默失败**：`storage.ts` 中的 `set` 方法捕获了 `QuotaExceededError` 但没有任何日志：
+   ```typescript
+   } catch {
+     // ignore quota exceeded
+   }
+   ```
+   当 `saveDraftToStorage()` 尝试保存大量关键帧时，`localStorage.setItem` 抛出异常，draft 无法更新，但用户和开发者都感知不到错误。最终返回 `/report-editor` 时，只能读取到"有视频、无关键帧"的旧 draft。
+
+**C. 解决问题方案**
+1. **压缩关键帧分辨率与质量**：
+   - 在 `captureFrame()`（手动截图）和 `autoCaptureFrames()`（自动抽帧）中，增加 Canvas 等比缩放：
+     ```tsx
+     const MAX_WIDTH = 800;
+     const scale = Math.min(1, MAX_WIDTH / video.videoWidth);
+     canvas.width = video.videoWidth * scale;
+     canvas.height = video.videoHeight * scale;
+     ```
+   - 将 JPEG 导出质量从 `0.9` 降到 `0.6`。
+   - 这样单张图片体积可从 500KB 降至 30KB~80KB，有效避免 LocalStorage 超限。
+
+2. **增加存储错误可见性**：
+   - 在 `storage.ts` 的 `set` 和 `setSession` 中，将静默 `catch` 改为输出 `console.error`：
+     ```typescript
+     } catch (e) {
+       console.error('Storage save failed (possibly quota exceeded):', e);
+     }
+     ```
+
+**D. 后续如何避免问题**
+- 任何将 Base64 图片持久化到 `localStorage` 的场景，都必须**预估数据体积**并对图片进行适当的分辨率/质量压缩。
+- 存储层的异常捕获**绝不应静默吞掉**，至少要输出日志，必要时还应弹出用户提示。
+- 对于需要存储大量图片的医疗/图文报告系统，应将 `localStorage` 逐步迁移到 `IndexedDB`，从根本上解除 5MB 容量瓶颈。
+- 在开发测试阶段，应使用高分辨率视频和大批量关键帧进行压力测试，提前暴露存储容量问题。