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 控件。
+- 修改逆向工作区融合视图。
+- 更新工程分析文档和经验记录。
+
+## 人工审核状态
+
+本次用户明确要求无需人工二次确认。
+
+状态：自动确认，继续执行。

工程分析/测试方案-2026-05-04-04-58-36.md

@@ -0,0 +1,78 @@
+# 测试方案
+
+时间戳：2026-05-04-04-58-36
+
+## 测试目标
+
+验证项目列表按钮不重叠、DICOM 三方向和显示模式可用、3D 模型有加载进度并可见、逆向工作区显示当前项目和融合视图，以及控制台不再出现 `THREE.Clock` 警告。
+
+## 静态检查
+
+- 检查项目列表标题区 `+` 与收缩按钮布局。
+- 检查 DICOM preview API 是否支持 `mode`。
+- 检查项目库是否使用原生 Three.js renderer 并显示加载进度。
+- 检查逆向工作区是否显示当前项目。
+
+## 构建与类型检查
+
+```bash
+cd WebSite
+npm run lint
+npm run build
+```
+
+预期：
+
+- TypeScript 检查通过。
+- Vite 构建通过。
+
+## API 验证
+
+```bash
+curl -s 'http://127.0.0.1:4000/api/projects/head-ct-demo/dicom-preview?plane=axial&slice=0&mode=default'
+curl -s 'http://127.0.0.1:4000/api/projects/head-ct-demo/dicom-preview?plane=sagittal&slice=128&mode=bone'
+curl -s 'http://127.0.0.1:4000/api/projects/head-ct-demo/dicom-preview?plane=coronal&slice=128&mode=contrast'
+curl -s 'http://127.0.0.1:4000/api/projects/head-ct-demo/models/头部.stl/preview?limit=2000'
+```
+
+预期：
+
+- DICOM 均返回 `width`、`height`、`pixels`、`mode`。
+- STL 预览返回 `triangleCount`、`sampledTriangles`、`vertices`。
+
+## 页面验证
+
+- 项目列表标题区按钮不重叠。
+- DICOM 视图可切换多种显示模式。
+- 矢状面/冠状面滑动有图像变化。
+- 3D 视图显示加载进度条，加载后模型可见。
+- 逆向工作区显示当前项目，融合视图显示 DICOM 与模型中心对齐叠加效果。
+
+## 控制台验证
+
+- headless Chrome 打开页面后不捕获 `THREE.Clock`。
+- 不捕获 `Uncaught`、`Error`。
+
+## 实际执行结果
+
+执行时间：2026-05-04
+
+- `npm run lint`：通过。
+- `npm run build`：通过，仅保留 Vite chunk size 提示。
+- DICOM API：
+  - axial default：`512x512 150/300 WW=360 WL=60`
+  - sagittal bone：`300x512 128/512 WW=2000 WL=500`
+  - coronal contrast：`300x512 256/512 WW=180 WL=80`
+  - axial soft：`512x512 150/300 WW=400 WL=40`
+- STL 预览 API：`头部.stl 2571248 2000 18000`。
+- Headless Chrome 自动化：
+  - 项目库进入成功。
+  - 3D 模型页进入成功，模型加载/二维兜底状态可见。
+  - 逆向工作区进入成功，当前项目与融合说明可见。
+  - `THREE.Clock`、`non-passive`、`Uncaught` 捕获数为 0。
+
+## 人工审核状态
+
+本次用户明确要求无需人工二次确认。
+
+状态：自动确认，继续执行。

工程分析/经验记录.md

@@ -325,3 +325,75 @@ C. 解决问题方案
 D. 后续如何避免问题
 
 列表页面应减少常驻表单噪声；破坏性操作必须二次确认；轻量编辑可采用失焦保存，但需要避免空名称提交。
+
+## 2026-05-04-04-58-36 项目列表按钮布局
+
+A. 具体问题
+
+项目列表标题旁的 `+` 创建按钮和侧栏收缩按钮靠得太近，视觉上发生重叠。
+
+B. 产生问题原因
+
+两个操作都放在项目列表标题区右侧，且侧栏宽度固定，未给低频收缩操作独立位置。
+
+C. 解决问题方案
+
+保留 `+` 在标题区，收缩按钮移动到项目列表侧栏中线外侧，并调整容器为 `overflow-visible`，避免按钮被卡片裁剪。
+
+D. 后续如何避免问题
+
+同一区域的高频操作和布局控制应分区放置；绝对定位按钮如果超出容器，要同步检查父容器裁剪策略。
+
+## 2026-05-04-04-58-36 DICOM 三方向缓存与显示模式
+
+A. 具体问题
+
+矢状面和冠状面切换后图像变化慢或不明显，且 DICOM 只能用单一窗宽窗位显示。
+
+B. 产生问题原因
+
+每次重建非横断面都要重新读取 DICOM 序列，前后端没有把显示模式作为预览参数，也没有复用已解析的体数据。
+
+C. 解决问题方案
+
+后端按显示模式缓存 DICOM 体数据和预览结果，API 增加 `mode=default|bone|soft|contrast`；前端切换方向时重置到对应方向中间层，并提供显示模式分段按钮。
+
+D. 后续如何避免问题
+
+DICOM 多平面重建应优先设计缓存键和窗宽窗位参数；后续接入真实医学影像库时继续保留 plane、slice、mode 的稳定 API 契约。
+
+## 2026-05-04-04-58-36 STL 大文件预览
+
+A. 具体问题
+
+3D 模型页容易空白，直接加载 9 个原始 STL 总量约 240MB，浏览器解析慢且缺少可靠进度反馈。
+
+B. 产生问题原因
+
+前端承担了原始 STL 解析和渲染的全部工作，大体积二进制模型会阻塞交互并放大 WebGL 环境差异。
+
+C. 解决问题方案
+
+后端新增 STL 二进制采样预览 API，只返回抽样三角面顶点；前端用原生 Three.js 按采样顶点生成 BufferGeometry，并显示加载进度。WebGL 不可用时改用二维 canvas 投影预览兜底。
+
+D. 后续如何避免问题
+
+大模型浏览应区分“预览网格”和“原始精度文件”；列表/项目库优先加载轻量预览，进入精修或导出阶段再读取完整 STL。
+
+## 2026-05-04-04-58-36 逆向工作区项目上下文与融合视图
+
+A. 具体问题
+
+逆向工作区没有明确显示当前项目，融合视图没有展示 DICOM 与 STL 归一化中心对齐的效果。
+
+B. 产生问题原因
+
+工作区初版更多是流程面板，缺少从项目库传入项目后继续呈现项目上下文和影像/模型叠加结果的状态。
+
+C. 解决问题方案
+
+工作区进入后读取当前项目详情，顶部显示项目名、DICOM 数量、STL 数量和路径；融合视图加载 DICOM 软组织窗切片，并叠加中心对齐的模型轮廓、十字参考线和切片滑块。
+
+D. 后续如何避免问题
+
+跨页面工作流必须在目标页面重新显示当前操作对象；医学影像配准类视图至少应具备影像层、模型层、对齐标识和当前切片控制。

工程分析/需求分析-2026-05-04-04-58-36.md

@@ -0,0 +1,61 @@
+# 需求分析
+
+时间戳：2026-05-04-04-58-36
+
+## 原始需求摘要
+
+用户要求严格使用代码编纂工作流处理本次修改，并在开始时确认工作流整体流程；本次需求分析、实现方案、测试方案和执行修改均不需要人工二次确认。
+
+具体需求：
+
+1. 项目列表旁边的 `+` 和向内收缩按钮重叠。
+2. 逆向工作区需要显示当前项目；影像与模型融合视角应显示 DICOM 与 STL 等比例拉伸到同种形状、中心对齐后的效果。
+3. 项目列表中矢状面和冠状面看起来不动；应在最早创建/载入项目时把图像处理并预存；同时 DICOM 应支持多种显示模式。
+4. 3D 模型页面为空；如果正在加载，应显示加载进度条；如果当前方法不可行，可调用 Python 现成包。
+5. 控制台出现 `THREE.Clock: This module has been deprecated. Please use THREE.Timer instead.` 和 OrbitControls 非 passive wheel 事件警告。
+
+## 业务目标
+
+- 优化项目库左侧标题区布局，避免操作按钮重叠。
+- 让逆向工作区明确显示当前项目，并提供直观的 DICOM/STL 融合对齐预览。
+- 提升 DICOM 三方向浏览性能和可用性，支持缓存和显示模式。
+- 确保 3D 模型预览可见，并提供清晰的加载状态。
+- 尽量消除由 React Three Fiber / Drei 引入的 Three.js 弃用警告。
+
+## 输入与输出
+
+输入：
+
+- 当前项目 ID。
+- 默认 DICOM 序列与 STL 文件。
+- 用户选择 DICOM 平面、切片与显示模式。
+- 用户调整 STL 显示颜色、透明度和可见性。
+
+输出：
+
+- 项目列表标题区不重叠。
+- 逆向工作区顶部和内容区显示当前项目。
+- 融合视图显示 DICOM 背景和 STL 归一化叠加效果。
+- DICOM 三方向预览来自后端缓存，支持窗宽窗位、骨窗、软组织、高对比模式。
+- 3D 模型显示加载进度，模型加载完成后可见。
+- 控制台不再出现 `THREE.Clock` 警告。
+
+## 影响范围
+
+- `WebSite/server.ts`
+- `WebSite/src/lib/api.ts`
+- `WebSite/src/types.ts`
+- `WebSite/src/components/ProjectLibrary.tsx`
+- `WebSite/src/components/ReverseWorkspace.tsx`
+- `工程分析/经验记录.md`
+
+## 风险点
+
+- DICOM 三方向缓存会增加运行态内存和首次请求计算量。
+- 用原生 Three.js 替换 React Three Fiber 可减少依赖警告，但需要手动管理 renderer/camera/geometry 生命周期。
+- 当前融合视图仍是演示级对齐，不等同真实医学配准矩阵。
+- Python 本次暂不引入，因为 Node/Three.js 能完成本次显示和缓存目标；后续真实体素化再引入更合理。
+
+## 待确认问题
+
+- 本次用户已明确无需二次确认，直接执行。