commit at 2026-04-16-17-55-13

工程分析/经验记录.md

@@ -83,3 +83,30 @@
 - 对于图片/截图类卡片上的操作按钮，应优先考虑不遮挡核心图片内容的区域（如底部、角落），避免影响预览。
 - 在 UI 微调过程中，可以通过小步迭代快速验证用户意图，减少一次性大改导致的方向偏差。
 - 实体按钮比纯文字链接具有更高的可点击性和辨识度，在微小空间中也能提供良好的交互体验。
+
+---
+
+## 记录 5：自动抽帧丢失、模板选择器变"无"与自动帧插入开关
+
+**A. 具体问题**
+用户反馈三个关联问题：
+1. 从其他页面返回 `/report-editor` 后，自动抽帧的图片全部丢失。
+2. 编辑报告后切换界面再返回，"当前模板"显示为"无"。
+3. 希望 system-settings 增加"开启自动帧插入"开关，让自动抽帧直接填充占位符。
+
+**B. 产生问题原因**
+1. **自动抽帧丢失**：`autoCaptureFrames`、`captureFrame`、`removeVideo`、`handleVideoUpload` 中调用 `setCapturedFrames`/`setVideos` 后立即调用 `saveDraftToStorage`，但 `stateRef.current` 中的 `capturedFrames` 和 `videos` 仍是旧值（React 的 setState 是异步的）。因此组件卸载前保存的 draft 里缺少新生成的自动帧。
+2. **模板选择器变"无"**：`saveDraftToStorage` 使用 `useCallback` 捕获了旧的 `loadedTemplateId`（stale closure）。编辑报告时 `loadedTemplateId` 未通过 `stateRef.current` 同步，导致 draft 中的 `loadedTemplateId` 为空字符串，恢复后模板选择器显示"无"。
+3. **自动帧插入需求**：用户希望减少手动拖拽操作，提升效率。
+
+**C. 解决问题方案**
+1. **修复状态同步**：将 `loadedTemplateId` 纳入 `stateRef.current`，并在 `saveDraftToStorage` 调用前先强制同步 `stateRef.current = { reportData, videos, capturedFrames, activeTab, loadedTemplateId }`。同时，在所有修改 `videos` 和 `capturedFrames` 的函数（`handleVideoUpload`、`removeVideo`、`captureFrame`、`autoCaptureFrames`）中，手动将最新状态同步到 `stateRef.current` 后再 `saveDraftToStorage`。
+2. **新增自动帧插入开关**：
+   - `SystemSettings` 类型增加 `autoInsertFrames?: boolean`。
+   - `SystemSettings.tsx` 增加 checkbox 开关，并在每个 `framePositions` 百分比旁显示绿色 `Check` 对勾。
+   - `ReportEditor.tsx` 的 `autoCaptureFrames` 中，每生成一帧后若开关开启，则查找第一个 `.image-placeholder:not(.has-image)` 并填充图片；若找不到则静默跳过，不弹窗。循环结束后统一更新 `contentRef.current` 并保存草稿。
+
+**D. 后续如何避免问题**
+- 当多个状态需要同时持久化到 localStorage（如通过 draft 机制），应避免依赖异步 setState 后的自动同步。在保存前手动将最新计算值同步到 ref 或直接在保存函数中传入最新值，是更可靠的做法。
+- `useCallback` 的依赖数组虽然能触发重新创建函数，但函数体内部若同时读取 state 和 ref，仍可能出现 stale closure。将可变状态统一收敛到 ref 中，并在保存前强制刷新 ref，可有效避免此类问题。
+- 新增业务开关时，类型定义、设置页面、消费逻辑三个点必须同步修改，并在 UI 上给予用户明确的视觉反馈（如此次的绿色对勾标记）。