2026-05-03-18-27-21 建立项目修改工作流

工程分析/工程整体分析.md

@@ -0,0 +1,70 @@
+# 工程整体分析
+
+更新时间：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`。后续每次项目修改需求都应先生成需求分析、实现方案、测试方案，并在实现方案与测试方案通过用户二次审核后再修改业务代码。