# 实现方案 - 2026-05-08-01-19-42

## 修改目标

1. 修复模型库大缩放时构件层级不可见或不可滚动的问题。
2. 更换逆向工作区侧栏图标，避免与模型库重复。
3. 优化逆向工作区模型位姿控制：拆分重置按钮、增加 ±90° 旋转、位姿重命名、单击最低刻度、长按连续移动。
4. 为融合视角增加 DICOM 体数据缓存与五个预存点位。
5. 在融合视角显示 DICOM 边界框、模型边界框，并以 DICOM 中心作为模型旋转中心。
6. 增加 DICOM 透明度三档控制。
7. 增加基于 DICOM 帧的模型切分预览，显示切割面。

## 涉及路径

- `WebSite/src/components/Sidebar.tsx`
- `WebSite/src/components/ProjectLibrary.tsx`
- `WebSite/src/components/ReverseWorkspace.tsx`
- `WebSite/src/lib/api.ts`
- `WebSite/src/types.ts`
- `WebSite/server.ts`
- `工程分析/经验记录.md`

## 技术路线

### 模型库滚动

- 调整项目库 3D 模型页右侧栏为 `min-h-0` + 内部滚动结构。
- 构件层级列表占用剩余高度，标题和控制区固定，防止浏览器放大后构件列表被挤出。

### 侧栏图标

- 侧栏中模型库继续使用 `Box`，逆向工作区改用 `Workflow` 或 `ScanLine` 类图标，保证含义和视觉不同。

### 位姿控制

- 在逆向工作区可视化工具栏中替换 `重置默认位姿` 为：
  - `重置旋转位姿`
  - `重置平移缩放位姿`
- 旋转 X/Y/Z 增加 `-90°` 和 `+90°` 按钮。
- 平移和缩放增加正负最小步进按钮。
- 单击按钮只移动一个最低刻度；鼠标或触摸长按时启动定时器连续移动。
- 保存位姿列表中允许重命名非默认位姿，默认位姿保持不可改名。

### DICOM 缓存与预存点

- 前端维护 `fusionVolumeCacheRef`，以 `projectId/mode/end` 作为 key 缓存融合体数据。
- DICOM 切片范围显示五个点位按钮，分别映射 20%、40%、60%、80%、100%。
- 点击预存点位时优先从缓存读取；缓存未命中则请求接口并写入缓存。
- 增加“预存五点”按钮，后台并发预取五个点位。

### 边界框与旋转中心

- FusionThreeView 增加 DICOM BoxHelper/LineSegments 边界和模型边界。
- 模型 STL 顶点以自身中心归一化后，整体 group 的 pivot 固定在 DICOM 体中心。
- 旋转、缩放围绕 DICOM 中心进行，平移作为模型相对 DICOM 中心的偏移。

### DICOM 透明度

- 新增 `dicomOpacityLevel`，提供低/中/高三档。
- 传入 FusionThreeView，控制 DICOM 体素切片和切片纹理材质透明度。

### 模型切分

- 新增切割开关、切割帧滑条和切割面显示。
- Three.js 中使用 DICOM 切片帧在 Z 方向的相对位置作为切割平面。
- 通过 local clipping plane 对模型材质裁剪，并显示半透明切割面。

## 数据流或交互流程

1. 进入逆向工作区后读取项目与 `moduleStyles`。
2. Fusion 视角按当前切片范围加载体数据，先查前端缓存，未命中再请求后端。
3. 用户点击五个点位或预存按钮，前端将对应 `end` 的 DICOM volume 写入缓存。
4. 用户调整模型位姿，模型围绕 DICOM 中心旋转缩放，并实时更新边界框。
5. 用户启用模型切分并选择 DICOM 帧，Three.js 使用对应切割平面裁剪模型并显示切割面。

## 兼容性与回滚方案

- 缓存仅存在浏览器内存中，不改变后端数据结构。
- 新增控制项都保留默认值，旧项目数据可直接使用。
- 若切割平面对部分浏览器性能影响较大，可关闭切割功能回到原始渲染。
- 回滚本次 commit 即可恢复。

## 预计文件变更

- `Sidebar.tsx`：调整逆向工作区图标。
- `ProjectLibrary.tsx`：修复右侧构件层级滚动布局。
- `ReverseWorkspace.tsx`：增加缓存、预存点、位姿控制、边界框、透明度和切割功能。
- `api.ts/types.ts/server.ts`：如需支持缓存辅助或类型扩展则同步调整。

## 人工审核状态

用户已声明本次不需要二次人工确认，按默认执行确认规则直接执行。

## 执行记录

- 已将左侧逆向工作区图标从 `Box` 改为 `Workflow`，与模型库图标区分。
- 已将模型库 3D 模型右侧栏改为整栏滚动结构，解决浏览器放大后构件层级下方内容不可见的问题。
- 已在逆向工作区模型位姿中增加：
  - `重置旋转位姿`
  - `重置平移缩放位姿`
  - X/Y/Z 的 ±90° 快捷旋转
  - 旋转/平移/缩放的最低刻度单击步进与长按连续步进
  - 非默认位姿重命名输入
- 已在融合视角中增加 DICOM 透明度低/中/高三档。
- 已在融合视角中增加 DICOM 边界框和模型边界框显示开关。
- 已将模型旋转中心改为以 DICOM 体中心为 pivot，模型自身偏移放入子节点，避免旋转时围绕模型偏移点运动。
- 已增加 DICOM 切片范围五个点位和 `预存五点` 功能，前端使用内存 Map 缓存融合体数据。
- 已增加模型切分开关、切割帧滑条、橙色切割面显示，并通过 Three.js clipping plane 裁剪模型。