# 实现方案

时间戳：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 控件。
- 修改逆向工作区融合视图。
- 更新工程分析文档和经验记录。

## 人工审核状态

本次用户明确要求无需人工二次确认。

状态：自动确认，继续执行。