工程整体分析

更新时间：2026-05-19-22-59-07

项目定位

本项目是“基于模型逆向体素化及 DICOM 分割标注系统”的前后端一体化演示工程。核心目标是读取 Head_CT_DICOM/ 中的 DICOM 序列和 Head_CT_ReConstruct/ 中的 STL 重建模型，在浏览器中完成 DICOM 切片预览、STL 模型预览、影像与模型三维融合观察、构件样式配置，并提供 NIfTI Mask 演示导出能力。

当前系统仍以演示闭环为主，真实医学级 STL 到 DICOM 空间体素化算法尚未接入。后续接入真实算法时，应保留现有 API 和前端工作流，并替换后端 Mask 生成逻辑或接入独立算法服务。

当前目录结构

README.md：项目目标、构建运行和部署入口说明。
WebSite/：前后端一体服务目录，包含 Vite React 前端与 Express 后端。
WebSite/server.ts：Express API、Vite 中间件、DICOM/STL 解析预览、NIfTI 演示导出、运行态状态存储。
WebSite/src/：React 页面、组件、类型和 API 封装。
WebSite/src/components/Login.tsx：登录页，默认账号 admin、密码 123456。
WebSite/src/components/Sidebar.tsx：主导航，包含总体概况、项目库、逆向工作区、系统管理工作区。
WebSite/src/components/Overview.tsx：项目、DICOM、STL、Mask 导出统计概览。
WebSite/src/components/ProjectLibrary.tsx：项目库、DICOM 切片预览、STL 预览、构件层级样式、Mask 下载入口。
WebSite/src/components/ReverseWorkspace.tsx：逆向工作区，提供 DICOM/STL 三维融合、模型位姿、切片范围和 STL 切面展示。
WebSite/src/components/UserManagement.tsx：系统管理与演示环境重置。
Head_CT_DICOM/：默认 DICOM 序列目录，不作为普通文档备份重点。
Head_CT_ReConstruct/：默认 STL 重建模型目录，不作为普通文档备份重点。
工程分析/：工程整体分析、代码编纂工作流、需求分析、实现方案、测试方案和经验记录。

技术栈

Node.js 18+ 与 npm。
React 19、TypeScript、Vite 6。
Express 4 与 Vite 中间件，开发和 API 统一由 npm run serve 启动。
Tailwind CSS 4。
Three.js、React Three Fiber、Drei，用于 STL 和融合视图。
Motion/Framer Motion、Recharts、Lucide React。
Node 内置 fs/path/zlib 负责状态文件、DICOM/STL 文件读取、tar.gz 与 NIfTI gzip 演示导出。

后端能力

WebSite/server.ts 当前提供：

/api/health 健康检查。
/api/session、/api/login、/api/logout：共享登录状态。
/api/users：用户列表。
/api/projects 及项目增删改查。
/api/projects/:projectId/module-styles：构件显示、颜色、透明度、Mask ID 的项目级持久化。
/api/projects/:projectId/dicom-preview：轴向、矢状面、冠状面 DICOM 预览。
/api/projects/:projectId/dicom-fusion-volume：三维融合所需的 DICOM 体纹理抽样。
/api/projects/:projectId/dicom-archive：默认 DICOM 序列 tar.gz 下载。
/api/projects/:projectId/dicom-info：DICOM 关键元数据、spacing 与物理尺寸。
/api/projects/:projectId/models/:fileName 与 /preview：STL 文件与抽样三角面预览。
/api/overview：概况统计。
/api/demo/reset：恢复默认演示环境。
/api/projects/:projectId/export-mask：生成 .nii 或 .nii.gz 演示分割 Mask。

运行态与数据

WebSite/data/state.json：共享登录、项目、用户和构件样式状态。
WebSite/exports/：Mask 导出文件。
WebSite/dist/：生产构建产物。
默认项目 ID 为 head-ct-demo，由后端扫描 Head_CT_DICOM/ 和 Head_CT_ReConstruct/ 生成。
DICOM/STL 数据和运行态输出通常不应混入文档备份提交。

已知脚本

在 WebSite/ 下执行：

npm ci：安装依赖。
npm run lint：执行 tsc --noEmit 类型检查。
npm run build：Vite 生产构建。
npm run dev：仅启动 Vite 开发服务器，默认端口 3000。
npm run serve -- --host 0.0.0.0 --port 4000：启动 Express + Vite 一体服务，是当前优先部署方式。

部署约定

当前 README 指向访问地址 http://192.168.3.11:4000/。
历史经验记录显示本项目长期使用 tmux 会话 revoxelseg-dicom 托管服务，避免普通后台进程被回收。
重新部署前先检查端口和已有 tmux 会话；部署后用 /api/health 和页面 HTTP 响应验证。

修改风险重点

DICOM 与 STL 的空间基准不能随显示范围变化而变化，显示范围和物理坐标基准要分开处理。
没有真实体素化或真实语义分割结果时，不应伪造 Mask 图像。
构件样式是跨页面、跨浏览器共享状态，新增字段必须检查初始化、服务端归一化、前端更新和 fallback。
UI 截图或页面文字相关需求应先用可见文案全局定位真实源码。
文档备份提交必须避免把无关的运行态产物、大型医学数据或既有未确认删除混入 commit。

5.0 KiB Raw Permalink Blame History Unescape Escape