Mdeical_Sur_Report/工程分析/经验记录.md

经验记录

---

记录 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 提示文字（如 "插入"、"可拖拽"）的显隐样式应尽量保持一致，减少用户认知成本。