2026-05-04-03-21-40 增加前后端协同和NIfTI导出

工程分析/经验记录.md

@@ -109,3 +109,75 @@ C. 解决问题方案
 D. 后续如何避免问题
 
 每次调整部署端口前先检查端口占用和现有 `tmux` 会话；部署后同时验证 `127.0.0.1` 与目标内网 IP，并把实际访问地址写入测试方案执行结果。
+
+## 2026-05-04-03-21-40 从纯前端演示升级为前后端协调系统
+
+A. 具体问题
+
+原系统登录、项目列表、用户列表、出厂重置和导出都是前端静态假数据，不同浏览器之间无法共享状态。
+
+B. 产生问题原因
+
+项目初始形态是 Vite/React 前端演示，没有后端 API、共享状态存储和统一部署入口。
+
+C. 解决问题方案
+
+新增 Express 后端 `server.ts`，用同一 `4000` 端口服务 API 和前端页面。后端通过 `WebSite/data/state.json` 维护演示状态，前端通过 `/api/session` 轮询同步登录状态，并将项目、用户、概况、重置和导出功能全部接入 API。
+
+D. 后续如何避免问题
+
+新增跨浏览器共享功能时，默认先判断状态是否必须由后端维护；涉及多浏览器一致性的功能不要放在组件静态数组或浏览器本地状态中。
+
+## 2026-05-04-03-21-40 默认医学数据项目载入
+
+A. 具体问题
+
+项目列表需要默认载入 `Head_CT_DICOM` 和 `Head_CT_ReConstruct`，恢复演示环境出厂设置后也必须恢复这两个默认数据目录。
+
+B. 产生问题原因
+
+旧项目列表使用硬编码医疗项目示例，和当前仓库中的 DICOM/STL 数据资产没有建立关系。
+
+C. 解决问题方案
+
+后端启动和读取状态时扫描 `Head_CT_DICOM` 的 `.dcm` 数量与 `Head_CT_ReConstruct` 的 `.stl` 文件列表，生成默认项目 `head-ct-demo`。`POST /api/demo/reset` 使用同一逻辑重建默认项目。
+
+D. 后续如何避免问题
+
+演示数据入口统一放在后端默认项目构建函数中，避免多个页面分别硬编码 DICOM/STL 路径或数量。
+
+## 2026-05-04-03-21-40 NIfTI 导出闭环
+
+A. 具体问题
+
+逆向工作区需要最终生成 `nii` 或 `nii.gz` 格式的分割 mask，而旧界面只有导出按钮，没有后端文件生成能力。
+
+B. 产生问题原因
+
+项目尚未实现真实 STL 到 DICOM 空间的体素化算法，也没有文件导出 API。
+
+C. 解决问题方案
+
+新增 `POST /api/projects/:projectId/export-mask`，后端生成 NIfTI-1 单文件 mask，并按请求输出 `.nii` 或 `.nii.gz`。`.nii.gz` 使用 Node `zlib.gzipSync` 压缩，并通过 `Content-Disposition` 触发下载。
+
+D. 后续如何避免问题
+
+导出类功能需要先定义后端接口、文件格式和校验命令。后续实现真实体素化时，可替换当前演示 mask 生成函数，但保留 API 和下载流程。
+
+## 2026-05-04-03-21-40 Vite 中间件 HMR 端口冲突
+
+A. 具体问题
+
+Express + Vite 中间件启动时，默认 HMR WebSocket 端口 `24678` 被其他服务占用，日志出现端口冲突。
+
+B. 产生问题原因
+
+同一机器同时运行多个 Vite 服务，默认 HMR 端口可能重复。
+
+C. 解决问题方案
+
+在 `createViteServer` 中指定 `server.hmr.port = 24679`，使本项目后端服务使用独立 HMR 端口。
+
+D. 后续如何避免问题
+
+多项目并行部署时，除了业务端口外，也检查 Vite HMR 端口；发现冲突时为每个项目分配独立 HMR 端口。