2026-05-19-22-59-07 建立代码编纂工作流
This commit is contained in:
102
工程分析/工程整体分析.md
102
工程分析/工程整体分析.md
@@ -1,57 +1,85 @@
|
||||
# 工程整体分析
|
||||
|
||||
更新时间：2026-05-04-02-38-48
|
||||
更新时间：2026-05-19-22-59-07
|
||||
|
||||
## 项目定位
|
||||
|
||||
本项目计划建设为“基于模型逆向体素化及 DICOM 分割标注系统”。
|
||||
本项目是“基于模型逆向体素化及 DICOM 分割标注系统”的前后端一体化演示工程。核心目标是读取 `Head_CT_DICOM/` 中的 DICOM 序列和 `Head_CT_ReConstruct/` 中的 STL 重建模型，在浏览器中完成 DICOM 切片预览、STL 模型预览、影像与模型三维融合观察、构件样式配置，并提供 NIfTI Mask 演示导出能力。
|
||||
|
||||
目标能力：
|
||||
|
||||
- 输入头部 DICOM 序列。
|
||||
- 对 DICOM 进行三维重建或读取已有重建模型。
|
||||
- 从重建后的 STL 模型反向生成体素级分割 Mask。
|
||||
- 面向医学影像分割标注流程提供可视化、管理和结果导出能力。
|
||||
当前系统仍以演示闭环为主，真实医学级 STL 到 DICOM 空间体素化算法尚未接入。后续接入真实算法时，应保留现有 API 和前端工作流，并替换后端 Mask 生成逻辑或接入独立算法服务。
|
||||
|
||||
## 当前目录结构
|
||||
|
||||
- `WebSite/`：前端应用主体，基于 Vite、React、TypeScript。
|
||||
- `WebSite/src/`：主要页面和组件代码。
|
||||
- `Head_CT_DICOM/`：头部 CT DICOM 文件目录。
|
||||
- `Head_CT_ReConstruct/`：已重建 STL 文件目录，包括头部、头颅、气管、肿瘤等结构。
|
||||
- `工程分析/`：工程分析、需求分析、实现方案、测试方案和经验记录目录。
|
||||
- `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 重建模型目录，不作为普通文档备份重点。
|
||||
- `工程分析/`：工程整体分析、代码编纂工作流、需求分析、实现方案、测试方案和经验记录。
|
||||
|
||||
## 前端技术栈
|
||||
## 技术栈
|
||||
|
||||
- React 19
|
||||
- TypeScript
|
||||
- Vite 6
|
||||
- Tailwind CSS 4
|
||||
- Three.js、React Three Fiber、Drei
|
||||
- Framer Motion / Motion
|
||||
- Recharts
|
||||
- Lucide React
|
||||
- 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/package.json` 中已有脚本：
|
||||
在 `WebSite/` 下执行：
|
||||
|
||||
- `npm run dev`：启动 Vite 开发服务器，端口 3000，监听 `0.0.0.0`。
|
||||
- `npm run build`：生产构建。
|
||||
- `npm run preview`：预览构建结果。
|
||||
- `npm run clean`：删除 `dist`。
|
||||
- `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 一体服务，是当前优先部署方式。
|
||||
|
||||
## 数据资产
|
||||
## 部署约定
|
||||
|
||||
- DICOM 数据位于 `Head_CT_DICOM/`。
|
||||
- STL 重建模型位于 `Head_CT_ReConstruct/`。
|
||||
- 医学数据和模型文件体积可能较大，Git 备份时应谨慎，默认不将原始影像与重建模型纳入普通文档备份提交。
|
||||
- 当前 README 指向访问地址 `http://192.168.3.11:4000/`。
|
||||
- 历史经验记录显示本项目长期使用 `tmux` 会话 `revoxelseg-dicom` 托管服务，避免普通后台进程被回收。
|
||||
- 重新部署前先检查端口和已有 `tmux` 会话；部署后用 `/api/health` 和页面 HTTP 响应验证。
|
||||
|
||||
## 后续重点
|
||||
## 修改风险重点
|
||||
|
||||
- 明确 DICOM 读取、排序、空间信息解析方式。
|
||||
- 明确 STL 到体素 Mask 的坐标对齐策略。
|
||||
- 明确 Mask 输出格式，例如 NIfTI、NRRD、DICOM SEG、PNG 序列或项目自定义格式。
|
||||
- 明确前端是否只做可视化，还是需要增加后端处理服务。
|
||||
- 对医学影像处理流程建立可复现测试样例和数据校验。
|
||||
- DICOM 与 STL 的空间基准不能随显示范围变化而变化，显示范围和物理坐标基准要分开处理。
|
||||
- 没有真实体素化或真实语义分割结果时，不应伪造 Mask 图像。
|
||||
- 构件样式是跨页面、跨浏览器共享状态，新增字段必须检查初始化、服务端归一化、前端更新和 fallback。
|
||||
- UI 截图或页面文字相关需求应先用可见文案全局定位真实源码。
|
||||
- 文档备份提交必须避免把无关的运行态产物、大型医学数据或既有未确认删除混入 commit。
|
||||
|
||||
Reference in New Issue
Block a user