# 经验记录

---

## 记录 1：report-editor 新建报告时显示空白模板

**A. 具体问题**
超级管理员进入 `/report-editor`（新建报告）时，编辑区域为纯白色空白，顶部模板选择器显示"无"，但 system-settings 中已配置了默认模板。

**B. 产生问题原因**
1. `ReportEditor.tsx` 在组件卸载（如页面切换）时会自动将当前编辑器内容保存为草稿（draft）。即使用户未输入任何内容，保存的 `content` 也是空字符串 `""`。
2. 初始化 effect 中判断草稿是否有效的条件仅使用了 `typeof draft.content === 'string'`，空字符串满足该条件，导致编辑器被填充为空白 HTML，并将 `contentLoadedRef.current` 设为 `true`。
3. 由于 `contentLoadedRef.current` 已被置为 `true`，后续加载 `settings.defaultTemplate` 的默认模板分支被完全跳过，从而永远显示空白。
4. 此外，草稿中未保存 `loadedTemplateId`，即使内容非空时恢复草稿，模板选择器也会因缺少状态而显示"无"。

**C. 解决问题方案**
1. 在 `saveDraftToStorage` 中将当前 `loadedTemplateId` 一并存入 draft。
2. 将四处草稿恢复的判断条件从 `typeof draft.content === 'string'` 收紧为 `typeof draft.content === 'string' && draft.content.trim().length > 0`，使空白草稿不再拦截默认模板加载。
3. 恢复草稿时同步执行 `setLoadedTemplateId(draft.loadedTemplateId || '')`，确保模板选择器名称正确。

**D. 后续如何避免问题**
- 在前端使用 contentEditable 的自动保存机制时，保存和恢复草稿都应增加对空/仅空白内容的过滤。
- 若草稿与某个业务状态（如当前模板 ID）强关联，应确保两者一并持久化和恢复，避免状态不一致。
- 对兜底初始化逻辑（如默认模板加载）增加更严格的防护，防止被无效中间状态提前截断。

---

## 记录 2：关键帧一键插入占位符功能实现

**A. 具体问题**
用户希望视频分析面板中的关键帧截图除了拖拽插入外，还能通过点击 "插入" 按钮一键自动填充到编辑器中第一个空置的 `image-placeholder`。

**B. 产生问题原因**
原先仅支持拖拽方式将关键帧放入占位符。当关键帧数量多或占位符位置较远时，操作不便。且 `handleDrop` 中的填充逻辑未抽离，无法被其他交互方式复用。

**C. 解决问题方案**
1. 将 `handleDrop` 中的 HTML 填充逻辑抽离为 `fillPlaceholder(placeholder, frame)` 公共函数。
2. 新增 `insertFrameToPlaceholder(frame)` 函数：通过 `editorRef.current.querySelector('.image-placeholder:not(.has-image)')` 查找第一个空置占位符，找到则调用 `fillPlaceholder`，未找到则 `alert('没有可插入图片的空位')`。
3. 在关键帧卡片底部的 `timeFormatted` 与 "可拖拽" 之间新增 "插入" 按钮，使用 `opacity-0 group-hover:opacity-100 transition-opacity` 与 "可拖拽" 保持一致的显隐行为，并通过 `e.stopPropagation()` 避免触发卡片的视频跳转 `onClick`。

**D. 后续如何避免问题**
- 当同一交互效果（如填充占位符）需要支持多种触发方式（拖拽、按钮点击、快捷键等）时，应将核心逻辑抽离为独立函数，避免重复代码。
- 在可点击子元素上务必注意事件冒泡控制，防止触发父级不必要的副作用（如此处的视频跳转）。
- UI 提示文字（如 "插入"、"可拖拽"）的显隐样式应尽量保持一致，减少用户认知成本。

---

## 记录 3：关键帧 "插入" 按钮位置与样式优化

**A. 具体问题**
用户对已实现的 "插入" 按钮位置和样式提出优化：希望按钮位于图片中央、做成实体按钮样式、颜色与 "可拖拽" 的蓝色有明显区分。

**B. 产生问题原因**
初次实现时将 "插入" 按钮放在了卡片底部文字区域，采用纯文字链接样式（`text-accent`），视觉上不够醒目，且与 "可拖拽" 提示颜色重叠，辨识度低。

**C. 解决问题方案**
1. 将 "插入" 按钮从底部文字行移到图片层的 `<div className="relative">` 容器内，使用 `absolute inset-0 m-auto w-fit h-fit` 实现水平和垂直居中。
2. 将按钮样式改为实体胶囊按钮：`px-3 py-1.5 bg-emerald-500 text-white rounded-full shadow-md`，hover 时加深为 `bg-emerald-600`。
3. 底部文字区域只保留 `timeFormatted` 和 "可拖拽" 提示，"插入" 按钮不再与它们并列。

**D. 后续如何避免问题**
- 对于图片卡片上的核心操作按钮，优先考虑覆盖在图片中央或显著位置，比在底部小字中放置链接更符合用户直觉。
- 同一卡片上的多个 hover 提示元素应保持显隐动画一致（`opacity-0 group-hover:opacity-100 transition-opacity`），但颜色上要有区分，避免用户混淆不同功能。
- 使用 `absolute inset-0 m-auto w-fit h-fit` 是一种在 Tailwind 中不依赖 flex/grid 的居中技巧，适合在 `relative` 容器内居中不定宽高的元素。

---

## 记录 4：关键帧 "插入" 按钮位置微调（从图片中央移回底部）

**A. 具体问题**
用户反馈将 "插入" 按钮放在图片正中央会遮挡图片内容，希望移回卡片底部，但仍保留实体按钮样式和蓝色。

**B. 产生问题原因**
按钮以 `absolute` 层覆盖在图片中央时，确实会遮挡部分图片内容，对于医学影像类截图可能影响用户预览。

**C. 解决问题方案**
1. 将 "插入" 按钮从图片层的 absolute 覆盖层移回卡片底部的文字行，放置在 `timeFormatted` 与 "可拖拽" 之间。
2. 按钮颜色恢复为蓝色（`bg-accent text-white`），与 "可拖拽" 蓝色保持一致，视觉上统一。
3. 保留实体胶囊按钮样式：`px-2 py-0.5 rounded-full shadow-sm`，不再是纯文字链接。
4. 显隐行为仍通过 `opacity-0 group-hover:opacity-100 transition-opacity` 与 "可拖拽" 同步。

**D. 后续如何避免问题**
- 对于图片/截图类卡片上的操作按钮，应优先考虑不遮挡核心图片内容的区域（如底部、角落），避免影响预览。
- 在 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 上给予用户明确的视觉反馈（如此次的绿色对勾标记）。