# 工程整体分析

更新时间：2026-05-03-18-27-21

## 项目定位

Head_CT_Morph 是一个头颈部 CT 仰头形变工具与网页工作站，包含 Python DICOM 处理能力、桌面辅助入口，以及 React/Vite 网页工作站。

## 主要结构

- `web_backend.py`：本地 Python API 后端，负责影像库、预览、任务、文件下载，以及调用形变和视频生成逻辑。
- `head_extension_app.py`：四状态 DICOM 形变核心逻辑与桌面界面。
- `generate_head_extension_video.py`：仰头角度变化 MP4 生成逻辑。
- `video_generator_app.py`：视频生成桌面界面包装。
- `WebSite/`：React 19 + Vite 前端工作站。
- `requirements.txt`：Python 依赖，包括 DICOM、图像、医学影像处理与视频输出相关库。
- `WebSite/package.json`：前端依赖与运行脚本。

## 运行方式

后端：

```bash
cd WebSite
npm run backend
```

前端：

```bash
cd WebSite
npm run dev
```

前端默认端口为 `3005`，后端默认监听 `0.0.0.0:8787`。

## 构建与检查

前端类型检查：

```bash
cd WebSite
npm run lint
```

前端构建：

```bash
cd WebSite
npm run build
```

Python 当前未发现统一测试脚本。涉及 Python 修改时，应至少执行对应模块的语法检查或针对性手工验证。

## 数据与产物

- DICOM 原始数据、上传库、运行结果、视频、ZIP、`node_modules` 等应避免作为常规修改提交。
- 网页上传数据通常写入 `web_library/`。
- 处理结果通常写入 `web_results/`。

## 修改风险

- 医学影像处理链路对路径、DICOM 排序、体素间距、输出格式较敏感。
- 后端接口同时承担文件读写、任务状态和下载路径暴露，修改时需关注路径安全与异常处理。
- 前端工作站面向实际操作流程，修改 UI 时需保持工作流连续性，不应引入说明性落地页替代真实工具界面。
- 形变和视频生成可能耗时较长，测试时要区分轻量类型检查、构建检查和完整样本数据验证。

## 长期工作流入口

项目修改工作流写入仓库根目录 `AGENTS.md`。后续每次项目修改需求都应先生成需求分析、实现方案、测试方案，并在实现方案与测试方案通过用户二次审核后再修改业务代码。