2026-05-04-04-58-36 优化DICOM缓存和三维融合预览

工程分析/实现方案-2026-05-04-04-58-36.md

@@ -0,0 +1,76 @@
+# 实现方案
+
+时间戳：2026-05-04-04-58-36
+
+## 修改目标
+
+修复项目列表按钮重叠；增强逆向工作区当前项目与融合视图；增加 DICOM 缓存和显示模式；重做 3D 模型渲染加载状态，避免 React Three Fiber 引入的 Three.js `Clock` 警告。
+
+## 涉及路径
+
+- `WebSite/server.ts`
+- `WebSite/src/lib/api.ts`
+- `WebSite/src/types.ts`
+- `WebSite/src/components/ProjectLibrary.tsx`
+- `WebSite/src/components/ReverseWorkspace.tsx`
+- `工程分析/测试方案-2026-05-04-04-58-36.md`
+- `工程分析/经验记录.md`
+
+## 技术路线
+
+1. 项目列表布局。
+   - 将收缩按钮从标题区右侧移到侧栏外侧中线位置。
+   - 保留 `+` 在项目列表标题行内，避免重叠。
+2. DICOM 预览缓存与显示模式。
+   - 后端增加内存缓存：按 project、plane、slice、mode 缓存灰度预览。
+   - API 增加 `mode=default|bone|soft|contrast`。
+   - 前端增加显示模式切换，并将 mode 传给 API。
+3. 3D 模型渲染。
+   - 项目库中不再使用 React Three Fiber Canvas。
+   - 后端增加 STL 二进制采样预览 API，避免浏览器一次解析 240MB 原始 STL。
+   - 前端改用原生 Three.js 手动创建 renderer、camera、scene、geometry。
+   - 显示加载进度条；WebGL 不可用时使用二维 canvas 模型预览兜底。
+   - 使用自动包围盒归一化、居中、缩放，确保模型可见。
+4. 逆向工作区。
+   - 拉取当前项目详情。
+   - 顶部显示当前项目名、DICOM/STL 数量和路径。
+   - 融合视图显示 DICOM canvas 背景，并叠加简化 STL/模型轮廓或模型投影效果，表达等比例缩放、中心对齐状态。
+5. 验证与部署。
+   - `npm run lint`
+   - `npm run build`
+   - API smoke test
+   - headless Chrome 冒烟检查
+   - 重启 `tmux` 会话部署到 `4000`。
+
+## 数据流
+
+DICOM：
+
+前端选择 plane/slice/mode -> 后端命中或生成缓存预览 -> 前端 canvas 显示。
+
+3D：
+
+前端读取 STL 采样预览 API -> 后端返回抽样三角面顶点 -> 原生 Three.js 生成材质、居中缩放 -> 渲染；WebGL 不可用时绘制二维投影预览。
+
+逆向融合：
+
+前端按当前项目获取 DICOM 预览和项目信息 -> canvas 绘制影像 -> HTML/SVG/Three 投影层叠加中心对齐模型轮廓。
+
+## 兼容性与回滚方案
+
+- DICOM preview API 兼容旧参数，不传 mode 时默认为 default。
+- 如果原生 Three.js 渲染异常，页面会使用二维 canvas 兜底预览，不影响项目库浏览。
+- 运行态缓存仅在进程内，不写入 Git。
+
+## 预计文件变更
+
+- 修改后端 DICOM preview API。
+- 修改项目库 3D 组件和 DICOM 控件。
+- 修改逆向工作区融合视图。
+- 更新工程分析文档和经验记录。
+
+## 人工审核状态
+
+本次用户明确要求无需人工二次确认。
+
+状态：自动确认，继续执行。