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

工程分析/经验记录.md

@@ -181,3 +181,93 @@ C. 解决问题方案
 D. 后续如何避免问题
 
 多项目并行部署时，除了业务端口外，也检查 Vite HMR 端口；发现冲突时为每个项目分配独立 HMR 端口。
+
+## 2026-05-04-03-50-07 概况统计语义误导
+
+A. 具体问题
+
+项目总数只有 1 时，“已处理项目总数”也显示 1，容易让用户误解为系统已经完成真实处理。
+
+B. 产生问题原因
+
+旧统计把 `status === completed` 直接当作已处理项目，而默认演示项目为了表示数据可用被标记为 `completed`。
+
+C. 解决问题方案
+
+将概况卡片语义改为“已导出 Mask 项目”，后端按 `exportedMaskCount > 0` 统计；默认项目初始为 0，只有实际触发 mask 导出后才计入。
+
+D. 后续如何避免问题
+
+统计卡片必须反映明确业务事件，不要把演示数据可用状态和处理完成状态混在一起。
+
+## 2026-05-04-03-50-07 DICOM 预览解析
+
+A. 具体问题
+
+项目库 DICOM 影像页看不到真实影像，只显示占位图形。
+
+B. 产生问题原因
+
+前端没有读取 DICOM 像素数据，后端也没有提供切片预览 API。
+
+C. 解决问题方案
+
+新增 `GET /api/projects/:projectId/dicom-preview`，后端解析当前 Little Endian DICOM 的 Rows、Columns、Window、Rescale 和 Pixel Data，返回 base64 灰度像素，前端用 canvas 绘制真实切片。
+
+D. 后续如何避免问题
+
+医学影像可视化应优先验证真实像素是否进入浏览器。后续扩展更多 DICOM 传输语法时，应把解析器替换为成熟 DICOM 库或 Python 预处理服务。
+
+## 2026-05-04-03-50-07 STL 模型真实渲染
+
+A. 具体问题
+
+项目库 3D 模型页显示的是占位立方体，不是 `Head_CT_ReConstruct` 中的真实 STL。
+
+B. 产生问题原因
+
+前端没有 STLLoader，后端也没有安全暴露 STL 文件。
+
+C. 解决问题方案
+
+新增 `GET /api/projects/:projectId/models/:fileName`，仅允许读取项目 STL 列表中的文件；前端使用 Three.js `STLLoader`、`Bounds` 和 `Center` 加载并自动居中显示模型。
+
+D. 后续如何避免问题
+
+三维模型视图必须加载真实模型文件，不能长期使用占位几何体；后端文件服务要限制文件名和项目白名单，避免任意路径读取。
+
+## 2026-05-04-03-50-07 Recharts 容器尺寸警告
+
+A. 具体问题
+
+控制台出现 Recharts 警告：图表宽高为 `-1`，需要检查容器尺寸。
+
+B. 产生问题原因
+
+图表在布局尚未稳定时渲染，`ResponsiveContainer` 从父容器拿到异常宽高。
+
+C. 解决问题方案
+
+为图表外层设置 `min-w-0`、固定高度和 `min-h`，并在 chartData 存在后再渲染 `ResponsiveContainer`，高度使用明确数值 `300`。
+
+D. 后续如何避免问题
+
+使用 Recharts 时保证父容器有稳定尺寸；在异步数据未到达前不要提前渲染响应式图表。
+
+## 2026-05-04-03-50-07 Python 环境引入边界
+
+A. 具体问题
+
+用户提出如果需要 Python 可新建 conda 环境，但本次需求可以在现有 Node/React/Three.js 技术栈中完成。
+
+B. 产生问题原因
+
+DICOM/STL/Mask 功能既可以由前端演示链路实现，也可能进入 Python 医学影像算法链路，需要判断当前阶段是否真的需要 Python。
+
+C. 解决问题方案
+
+本次不创建 conda 环境，避免增加不必要复杂度；README 中说明当前构建方式和后续真实体素化阶段的 conda 环境建议。
+
+D. 后续如何避免问题
+
+只有当需要真实 DICOM 空间解析、STL 体素填充、NIfTI 精确写入或批处理算法时，再引入 Python/conda，并把环境文件纳入项目文档。