# 实现方案

时间戳：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。
- 更新工程分析文档和经验记录。

## 人工审核状态

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

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