86 lines
5.0 KiB
Markdown
86 lines
5.0 KiB
Markdown
# 工程整体分析
|
||
|
||
更新时间：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。
|