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

---

## 记录 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. 具体问题**
在 `/report-editor` 中上传视频、自动摘取关键帧、手动截图或拖拽截图到 `image-placeholder` 后，切换到 `/report-manage` 等其他页面再返回 `/report-editor`，右侧「视频分析」面板中的所有截图和关键帧全部消失；编辑器中已拖拽到 placeholder 的图片也不可见。

**B. 产生问题原因**
1. `ReportEditor.tsx` 在组件卸载时通过 `stateRef.current` 保存草稿到 `localStorage`。
2. 初始化 `useEffect` 和 `useLayoutEffect` 从 draft 或已保存报告恢复数据时，仅通过 `setState` 更新了 React state（`videos`、`capturedFrames`），但 **没有同步更新 `stateRef.current`**。
3. 用户首次进入页面时数据正确显示；离开页面时，`stateRef.current` 仍保存着初始值（空数组），导致 `saveDraftToStorage()` 用空数组覆盖了 localStorage 中的 draft。
4. 再次返回页面时，系统优先读取被污染后的 draft，从而丢失了所有视频分析数据。

**C. 解决问题方案**
在 `ReportEditor.tsx` 的 6 个数据恢复入口（初始化 `useEffect` 的 3 个分支 + `useLayoutEffect` 安全网的 3 个分支）中，恢复 `reportData`、`videos`、`capturedFrames` 后立即同步赋值给 `stateRef.current`，确保后续草稿保存时数据完整。

**D. 后续如何避免问题**
- 当使用 `useRef` 作为「自动保存」的数据快照时，**任何从持久化存储恢复数据到 React state 的操作，必须同步更新对应的 ref**，否则 ref 将始终保存陈旧值。
- 在涉及草稿/自动保存的功能中，应定期审查所有数据恢复路径（初始化 effect、安全网 effect、手动导入等），确保 ref 与 state 的一致性。
- 对于复杂单文件组件，可考虑将「持久化 ↔ 状态同步」逻辑抽离为统一的数据恢复函数，集中处理 ref 同步，减少遗漏点。


---

## 记录 6：路由切换后报告内容、基本信息、视频分析全部丢失 + 自动帧插入 UI 延迟刷新

**A. 具体问题**
1. 在 `/report-editor` 中编辑报告后，切换到 `/report-manage` 再返回 `/report-editor`，**报告内容变空、基本信息清空、视频分析数据全部丢失**。
2. 开启「自动帧插入」后，自动关键帧摘取过程中右侧关键帧列表和 placeholder 中的图片**不会逐张实时更新**，而是等所有帧全部处理完后一次性批量出现。

**B. 产生问题原因**
1. **数据丢失原因**：在初始化 `useEffect` 中，将 `stateRef.current` 的同步赋值放在了 `if (editorRef.current && draft.content.trim().length > 0)` 条件块的内部。当组件首次渲染时 `editorRef` 尚未挂载，或 `draft.content` 为空（新建报告常见场景），`stateRef.current` 就得不到同步，始终保存着初始空值。组件卸载时，空值被保存为 draft，覆盖了用户已有的数据。
2. **UI 延迟原因**：`autoCaptureFrames` 是一个 async 函数，内部循环中连续调用 `setCapturedFrames`。由于 React 18 的自动批处理机制，在异步函数中连续的状态更新会被合并，DOM 重渲染被推迟到整个循环结束后才执行一次，导致用户看不到逐帧实时更新的效果。

**C. 解决问题方案**
1. **修复数据丢失**：在 `ReportEditor.tsx` 初始化 `useEffect` 的 3 个数据恢复分支（draft 恢复已有报告、found 恢复已有报告、draf t 恢复新建报告）中，将 `stateRef.current` 的同步赋值**移到 `editorRef.current/content` 判断条件的外部**，确保无论编辑器 DOM 是否已挂载、`content` 是否为空，`reportData`、`videos`、`capturedFrames` 都会立即写入 `stateRef.current`。
2. **清理重复代码**：顺带移除了 `found` 恢复分支中 `contentRef.current = found.content;` 的重复赋值。
3. **修复 UI 延迟**：在 `autoCaptureFrames` 的 for 循环中，将 `setCapturedFrames` 包裹在 `flushSync(() => { ... })` 中，强制每一帧被摘取后立即触发 DOM 更新，实现逐张实时显示和逐张插入 placeholder。

**D. 后续如何避免问题**
- 当使用 `useRef` 作为自动保存的数据快照时，**ref 的同步赋值绝对不能依赖于任何与 UI 渲染相关的条件判断**（如 `editorRef.current` 是否存在、`content` 是否非空），否则在组件挂载前或内容为空时会导致数据丢失。
- 在异步函数中需要让用户看到实时状态更新时，应使用 `flushSync` 强制同步渲染，避免被 React 自动批处理延迟。
- 对于复杂单文件组件中的「恢复数据」逻辑，建议将所有 `setState` 和对应的 `ref` 同步集中在一个统一的恢复函数中处理，减少遗漏点和条件嵌套。


---

## 记录 7：重新部署应用（Vite 生产构建 + Vite Preview）

**A. 具体问题**
用户要求将最新代码重新部署到生产环境，但当前运行环境中未安装 Docker，无法使用项目自带的 `docker-compose.yaml` 进行容器化部署。

**B. 产生问题原因**
1. 当前 Windows 环境缺少 Docker 和 docker-compose CLI；
2. 项目本身是基于 Vite 的前端应用，可通过 `npm run build` 生成静态文件后，使用 `vite preview` 或任意静态文件服务器进行部署；
3. 系统中已存在旧版本的 `vite preview` 进程在运行，需要先停止旧服务再启动新服务。

**C. 解决问题方案**
1. 使用 PowerShell 查询并强制停止所有属于当前项目目录的旧 `vite preview` 进程；
2. 执行 `npm run build` 重新构建生产包；
3. 使用 `cmd /c "start /B npm run preview"` 在后台启动新的 Vite 预览服务器；
4. 通过 `Invoke-WebRequest` 访问 `http://localhost:4173/` 验证服务返回 HTTP 200，确认部署成功。

**D. 后续如何避免问题**
- 在无法使用 Docker 的环境中，可将 `npm run build && npm run preview` 作为标准部署脚本；
- 重新部署前务必先清理旧的同类型进程，避免端口冲突或多版本服务同时运行导致访问混乱；
- 如需固定端口，可在 `package.json` 的 `preview` 脚本中增加 `--port` 参数（如 `vite preview --port 8080`）。


---

## 记录 8：路由切换后所有内容仍然丢失——彻底重构自动保存机制

**A. 具体问题**
在 `/report-editor` 中编辑报告（填写基本信息、上传视频、自动/手动截取关键帧、拖拽图片到 placeholder）后，切换到 `/report-manage` 再返回 `/report-editor`，报告编辑器内容、基本信息、视频列表、关键帧截图**全部丢失**。

**B. 产生问题原因**
1. 自动保存机制过度依赖 `stateRef` 和 `contentRef` 作为"数据快照"。
2. **React 18 `StrictMode`** 在开发/预览环境下会执行"挂载 → 立即卸载 → 重新挂载"。在首次模拟卸载时，`stateRef.current` 仍然是组件创建时的初始空值（`videos: []`、`capturedFrames: []`、默认 `reportData`）。
3. 组件卸载（cleanup）时调用保存，用这个空值**覆盖了 localStorage 中已有的正确 draft**。
4. 重新挂载后，系统读取了被清空的 draft，导致所有数据全部丢失。
5. 此前两次修复仅把 `stateRef.current` 同步移到了更多恢复分支中，但**没有从根本上消除对 ref 的依赖**，因此 `StrictMode` 下的首次卸载仍会覆盖有效 draft。

**C. 解决问题方案**
1. **彻底重构 `saveDraftToStorage`**：不再读取 `contentRef.current` 和 `stateRef.current`，而是直接从最新的 React state 和 `editorRef.current?.innerHTML` 获取数据。`useCallback` 的 dependency 数组包含 `reportData`、`videos`、`capturedFrames`、`activeTab`、`loadedTemplateId`、`reportId`，确保闭包永远绑定当前渲染周期的最新 state。
2. **重构自动保存 effect**：将 `beforeunload` 和 `visibilitychange` 事件处理器直接绑定到 `saveDraftToStorage`，effect 的 dependency 改为 `[saveDraftToStorage]`。这样即使 `StrictMode` 导致组件在首次挂载后立即卸载，cleanup 中调用的 `saveDraftToStorage` 也指向最新数据的闭包，不会用空值覆盖已有 draft。
3. **给 `useLayoutEffect` 安全网添加 `[]` 依赖**：防止每次渲染后重复执行，避免潜在的意外覆盖。

**D. 后续如何避免问题**
- **永远不要将 `useRef` 作为自动保存的唯一数据源**。ref 在 React 18 `StrictMode` 的模拟卸载阶段仍然保持初始值，会导致用空数据覆盖有效持久化数据。
- 自动保存函数应直接从最新的 React state 和 DOM 读取数据，通过 `useCallback` + 完整的 dependency 数组保证闭包始终新鲜。
- 在开发阶段应始终开启 `StrictMode` 测试，因为它能暴露 ref-based 状态同步在卸载/重挂载时的隐藏 bug。
- 对于大型表单/编辑器组件，应将自动保存逻辑与业务状态彻底解耦，统一通过 hook 的最新状态闭包来持久化。


---

## 记录 9：编辑器内容和关键帧在路由切换后仍然丢失——从 Ref 读取避免闭包陷阱和 DOM 失效

**A. 具体问题**
在 `/report-editor` 中编辑报告（输入文字、上传视频、自动/手动摘取关键帧、拖拽图片到 placeholder）后，切换到 `/report-manage` 再返回 `/report-editor`：
- `class="editor-content-wrapper print-wrapper"` 中的报告内容全部丢失；
- 视频分析面板中的自动关键帧和手动截图全部丢失。

**B. 产生问题原因**
1. **闭包陷阱**：之前为修复 `stateRef` 不同步的问题，将 `saveDraftToStorage` 改为直接从 React state（如 `capturedFrames`、`videos`）读取。但代码中大量存在 `setCapturedFrames(nextFrames); saveDraftToStorage();` 的写法。由于 `setState` 是异步的，`saveDraftToStorage` 闭包中读到的 `capturedFrames` 仍然是旧值（空数组），导致旧值覆盖了 localStorage 中的有效 draft。
2. **卸载时 DOM 失效**：组件卸载时 React 开始销毁 DOM 树，`editorRef.current` 可能已经变为 `null` 或其 `innerHTML` 已为空。`content: editorRef.current?.innerHTML || ''` 会把空字符串保存到 draft 中，导致报告内容丢失。
3. **`contentRef` 更新遗漏**：在 `handleEditorClick` 中通过 `document.execCommand('delete')` 删除 placeholder 后，直接调用了 `saveDraftToStorage()`，但没有先更新 `contentRef.current`，进一步加剧了内容不一致。

**C. 解决问题方案**
1. **重构 `saveDraftToStorage` 从 Ref 读取**：
   - `content` 优先读取 `contentRef.current`（内存引用，卸载时仍稳定存在），回退到 `editorRef.current?.innerHTML`。
   - `reportData`、`videos`、`capturedFrames`、`activeTab`、`loadedTemplateId` 全部从 `stateRef.current` 读取，彻底避开 React state 的闭包陷阱。
   - `useCallback` 的 dependency 仅保留 `[reportId]`，避免因 state 变化产生陈旧闭包。
2. **补齐 `contentRef` 遗漏**：在 `handleEditorClick` 的 `document.execCommand('delete')` 分支后，增加 `if (editorRef.current) contentRef.current = editorRef.current.innerHTML;`，确保 DOM 修改后 `contentRef` 及时同步。

**D. 后续如何避免问题**
- 对于需要在异步操作或组件卸载时读取的"最新状态"，**应优先使用 `useRef` 作为稳定的数据快照**，而不是依赖 React state 的闭包。
- 自动保存函数的 `useCallback` dependency 应尽量精简（如只保留 `reportId`），避免因 state 变化导致闭包更新不同步。
- 任何直接操作 DOM 修改编辑器内容的代码，都必须**紧跟一行 `contentRef.current = editorRef.current.innerHTML`**，确保内存中的内容快照与 DOM 保持一致。
- 在开发阶段应定期测试「组件卸载 → 重新挂载」的场景（React 18 `StrictMode` 会自动模拟），提前暴露闭包和 ref 同步问题。


---

## 记录 10：自动帧插入阻塞关键帧摘取——改为 setTimeout 非阻塞异步插入

**A. 具体问题**
开启「自动帧插入」后，点击「自动关键帧摘取」时，系统不是快速完成所有关键帧的摘取，而是每摘取一张就停下来等待插入延迟（如 2 秒），插入完成后才继续摘取下一张。整体过程非常缓慢，用户体验卡顿。

**B. 产生问题原因**
`autoCaptureFrames` 的 `for` 循环内部，自动插入逻辑使用了 `await new Promise<void>(r => setTimeout(...))`：
```tsx
if ((settings.autoInsertDelay || 0) > 0) {
  await new Promise<void>(r => setTimeout(r, (settings.autoInsertDelay || 0) * 1000));
}
```

`await` 会暂停整个 `for` 循环的执行，导致关键帧摘取和插入变成了串行阻塞流程：必须等插入完成才能摘取下一张。

**C. 解决问题方案**
1. 将 `await new Promise(...)` 替换为 `setTimeout(...)`，把插入操作推入事件队列异步执行，`for` 循环不再被阻塞，可以全速完成所有关键帧的摘取。
2. 实现延迟叠加（顺序插入）：通过 `settings.autoInsertFrameIndices.indexOf(i)` 计算当前帧是第几个需要插入的，延迟时间为 `baseDelay * (insertOrderIndex + 1)`，避免所有图片在同一时刻同时插入。
3. `setTimeout` 回调中实时查询 `.image-placeholder:not(.has-image)`，找到则插入，并同步更新 `contentRef.current` 和调用 `saveDraftToStorage()`。

**D. 后续如何避免问题**
- 在异步循环中，如果某个操作不需要依赖前一步的完成结果，**绝对不要使用 `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 容量瓶颈。
- 在开发测试阶段，应使用高分辨率视频和大批量关键帧进行压力测试，提前暴露存储容量问题。

---

## 记录 12：contentEditable 中实现标签锁定与输入方格的双向绑定

**A. 具体问题**
需要在 `ReportEditor` 和 `TemplateManage` 的富文本编辑器中插入"标签锁定、内容可调"的智能占位控件，使"姓名："等固定文本不会被用户误删，同时方格内的输入能与右侧【基本信息】表单双向联动。

**B. 产生问题原因**
原生 `contentEditable` 区域内所有文本节点对用户都是可编辑的，无法直接保护某一段固定标签不被单独删除或篡改。若仅用样式区分的普通 `<span>`，用户仍可通过退格键将"姓名："删掉一半或改乱。

**C. 解决问题方案**
采用三层嵌套 HTML 结构：
1. **外层** `<span class="smart-field-wrapper" contenteditable="false">`：作为不可编辑的框架，确保整个控件不会被内部逐字删除。
2. **标签层** `<span class="field-label">`：显示固定文本如"姓名："，受外层保护。
3. **输入层** `<span class="field-value" contenteditable="true" data-bind="patientName">`：允许用户输入，并通过 `data-bind` 属性建立与 `reportData` 的映射关系。

双向绑定逻辑：
- **富文本 → 表单**：在 `handleEditorInput` 中通过 `e.target.hasAttribute('data-bind')` 判断输入源，实时更新 `reportData`。
- **表单 → 富文本**：在 `useEffect` 中监听 `reportData` 变化，仅当 `el.innerText !== newValue` 时才重写 DOM，防止光标跳动。

**D. 后续如何避免问题**
- 对于需要在富文本中保护的固定文本，优先采用 `contenteditable="false"` 的包装器，而不是仅靠样式区分的普通 `<span>`。
- 在 `State -> DOM` 的同步中务必加入差异判断，避免不必要的 DOM 重写导致输入焦点异常。
- 数组类型字段（如 `surgeon`）在同步到方格前应先 `join(', ')` 转换为字符串，保持显示一致性。

---

## 记录 13：手术时间方框化、动态字段分类体系与 UI 紧凑化

**A. 具体问题**
1. 手术开始/终止时间在模板中是纯文本"时 分"，无法与右侧表单联动。
2. `TemplateManage` 的字段库是静态列表，无法按医院需求自定义字段；`ReportEditor` 的右侧表单全部硬编码，每新增一个字段就要改代码。
3. `field-value` 方格使用了 `min-width: 60px` 和上下 `padding`，导致行间距被撑大，排版松散。

**B. 产生问题原因**
1. 时间字段在 `defaultContent.ts` 中没有使用 `data-bind` 智能控件，且右侧表单将时间拆分为 `startHour`/`startMinute` 两个独立字段，缺少与方格的双向转换层。
2. 早期设计采用了"硬编码表单"思路，字段名、类型、选项全部写死在 `ReportEditor.tsx` 的 JSX 中，不具备扩展性。
3. `inline-block` 元素自带上下 `padding` 和 `border`，超出了默认行高，浏览器不得不增大整行高度以容纳它。

**C. 解决问题方案**
1. **时间方框联动**：
   - 在 `defaultContent.ts` 中替换为 `data-bind="startTime"` 和 `data-bind="endTime"` 的方格。
   - 在 `ReportEditor.tsx` 的 `handleEditorInput` 中，对 `startTime`/`endTime` 使用 `split(':')` 解析，反向更新 `startHour`/`startMinute`；在 `useEffect(reportData)` 中拼接 `HH:mm` 同步回方格。
2. **动态字段体系**：
   - 在 `types.ts` 中新增 `FieldType`、`FormField`、`DEFAULT_FORM_FIELDS`，定义字段的 key/label/分类/类型/显隐/锁定状态/选项。
   - 使用 `localStorage` 的 `formFieldsConfig` 持久化字段配置。
   - `TemplateManage.tsx` 右侧字段库重构为 Tab 结构：【插入字段】按"填空/单选/多选/时间"分组；【字段管理】支持新增、删除（非锁定字段）、显隐开关。
   - `ReportEditor.tsx` 右侧基本信息表单改为遍历 `formFieldsConfig`、按 `type` switch-case 动态渲染（文本框/下拉框/多选标签/时间拆分下拉框）。
3. **UI 紧凑化**：
   - 将 `min-width` 从 `60px` 缩至 `32px`。
   - 去除上下 `padding`，使用 `line-height: 1.2`、`font-size: inherit`、`vertical-align: text-bottom`。
   - 背景色改为 `#f8fafc`（编辑态更明显），打印时恢复透明并只保留下划线。

**D. 后续如何避免问题**
- 对于需要将多个子字段映射到单一 UI 控件的场景，应在事件处理器和 `useEffect` 中各维护一层"拼接/解析"转换逻辑，保持底层数据结构不变。
- 当表单字段超过 5 个且存在频繁变更需求时，应尽早从硬编码 JSX 转向"配置驱动渲染"（Config-Driven UI），降低后续维护成本。
- 在 `contentEditable` 中插入 `inline-block` 元素时，务必通过 `line-height`、`vertical-align` 和最小化 `padding` 控制其对行高的影响，避免破坏段落排版的紧凑性。

---

## 记录 16：模板字段唯一性、删除按钮与报告批量导出

**A. 具体问题**
1. `TemplateManage` 中智能字段可以重复插入多次，导致模板混乱。
2. 智能字段在某些边界位置（如段落开头/结尾）无法通过 Backspace/Delete 删除。
3. `ReportManage` 缺少报告导出功能和批量操作能力。

**B. 产生问题原因**
1. `insertSmartField` 没有检测 DOM 中是否已存在相同 `data-bind` 的字段节点。
2. 之前的 `keydown` 拦截逻辑只处理了光标在文本节点内的情况，没有处理光标直接在块级父节点边界（`startContainer` 为 `<p>` 等块元素）的场景。
3. `ReportManage` 的设计只支持单条查看/编辑/删除，没有设计多选状态和导出逻辑。

**C. 解决问题方案**
1. **唯一性校验**：在 `insertSmartField` 中通过 `editorRef.current?.querySelector([data-bind="..."])` 预检查，若已存在则 `alert` 并终止插入。
2. **删除按钮**：给 `.smart-field-wrapper` 内部增加一个红色圆形的 `<span class="delete-btn">×</span>`，点击即可删除整个字段节点。同时在 `index.css` 和 `print` 媒体查询中分别定义显示/隐藏样式。
3. **键盘删除增强**：重写 `keydown` 处理器，同时处理 `startContainer` 为 `TEXT_NODE` 和 `ELEMENT_NODE` 两种情况。当光标位于块级父节点的子节点边界时，通过 `el.childNodes[offset - 1]` 或 `el.childNodes[offset]` 定位字段节点并安全删除。
4. **报告批量操作**：
   - 在 `ReportManage.tsx` 中引入 `selectedIds` 状态，表格每行增加 Checkbox，表头支持全选/反选。
   - 增加浮动批量操作栏，支持"批量删除"、"批量导出 PDF"、"批量导出 JSON"、"取消选择"。
   - 单报告操作列增加"导出"按钮，点击弹出模态框选择 PDF 或 JSON。
   - PDF 导出复用现有的 `printDocument(content)`；JSON 导出通过 `Blob` + `URL.createObjectURL` 实现下载，数据结构包含 `meta`（报告元信息）和 `fields`（所有 `DEFAULT_FORM_FIELDS` 对应值）。
   - 批量 PDF 将多份报告的 HTML 用 `<div style="page-break-after: always;"></div>` 拼接后统一打印。
   - 批量 JSON 将多份报告导出为数组形式的单个 `.json` 文件。

**D. 后续如何避免问题**
- 在 `contentEditable` 中插入的任何可复用控件，都应考虑增加唯一性校验和明确的删除入口（可视化按钮 + 键盘事件拦截）。
- 键盘事件处理不能假设 `startContainer` 一定是文本节点，必须覆盖块级元素边界的情况。
- 当列表页需要增加批量操作时，建议将"选择状态"和"批量动作"封装为独立逻辑，保持单条操作按钮的可维护性。
- 导出功能应尽量复用现有的 `printDocument` 等工具函数，减少新依赖引入。

---

## 记录 17：字段聚焦高亮、删除按钮显隐隔离与 multi_select 脏数据崩溃修复

**A. 具体问题**
1. `TemplateManage` 中编辑智能字段时缺少视觉焦点反馈，用户体验不够直观。
2. 红色 × 删除按钮始终显示在字段内部左侧，且在任何包含 `smart-field-wrapper` 的页面（包括 `ReportEditor`）都会显示。
3. `ReportEditor` 加载某些历史报告时崩溃，报错 `(y[x.key] || []).map is not a function`。

**B. 产生问题原因**
1. 之前没有为 `.field-value` 定义 `:focus` 状态的 CSS 样式。
2. `delete-btn` 使用 `display: inline-flex` 默认常驻显示，且没有针对页面做显隐隔离。
3. `multi_select` 字段（如 `surgeon`、`assistant`）的渲染直接对值调用 `.map()`，但旧数据或异常存储可能将其保存为字符串（如 `"张医生"` 而非 `["张医生"]`），导致 `.map` 在字符串上调用时抛出 `TypeError`。

**C. 解决问题方案**
1. **聚焦高亮**：在 `index.css` 中为 `.smart-field-wrapper .field-value:focus` 增加背景色加深（`#e2e8f0`）、边框变深（`#94a3b8`）和蓝色外发光（`box-shadow: 0 0 0 2px rgba(59,130,246,0.25)`）的样式，配合 `transition` 实现平滑反馈。
2. **删除按钮定位与显隐隔离**：
   - 将 `delete-btn` 从字段内部移到 `.field-value` 之后，并给 `.smart-field-wrapper` 增加 `position:relative`，使 `delete-btn` 可绝对定位到右上角（`top: -8px; right: -8px`）。
   - 默认 `display: none`；在 `TemplateManage` 的编辑器容器上增加 `template-editor-mode` class，通过 `.template-editor-mode .smart-field-wrapper:hover .delete-btn` 和 `:focus-within .delete-btn` 控制仅在 TemplateManage 中悬浮/聚焦时显示。
   - `ReportEditor` 的编辑器容器没有 `template-editor-mode`，因此删除按钮不会显示。
3. **类型安全修复**：在 `ReportEditor.tsx` 的 `multi_select` 渲染分支中，增加 `Array.isArray` 检查：
   ```ts
   const rawValue = (reportData as any)[field.key];
   const tags = Array.isArray(rawValue) ? rawValue : (rawValue ? [String(rawValue)] : []);
   ```
   确保无论旧数据是数组、字符串还是空值，都能安全渲染为标签列表。

**D. 后续如何避免问题**
- 任何需要在不同页面显隐不同的 UI 元素，应通过容器级 class 做样式隔离，而不是依赖全局显示/隐藏。
- `contentEditable` 控件的焦点状态必须有明确的视觉反馈（背景/边框/阴影变化），否则用户难以感知当前编辑位置。
- 对从持久化存储读取的数组类型数据，在 React 渲染前务必做 `Array.isArray` 校验，防止历史脏数据导致整页崩溃。

---

## 记录 18：字段悬浮高亮、电子签上传与手术者签名联动

**A. 具体问题**
1. `TemplateManage` 中右侧字段库按钮与编辑器中的字段缺乏视觉关联，用户难以快速定位字段位置。
2. `UserManage` 缺少电子签名上传功能，无法为医生绑定个人签名图。
3. 模板中缺少"手术者签名"字段，报告编辑时无法自动带入医生签名。
4. 签名图片若直接放入 `.field-value` 中，容易撑大行高，影响排版和打印效果。

**B. 产生问题原因**
1. 字段库按钮没有任何与编辑器 DOM 联动的交互反馈机制。
2. 早期设计未考虑医疗文书中的电子签需求，`User` 模型和 `DEFAULT_FORM_FIELDS` 均缺少签名相关定义。
3. 没有针对签名图片设计专门的 CSS 尺寸约束，导致浏览器按原图尺寸渲染，破坏行高。

**C. 解决问题方案**
1. **悬浮高亮**：在 `TemplateManage.tsx` 的字段库按钮上增加 `onMouseEnter` / `onMouseLeave`，直接操作编辑器中对应 `data-bind` 的 `.field-value` 的 `style.boxShadow` 和 `style.backgroundColor`，实现蓝色外发光/背景变浅蓝色的即时高亮反馈。
2. **电子签上传与压缩**：
   - 在 `UserManage.tsx` 中增加 `compressImage(file, maxSize=500)` 工具函数，利用 Canvas 等比例缩放并填充白色背景，输出 JPEG base64（质量 0.8）。
   - 在用户编辑/新增弹窗中增加"电子签名"区块：预览图、上传按钮、清除按钮。
   - 编辑当前登录用户时同步更新 `storage.set('currentUser', ...)`，确保 ReportEditor 能读取最新签名。
3. **手术者签名字段**：
   - `types.ts` 中 `User` 增加 `signature?: string`；`FieldType` 增加 `'signature'`；`DEFAULT_FORM_FIELDS` 追加 `surgeonSignature`（分类"图片"，系统锁定）。
   - `TemplateManage` 插入字段分类增加"图片"，`surgeonSignature` 自动出现在该分类下。
   - `ReportEditor` 的"表单 → 编辑器"同步 `useEffect` 中，对 `fieldKey === 'surgeonSignature'` 做特殊分支：有签名则填充 `<img class="report-signature-img" src="..." />`，无签名则填充文本"【请上传电子签】"。
4. **签名排版优化**：
   - 在 `index.css` 和 `print.ts` 中定义 `.report-signature-img`：
     ```css
     .report-signature-img {
       height: 2.4em;
       width: auto;
       vertical-align: middle;
       display: inline-block;
       margin: -0.3em 0;
     }
     ```
   - 打印媒体查询中同步使用 `!important` 确保打印输出也保持同样尺寸。

**D. 后续如何避免问题**
- 当需要在 React 之外直接操作 DOM 样式实现即时反馈时，优先使用原生事件 + inline style（避免触发组件重渲染导致光标丢失）。
- 任何新增的持久化字段，应在类型定义（TypeScript interface）、默认值（DEFAULT_xxx）、以及所有相关读写逻辑中同步补齐，防止类型不一致。
- 在 `contentEditable` 中插入图片时，务必通过 CSS 对 `height`/`width`/`vertical-align` 做严格约束，避免原图尺寸破坏文本流。
- 涉及打印的样式必须在 iframe 打印模板和 `@media print` 中双端同步，防止打印效果与屏幕预览不一致。

---

## 记录 19：撤销栈修复、字段删除交互优化与签名字段闭环

**A. 具体问题**
1. `TemplateManage` 中通过红色 × 或键盘删除智能字段后，浏览器撤销栈（Undo）失效，点击"撤销"按钮无法恢复。
2. 插入"手术日期"、"手术者签名"等字段后，字段框有时会跳到下一行。
3. Backspace 键无法删除字段；Delete 键会误删字段前面的大段文本（如"手术步骤、术中出现的情况及处理："）。
4. 签名图片没有最大尺寸限制；"手术者签名"字段不在 ReportEditor 表单中显示，无法受控管理签字状态。
5. 点击"完成报告"时缺少对签名状态的确认提示。

**B. 产生问题原因**
1. 删除字段时使用了 `target.remove()` 直接操作 DOM，绕过了浏览器的原生撤销栈（`undo stack`）。
2. 插入的 `smart-field-wrapper` 是 `inline-block` 元素，但其后缺少行内锚点文本节点，浏览器在特定光标位置插入时容易将其挤到新行。
3. `keydown` 拦截逻辑中 `target.remove()` 同样会误删父级块节点（WebKit 在边界处对 `contenteditable="false"` inline 元素的处理缺陷）。
4. `surgeonSignature` 字段原先 `visibleInForm: false`，且签名图片样式仅用 `height: 2.4em` 约束，没有 `max-width/max-height` 的硬限制。
5. 完成报告逻辑中缺少针对签名字段的业务校验。

**C. 解决问题方案**
1. **撤销栈修复**：将点击红 × 删除和键盘 Backspace/Delete 删除全部改为 `Range.selectNode(target)` + `document.execCommand('delete')`。这样浏览器会将删除操作记录到撤销栈中，`execCommand('undo')` 可以正确恢复。
2. **防换行**：在 `insertSmartField` 和 `defaultContent.ts` 的 `smartField()` 生成的 HTML 末尾增加 `&#8203;`（零宽空格），作为稳定的行内锚点，防止字段被浏览器排到新行。
3. **精准键盘删除**：配合 `Range.selectNode` + `execCommand('delete')`，不再直接 `remove()` DOM 节点，彻底避免误删父级 `<p>` 的问题。
4. **签名尺寸与字段管理**：
   - `types.ts` 中将 `surgeonSignature` 改为 `visibleInForm: true, isSystemLocked: false`，使其出现在字段管理和右侧表单中。
   - 新增 `isSigned` 字段（单选：已签字 / 未签字，默认"未签字"）。
   - 签名图片样式改为 `max-width: 120px; max-height: 40px; object-fit: contain;`，并在打印样式和 `print.ts` 中同步。
5. **签名同步逻辑重构**：`ReportEditor` 中 `surgeonSignature` 的渲染由 `isSigned` 控制：
   - `已签字` 且 `currentUser.signature` 存在 → 显示签名图片。
   - `已签字` 但无签名图 → 显示 "【请上传电子签】"。
   - `未签字` → 显示 "【未签字】"。
6. **完成报告签名校验**：`saveReport('completed')` 中，若模板包含 `surgeonSignature`：
   - 未选择"已签字" → `confirm` 弱阻断提示。
   - 已选择"已签字"但无签名图 → `confirm` 弱阻断提示。
   - 用户点击"取消"则中断保存，点击"确定"仍可继续保存。

**D. 后续如何避免问题**
- 在 `contentEditable` 中删除元素时，**优先使用 `Range.selectNode` + `execCommand('delete')`** 而非直接 `remove()`，以确保撤销/重做等原生编辑行为正常工作。
- 插入 `inline-block` 或 `inline-flex` 控件时，可在其后追加 `&#8203;` 零宽空格，为浏览器提供稳定的行内文本锚点，减少排版异常。
- 任何需要从"不可见"改为"可见/可配置"的字段，应在 `DEFAULT_FORM_FIELDS`、`Report 类型`、`reportData 初始值` 三处同步更新，防止表单渲染遗漏。
- 对于图片类嵌入内容，应使用 `max-width`/`max-height` + `object-fit: contain` 做硬约束，避免不同来源图片破坏页面布局。

---

## 记录 20：TemplateManage 自定义 Undo/Redo 与插入字段光标定位修复

**A. 具体问题**
1. `TemplateManage` 中删除智能字段（通过红 × 或 Backspace/Delete）后，点击工具栏的"撤销"按钮无法恢复字段，"重做"也失效。
2. 点击右侧字段库按钮插入字段时，字段经常跳到下一行或文档末尾。

**B. 产生问题原因**
1. 即使将删除逻辑改为 `execCommand('delete')`，浏览器原生的 undo stack 在 `contentEditable` 中结合 React 状态更新时仍然非常脆弱，容易被清空。
2. 点击侧边栏按钮会导致编辑器 `blur`，浏览器内部的光标位置（Selection/Range）丢失；再次 `focus()` 后光标被重置，导致 `insertHTML` 插入位置错误。

**C. 解决问题方案**
1. **自定义 Undo/Redo 栈**：
   - 在 `TemplateManage.tsx` 中引入 `undoStack` 和 `redoStack` 两个 `useRef<string[]>([])`。
   - 实现 `pushHistory()`，在执行任何结构性变更（删除字段、插入字段、插入表格/图片、格式化命令）前将当前 `editorRef.current.innerHTML` 推入 undo 栈并清空 redo 栈。
   - 实现 `handleUndo()` / `handleRedo()`，直接替换工具栏按钮的 `execCmd('undo')` / `execCmd('redo')` 调用。从栈中取出历史 HTML 字符串并赋值给 `editorRef.current.innerHTML`，再调用 `saveTemplateContent()` 同步到 React state 和 `localStorage`。
2. **阻止焦点流失**：
   - 在所有工具栏按钮和字段库插入按钮上增加 `onMouseDown={(e) => e.preventDefault()}`，阻止 mousedown 默认行为导致编辑器失去焦点。
3. **光标位置记忆与恢复**：
   - 利用已有的 `savedRangeRef`，实现 `saveSelection()` 和 `restoreSelection()`。
   - 在编辑器 `<div>` 上绑定 `onBlur={saveSelection}`、`onMouseUp={saveSelection}`、`onKeyUp={saveSelection}`，持续记录光标位置。
   - 在 `insertSmartField` 和 `insertImage` 中，执行 `insertHTML` 前先调用 `restoreSelection()` 恢复光标，确保字段插入到正确的位置。

**D. 后续如何避免问题**
- 对于 `contentEditable` 编辑器中的结构性变更（插入/删除特殊节点），如果原生 undo 不可靠，应尽早实现自定义历史栈（基于 HTML 字符串快照），完全接管撤销/重做逻辑。
- 侧边栏/工具栏按钮与编辑器共存时，**必须**通过 `onMouseDown={e => e.preventDefault()}` 或等价手段阻止焦点流失，这是保证光标位置不丢失的最简单有效方案。
- 插入操作前恢复 `savedRangeRef` 可以作为焦点流失后的兜底保险，两者结合使用效果最佳。

---

## 记录 14：智能字段插入间距修复与 Backspace 防误删

**A. 具体问题**
1. `TemplateManage.tsx` 中使用 `insertSmartField` 插入智能字段后，字段后方会出现一个可见的空格（由 `&nbsp;` 和多行模板字符串中的换行/缩进空白引起）。
2. 在 `contenteditable` 中，光标位于 `<p>` 行首且后紧跟 `.smart-field-wrapper` 时按 Backspace，WebKit 内核会直接删除整段 `<p>` 而不是仅删除字段节点。
3. `defaultContent.ts` 中的 `smartField` 辅助函数同样存在多行缩进导致的模板 HTML 中夹杂空白文本节点问题。

**B. 产生问题原因**
1. `insertSmartField` 的 HTML 字符串使用反引号多行模板，缩进和换行被浏览器解析为额外的文本节点；末尾显式拼接了 `&nbsp;`，导致插入后字段与后续文字之间总有一个不必要的空格。
2. `contenteditable="false"` 的 inline 元素处于行边界时，WebKit 的默认编辑行为会将整个包含该元素的块级父节点一并删除，而不是只删除该不可编辑元素。
3. `defaultContent.ts` 中的 `smartField` 为了可读性也使用了多行缩进模板字面量，导致默认模板里每个 `smartField` 调用前后都引入了额外的空白文本节点。

**C. 解决问题方案**
1. **压缩 HTML 字符串**：将 `insertSmartField` 和 `defaultContent.ts` 的 `smartField` 输出改为单行 HTML，移除所有无意义的换行和缩进，并去掉尾部的 `&nbsp;`。
2. **防止内部折行**：给 `.smart-field-wrapper` 增加 `white-space: nowrap;`（内联样式 + CSS 类双保险），确保标签和输入框不会在行中间被拆开。
3. **拦截 Backspace/Delete**：在 `TemplateManage.tsx` 的编辑器上增加 `keydown` 事件监听（capture 阶段）。当光标位于文本节点起始位置且前一个兄弟节点是 `.smart-field-wrapper` 时按 Backspace，或光标在文本节点末尾且后一个兄弟节点是 `.smart-field-wrapper` 时按 Delete，主动 `preventDefault()` 并手动移除该字段节点，随后同步更新 `localStorage` 中的模板内容。

**D. 后续如何避免问题**
- 在 `contentEditable` 中使用 `document.execCommand('insertHTML', ...)` 插入 HTML 时，**传入的字符串必须是无多余空白的紧凑单行**，否则浏览器会将其中的换行符解析为额外的文本节点，破坏排版和光标行为。
- 对于 `contenteditable="false"` 的内联控件，若放置在块级边界（如 `<p>` 开头/结尾），务必增加键盘事件拦截，防止浏览器默认行为误删父级块。
- 默认模板或任何通过代码生成的 HTML，应避免为了代码可读性而牺牲运行时 DOM 的纯净性；必要时在生成后对字符串进行 `.replace(/\s+/g, ' ').trim()` 处理。


---

## 记录 21：TemplateManage 快捷键 Undo/Redo 与字段插入排版修复

**A. 具体问题**
1. TemplateManage 中删除 smart-field-wrapper 后按键盘 Ctrl+Z 无法撤销，但点击工具栏撤销按钮可以恢复。
2. 当目标段落以 <br> 结尾时，从字段库插入 smart-field-wrapper 会被拆到下一行（<span> 跑到了 <p> 外部）。

**B. 问题产生原因**
1. keydown 事件监听器只拦截了 Backspace/Delete，未拦截 Ctrl+Z/Ctrl+Y，导致浏览器原生 undo 与自定义 undoStack/
edoStack 完全脱节。
2. insertSmartField 使用 document.execCommand('insertHTML')，WebKit/Blink 在块级元素末尾存在 <br> 时，会自动将插入的 inline <span> 修正到块级元素外部，造成排版错位。

**C. 解决问题方法**
1. **快捷键拦截**：在 keydown 监听的最开头增加 Ctrl+Z / Cmd+Z / Ctrl+Shift+Z / Ctrl+Y 的拦截，调用 e.preventDefault() 后路由到 handleUndo() 或 handleRedo()。
2. **精确 Range 插入**：将 insertSmartField 的插入方式从 execCommand('insertHTML') 替换为手动 Range.insertNode()：
   - 
estoreSelection() 恢复光标；
   - 
ange.deleteContents() 清空当前选区；
   - 将 HTML 字符串转为 DocumentFragment；
   - 
ange.insertNode(fragment) 精确插入到 Range 位置；
   - setStartAfter(lastNode) 把光标移动到插入内容末尾。

**D. 经验与教训总结**
- 在 contentEditable 中实现自定义撤销栈时，必须**同时拦截界面按钮和键盘快捷键**的 undo/redo，否则两套历史机制会互相冲突。
- document.execCommand('insertHTML') 对块级元素边界（尤其是 <br> 结尾）的自动修正行为不可控；需要精确插入时，应优先使用 Range.insertNode() 手动操作 DOM。
- 任何对 contentEditable 的 DOM 修改后，都应同步保存内容（saveTemplateContent），确保 localStorage 中的模板数据与编辑器状态一致。


---

## 记录 22：TemplateManage 字段体系升级与双向交互联动

**A. 具体问题**
1. 新增字段时单选/多选分类仍显示"文本"选项，联动逻辑错误。
2. 默认模板中存在大量静态灰色占位文本（术前诊断、术后诊断等），无法与右侧表单双向绑定。
3. 字段管理列表平铺展示，无分组折叠，系统字段选项不可修改。
4. 图片占位符只能通过本地上传填充，无法使用签名图或系统素材。
5. 编辑器中的智能字段与右侧侧边栏完全无联动。

**B. 问题产生原因**
1. `newFieldForm.category` onChange 时未正确过滤 type select 的 options。
2. `DEFAULT_FORM_FIELDS` 缺少术前/术后诊断等临床字段，导致 `defaultContent.ts` 只能写死占位文本。
3. 字段管理 UI 未按 category 分组，也未提供编辑系统字段选项的入口。
4. `ReportEditor.tsx` 中图片占位符点击后直接调用 `input.click()`，缺少多渠道选择机制。
5. `TemplateManage.tsx` 的 `handleEditorClick` 仅处理了删除逻辑，未处理点击高亮/导航。

**C. 解决问题方法**
1. **类型联动修复**：category onChange 时强制设置对应 type（单选→single_select、多选→multi_select、图片→image）；type select 使用条件渲染，只显示当前 category 支持的选项。
2. **扩展默认字段**：在 `types.ts` 追加 `preoperativeDiagnosis`、`postoperativeDiagnosis`、`postOpCondition`、`specimenDescription`、`pathologyCheck`、`frozenPathology`、`hospitalLogo` 等系统字段，全部 `isSystemLocked: true`。
3. **替换模板占位文本**：在 `defaultContent.ts` 中将所有灰色占位文本替换为 `smartField(...)`，Logo 替换为带 `data-bind="hospitalLogo"` 的 `image-placeholder`。
4. **字段管理折叠与编辑**：新增 `expandedCategories` 状态实现折叠面板；新增 `editingFieldKey` 等状态实现点击编辑（系统字段 label 只读、选项可编辑）。
5. **素材库与图片字段**：`FieldType` 扩展 `'image'`；初始化时自动将 Logo 转 Base64 存入 `imageAssets`；`insertSmartField` 对图片类型插入 `image-placeholder`。
6. **图片来源选择弹窗**：`ReportEditor.tsx` 点击图片占位符弹出 Modal，支持本地上传、我的签名、系统素材三选一。
7. **编辑器-侧边栏双向联动**：点击 `smart-field-wrapper` 时读取 `data-bind`，高亮并滚动定位到右侧对应字段，自动展开分组。

**D. 经验与教训总结**
- category→type 的联动应在 state 变更层强制收敛，而不是仅依赖 JSX 条件渲染。
- 升级静态占位文本为字段时，必须同步修改 `DEFAULT_FORM_FIELDS`、`defaultContent.ts` 和 `formFieldsConfig`。
- 图片字段与普通文本字段的 DOM 结构差异大，插入逻辑需要按 type 分支。
- 编辑器与侧边栏联动建议使用 `scrollIntoView` + 临时 CSS 类，避免复杂的状态同步。
- 新增 localStorage key 时应提供合理的默认值或降级处理。


---

## 记录 23：图片占位符体系重构与双端统一

**A. 具体问题**
1. `template-manage` 的"插入字段"中仍存在"图片"分类（手术者签名、医院Logo），用户认为不再需要。
2. 插入图片占位符时无法自定义默认宽高，且使用 `<div>` 导致强制换行。
3. 占位符框太小时"插入/点击放置图片"文字显示不全。
4. 默认模板中签名和 Logo 的结构不统一（一个是 `smartField`，一个是 `div.image-placeholder`）。
5. `template-manage` 点击图片占位符直接调起本地文件选择器，与 `report-editor` 的三选一弹窗行为不一致。

**B. 问题产生原因**
1. `DEFAULT_FORM_FIELDS` 仍包含 `surgeonSignature` 和 `hospitalLogo`。
2. 两端编辑器的 `insertImage()` 使用块级 `<div>` 插入，未提供尺寸 prompt。
3. 占位符提示文本固定为长文本，未根据容器宽度做缩写适配。
4. `TemplateManage` 的 placeholder 点击事件直接调用 `triggerPlaceholderUpload()`，缺少与 `ReportEditor` 一致的弹窗组件。

**C. 解决问题方法**
1. **清理图片字段**：从 `DEFAULT_FORM_FIELDS` 和 `types.ts` 中移除 `surgeonSignature` 和 `hospitalLogo`；在 `TemplateManage.tsx` 的插入字段/字段管理/新增字段表单中彻底移除"图片"分类。
2. **统一默认模板**：在 `defaultContent.ts` 中将 Logo 和签名均替换为 `<span class="image-placeholder" style="display:inline-flex;...">`。
3. **改造 insertImage()**：在 `TemplateManage.tsx` 和 `ReportEditor.tsx` 中，插入前通过 `prompt` 获取最大宽度/高度（px），生成带 `max-width/max-height` 的 `<span>` 行内占位符；提示文字中附加"正文一行文字高度约为 20 像素左右"。
4. **文本自适应**：根据 prompt 输入的宽度决定提示文字：宽度 < 80px 时显示"插入图片"，否则显示"插入/点击放置图片"。
5. **统一弹窗行为**：将 `ReportEditor` 的 `imagePickerOpen` / `imagePickerTarget` / `fillPlaceholderSrc` 逻辑完整移植到 `TemplateManage`；删除旧的 `triggerPlaceholderUpload` 直接上传逻辑；两端点击图片占位符均弹出"本地上传 / 我的签名 / 系统素材"三选一弹窗。
6. **优化填充样式**：`fillPlaceholderSrc` 中给 `<img>` 增加 `max-width:100%; max-height:100%; object-fit:contain;`，避免撑破设置了固定尺寸的占位符。

**D. 经验与教训总结**
- 当从字段体系中彻底移除某一分类时，需要同时清理：`DEFAULT_FORM_FIELDS`、UI 渲染数组、新增表单 options、以及可能残留的分类判断逻辑（如编辑字段时显示 options 输入框的条件）。
- 在 `contentEditable` 中实现"同行插入"必须使用行内元素（`<span>`）并显式设置 `display:inline-flex` + `vertical-align:middle`；块级 `<div>` 即使通过 CSS 改 display 也可能因浏览器 execCommand 修正导致换行。
- 跨页面/跨编辑器的一致交互（如图片选择弹窗）应抽取为可复用逻辑或至少保持代码结构一致，避免用户在不同页面产生认知割裂。
- `prompt` 虽不是最优雅的用户交互，但在工具栏快捷操作中是一种零依赖、快速落地的方案；若后续需要更复杂交互，可再替换为 Modal 组件。