# 实现方案 - 2026-05-04-05-41-22

## 修改目标

在不直接加载全部原始 STL 的前提下，提高 3D 模型预览的实体感，并加入整体位姿控制；改进 DICOM 长按切片时的连续图像反馈；精简逆向工作区重复标题与项目描述。

## 涉及路径

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

## 技术路线

### 1. 3D 模型实体化程度

- 在项目库 3D 模型页增加“实体化程度”控制，建议分为：
  - `预览`：维持较低三角面抽样，优先速度。
  - `标准`：提高抽样数量，呈现连续表面。
  - `精细`：进一步提高抽样数量，但仍保留上限防止卡顿。
- 将当前固定 `/preview?limit=6000` 改为根据实体化程度动态请求，例如 `6000 / 16000 / 36000`。
- Three.js 渲染继续使用 `MeshStandardMaterial`，但新增：
  - `flatShading: false`
  - 更强的环境光、主光和边缘光。
  - 可选整体白色实体显示模式，让模型更接近用户参考图。
- 保留每个 STL 构件的颜色和透明度控制，新增“整体白色实体”开关时临时覆盖颜色为白/灰，不破坏原配置。

### 2. 3D 模型位姿控制

- 在 3D 模型左侧画布上方或右侧面板增加整体位姿控制：
  - 旋转 X/Y/Z 滑块，范围 `-180° ~ 180°`。
  - 平移 X/Y/Z 微调，范围建议 `-2 ~ 2`。
  - 缩放滑块，范围建议 `0.5 ~ 2`。
  - 重置按钮。
- 将自动旋转改为可开关；当用户调整位姿时，自动旋转默认关闭，避免控制冲突。
- 将位姿状态传入 `NativeStlViewer`，渲染循环中应用到 group。

### 3. DICOM 长按连续图像变化

- 当前 `startSliceStep` 只是连续改变 `sliceIndex`，图像依赖 API 响应更新。为增强“动起来”的感觉：
  - 将步进间隔保持在 `90~120ms`，同时在请求期间显示轻量切片过渡效果。
  - 增加 `latestPreviewRequestRef` 或请求序列号，确保旧请求返回时不会覆盖新切片。
  - 在 `sliceIndex` 变化时，立即更新右下角切片文字和 canvas 容器的轻微淡入/亮度变化。
  - 若接口响应较慢，保留上一帧图像并叠加“正在切换”状态，避免画面停滞误解。

### 4. 逆向工作区信息精简

- 删除 `ReverseWorkspace` 页面内 `h2` 标题“逆向工作区”，保留全局 header 的标题。
- 删除页面内副标题中的上方“当前项目：xxx”文本。
- 保留下方标签行：
  - `当前项目：头部 CT 模型逆向体素化演示`
  - `DICOM 300`
  - `STL 9`
- 将标签字号从 `text-[11px]` 提升为 `text-sm` 或 `text-[13px]`，内边距加大，提高可读性。

## 数据流或交互流程

1. 用户进入项目库 3D 模型页。
2. 前端根据实体化程度选择 STL preview limit 请求后端抽样数据。
3. Three.js 将各 STL 抽样三角面生成实体 mesh，按当前实体化、颜色、透明度、白色实体模式、整体位姿状态渲染。
4. 用户拖动位姿控制滑块，前端立即更新 group 的 rotation / position / scale。
5. 用户在 DICOM 页长按切片按钮，前端连续改变 `sliceIndex`，后端返回切片预览，前端按最新请求序号绘制最新帧。
6. 用户进入逆向工作区，只看到全局 header 的“逆向工作区”和加大后的当前项目标签行。

## 兼容性与回滚方案

- 实体化程度默认使用“标准”，若性能不佳可切回“预览”。
- WebGL 不可用时继续使用二维投影兜底，实体化和位姿控制主要作用于 WebGL 路径。
- 若提高抽样上限导致性能问题，可只回滚实体化程度 limit 参数，不影响项目列表、DICOM 和导出功能。
- 逆向工作区文案调整为纯 UI 变更，可直接回滚组件 JSX。

## 预计文件变更

- `ProjectLibrary.tsx`：新增 3D 渲染控制状态、实体化程度、位姿控制 UI、DICOM 请求序号和切片过渡反馈。
- `server.ts`：可能提高 STL preview 的安全上限。
- `ReverseWorkspace.tsx`：删除重复标题/副标题，调整标签字号。
- `经验记录.md`：执行后追加本次经验。

## 人工审核状态

用户已回复“确认方案”，按已确认方案执行项目业务代码修改。