2026-05-04-03-50-07 完善项目库可视化和项目管理

工程分析/实现方案-2026-05-04-03-50-07.md

@@ -0,0 +1,91 @@
+# 实现方案
+
+时间戳：2026-05-04-03-50-07
+
+## 修改目标
+
+修复概况统计、图表警告和模块高亮问题；完善项目库真实 DICOM/STL/分割结果展示；增加项目创建和重命名能力；补齐 README 构建方案并重新部署。
+
+## 涉及路径
+
+- `WebSite/server.ts`
+- `WebSite/src/lib/api.ts`
+- `WebSite/src/types.ts`
+- `WebSite/src/components/Overview.tsx`
+- `WebSite/src/components/ProjectLibrary.tsx`
+- `WebSite/README.md`
+- `README.md`
+- `工程分析/测试方案-2026-05-04-03-50-07.md`
+- `工程分析/经验记录.md`
+
+## 技术路线
+
+1. 后端项目状态增强。
+   - 保留默认项目，同时允许新增用户创建项目。
+   - 新增 `POST /api/projects` 创建项目。
+   - 新增 `PATCH /api/projects/:projectId` 修改项目名称。
+2. 后端 DICOM 预览。
+   - 新增 `GET /api/projects/:projectId/dicom-preview?slice=0`。
+   - 读取当前 DICOM 文件，解析 Rows、Columns、Pixel Data、Window Center/Width、Rescale Slope/Intercept。
+   - 返回 `width`、`height`、`pixels` base64 灰度数据和 slice 元数据。
+3. 后端 STL 文件服务。
+   - 新增 `GET /api/projects/:projectId/models/:fileName`。
+   - 只允许读取项目对应 STL 列表中的文件，避免任意路径读取。
+4. 前端项目库。
+   - DICOM 视图使用 canvas 绘制后端返回灰度像素。
+   - 3D 模型视图使用 Three.js `STLLoader` 加载真实 STL。
+   - 新增 `分割结果` tab，展示 mask 预览、标签图例和 NII/NII.GZ 下载。
+   - 项目列表顶部增加创建按钮和名称输入。
+   - 项目卡右侧增加编辑图标，可重命名。
+   - 移除首个 STL 模块默认蓝色高亮，所有模块同等样式。
+5. 概况页。
+   - 已处理项目改为“已导出 Mask 项目”，避免项目总数 1 时已处理 1 的误导。
+   - 趋势数据改为平稳小范围变化。
+   - Recharts 容器增加 `min-w-0`、固定高度和加载态，避免宽高 -1 警告。
+6. README。
+   - 补充 Node 构建运行方案。
+   - 说明当前无需 Python/conda；真实体素化阶段再引入 Python 环境建议。
+7. 验证与部署。
+   - `npm run lint`
+   - `npm run build`
+   - API smoke test
+   - 重新部署 `tmux` 会话到 `4000`。
+
+## 数据流
+
+DICOM 预览：
+
+前端切片滑块 -> `/api/projects/:id/dicom-preview?slice=n` -> 后端解析 DICOM 像素 -> 前端 canvas 绘制。
+
+STL 预览：
+
+前端选择 STL 模块 -> `/api/projects/:id/models/:fileName` -> `STLLoader` 加载几何体 -> Three.js 渲染。
+
+分割结果：
+
+前端 `分割结果` tab -> 展示 mask 预览 -> 调用已有 `/api/projects/:id/export-mask` 导出 `nii` 或 `nii.gz`。
+
+项目管理：
+
+创建/重命名 -> 后端写入 `state.json` -> 项目列表刷新。
+
+## 兼容性与回滚方案
+
+- DICOM/STL 原始文件仍不提交 Git。
+- 若 DICOM 解析失败，前端显示错误态，不影响其他页面。
+- 若 STL 加载失败，前端显示模型加载失败提示，不影响 DICOM 和分割结果。
+- 回滚时恢复 `server.ts` 和项目库组件即可回到上一版前后端演示状态。
+
+## 预计文件变更
+
+- 修改后端 API。
+- 修改项目库和概况页。
+- 修改 API 类型和封装。
+- 修改 README。
+- 更新工程分析文档和经验记录。
+
+## 人工审核状态
+
+本次用户明确要求无需人工二次确认。
+
+状态：自动确认，继续执行。