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

AGENTS.md

@@ -0,0 +1,62 @@
+# 项目修改工作流
+
+本仓库后续所有项目修改相关需求，都必须遵循以下流程。若用户临时提出的要求与本文件冲突，应先向用户说明冲突点并等待确认。
+
+## 强制时间戳
+
+- 每次开始处理项目修改需求前，先记录开始时间，格式为 `YYYY-MM-DD-HH-MM-SS`。
+- 同一轮需求内创建的 `需求分析`、`实现方案`、`测试方案` 文件必须使用同一个开始时间戳。
+
+## 工程分析目录
+
+- 每次执行前先阅读或创建 `工程分析/`。
+- 优先阅读 `工程分析/工程整体分析.md`，了解项目结构、运行方式和风险边界。
+- 在最终执行修改前，必须阅读 `工程分析/经验记录.md`，避免重复犯错。
+
+## 需求分析
+
+- 每次用户提出项目修改需求后，先整理需求并写入：
+  `工程分析/需求分析-YYYY-MM-DD-HH-MM-SS.md`
+- 文档至少包含：原始需求、目标、影响范围、约束、风险点、待确认事项。
+
+## 实现方案
+
+- 每次进入代码修改前，先将实现方案写入：
+  `工程分析/实现方案-YYYY-MM-DD-HH-MM-SS.md`
+- 文档至少包含：方案路径、涉及文件、执行步骤、回滚思路、风险控制。
+- 实现方案写完后必须等待用户二次人工审核确认；未经确认不得修改业务代码。
+
+## 测试方案
+
+- 每次执行代码修改前，先将测试方案写入：
+  `工程分析/测试方案-YYYY-MM-DD-HH-MM-SS.md`
+- 文档至少包含：测试范围、测试命令、手工验证点、验收标准、无法测试的风险。
+- 测试方案写完后必须等待用户二次人工审核确认；未经确认不得修改业务代码。
+
+## 执行与经验记录
+
+- 用户确认实现方案和测试方案后，方可执行完整修改。
+- 执行过程中遇到的关键问题及解决方案，必须追加到 `工程分析/经验记录.md`。
+- 经验记录统一使用四段式：
+  - A. 具体问题
+  - B. 产生问题原因
+  - C. 解决问题方案
+  - D. 后续如何避免问题
+
+## Gitea 备份
+
+- 每次最终执行后，必须将本次文档变更提交到 Gitea。
+- commit 信息格式：
+  `YYYY-MM-DD-HH-MM-SS 简要描述`
+- 远程仓库：
+  `http://admin@192.168.31.5:5002/admin/Head_CT_Morph.git`
+- 不得把 Gitea 密码、令牌或其他凭据写入仓库文件、提交信息、日志文档或可追踪脚本。
+- 完成 commit 后，必须提醒用户文档备份 commit 已完成。
+
+## 重新部署
+
+- 每次最终执行项目修改后，重新部署或重启本项目。
+- 当前项目通常需要：
+  - Python 后端：`cd WebSite && npm run backend`
+  - 前端开发服务：`cd WebSite && npm run dev`
+- 若部署方式发生变化，应同步更新 `工程分析/工程整体分析.md`。

工程分析/实现方案-2026-05-03-18-27-21.md

@@ -0,0 +1,45 @@
+# 实现方案
+
+开始时间：2026-05-03-18-27-21
+
+## 本次方案路径
+
+`工程分析/实现方案-2026-05-03-18-27-21.md`
+
+## 实现目标
+
+建立长期有效的项目修改工作流，并将工作流说明放在后续维护者容易读取的位置。
+
+## 涉及文件
+
+- `AGENTS.md`
+- `工程分析/工程整体分析.md`
+- `工程分析/经验记录.md`
+- `工程分析/需求分析-2026-05-03-18-27-21.md`
+- `工程分析/实现方案-2026-05-03-18-27-21.md`
+- `工程分析/测试方案-2026-05-03-18-27-21.md`
+
+## 执行步骤
+
+1. 创建 `工程分析/` 目录。
+2. 编写 `AGENTS.md`，将用户指定的流程固化为仓库级工作流。
+3. 编写 `工程分析/工程整体分析.md`，记录当前项目结构、运行方式、测试入口和风险边界。
+4. 编写本次需求分析、实现方案和测试方案文档。
+5. 初始化 `工程分析/经验记录.md`，记录建立工作流的原因、方案和后续避免方式。
+6. 执行文档检查、前端类型检查和构建检查。
+7. 将文档变更提交并推送到 Gitea。
+8. 重新部署本项目的后端和前端开发服务。
+
+## 回滚思路
+
+如该工作流需要撤销，可删除本次新增的 `AGENTS.md` 和 `工程分析/` 中本次新增文档，并提交一次回滚 commit。若只需调整流程，应优先修改 `AGENTS.md` 和对应工程分析文档，而不是删除知识库。
+
+## 风险控制
+
+- 本次不修改业务代码，降低运行行为变化风险。
+- Gitea 密码不写入仓库，不写入提交信息。
+- 重新部署前先执行前端检查，确保基础构建链路可用。
+
+## 人工审核状态
+
+本次为建立工作流本身，按用户明确指令直接执行。后续业务代码修改必须等待用户对实现方案进行二次人工审核确认。

工程分析/工程整体分析.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`。后续每次项目修改需求都应先生成需求分析、实现方案、测试方案，并在实现方案与测试方案通过用户二次审核后再修改业务代码。

工程分析/测试方案-2026-05-03-18-27-21.md

@@ -0,0 +1,55 @@
+# 测试方案
+
+开始时间：2026-05-03-18-27-21
+
+## 本次方案路径
+
+`工程分析/测试方案-2026-05-03-18-27-21.md`
+
+## 测试范围
+
+- 文档是否创建在正确路径。
+- 工作流是否覆盖用户要求的 0 至 7 步。
+- 前端类型检查是否通过。
+- 前端构建是否通过。
+- 项目是否能重新启动后端和前端开发服务。
+
+## 测试命令
+
+```bash
+find 工程分析 -maxdepth 1 -type f | sort
+```
+
+```bash
+cd WebSite
+npm run lint
+```
+
+```bash
+cd WebSite
+npm run build
+```
+
+## 手工验证点
+
+- `AGENTS.md` 是否明确后续项目修改需求必须先生成需求分析、实现方案和测试方案。
+- `AGENTS.md` 是否明确实现方案和测试方案必须经过用户二次审核确认。
+- `工程分析/经验记录.md` 是否采用 A/B/C/D 四段式。
+- Gitea 凭据是否未写入仓库文件。
+
+## 验收标准
+
+- 所有本次计划新增文档存在。
+- 文档内容覆盖用户要求。
+- `npm run lint` 通过。
+- `npm run build` 通过。
+- 重新部署后可访问前端开发服务，后端进程正常监听。
+
+## 无法测试或残余风险
+
+- 本次不运行完整 DICOM 形变任务，避免产生大型运行结果；医学影像处理链路需在未来涉及相关代码修改时单独验证。
+- Gitea 推送依赖远程服务和凭据可用性，如远程不可达需记录失败原因并提醒用户。
+
+## 人工审核状态
+
+本次为建立工作流本身，按用户明确指令直接执行。后续业务代码修改必须等待用户对测试方案进行二次人工审核确认。

工程分析/经验记录.md

@@ -0,0 +1,21 @@
+# 经验记录
+
+本文件作为项目统一知识库。每次最终执行项目修改前必须阅读；每次执行完成后，如遇到关键问题或形成可复用经验，必须按以下四段式追加记录。
+
+## 2026-05-03-18-27-21 建立项目修改工作流
+
+A. 具体问题
+
+项目此前缺少统一的修改前分析、人工审核、测试确认、经验沉淀、Gitea 备份和重新部署流程，后续需求容易直接进入代码修改，导致风险不可追踪。
+
+B. 产生问题原因
+
+仓库中已有 README 和运行说明，但没有面向后续代码编纂工作的强制流程文件，也没有统一的 `工程分析/` 知识库目录。
+
+C. 解决问题方案
+
+新增仓库根目录 `AGENTS.md`，明确后续项目修改需求必须记录开始时间、生成需求分析、实现方案、测试方案，并在实现方案和测试方案通过用户二次审核后再修改业务代码。新增 `工程分析/工程整体分析.md`、本经验记录，以及本次需求、实现、测试方案文档。
+
+D. 后续如何避免问题
+
+后续每次项目修改开始时先阅读 `AGENTS.md`、`工程分析/工程整体分析.md` 和 `工程分析/经验记录.md`，严格使用同一开始时间戳创建三类分析文档，并在用户确认实现方案和测试方案后再执行代码改动。

工程分析/需求分析-2026-05-03-18-27-21.md

@@ -0,0 +1,43 @@
+# 需求分析
+
+开始时间：2026-05-03-18-27-21
+
+## 原始需求
+
+用户要求新建一个完整的代码编纂工作流。后续只要提出项目修改相关需求，都需要按照该工作流执行：
+
+- 每次执行前记录开始时间。
+- 阅读或创建 `工程分析/` 文件夹，并维护工程整体分析。
+- 每次需求写入 `工程分析/需求分析-时间戳.md`。
+- 每次实现方案写入 `工程分析/实现方案-时间戳.md`，写完后必须经过用户二次人工审核确认。
+- 每次测试方案写入 `工程分析/测试方案-时间戳.md`，写完后必须经过用户二次人工审核确认。
+- 最终执行前阅读 `工程分析/经验记录.md`，执行后以四段式记录关键问题及解决方案。
+- 最终执行后使用 Gitea 备份 commit，提交信息包含时间戳和简要描述，并提醒用户备份完成。
+- 重新部署本项目。
+
+## 目标
+
+建立仓库内可持续遵守的修改工作流，让后续项目修改具备需求记录、方案审查、测试审查、经验沉淀、文档备份和重新部署闭环。
+
+## 影响范围
+
+- 新增仓库根目录 `AGENTS.md`，作为后续 Codex/工程协作的优先工作流入口。
+- 新增并维护 `工程分析/` 目录。
+- 不修改本次业务代码。
+- 不把 Gitea 密码写入仓库文件。
+
+## 约束
+
+- 文档文件使用本次开始时间戳 `2026-05-03-18-27-21`。
+- Gitea 凭据只能用于备份操作，不得持久化到仓库。
+- 后续涉及业务代码修改时，必须等待用户审核确认实现方案和测试方案。
+
+## 风险点
+
+- 若未来执行者未阅读 `AGENTS.md`，可能绕过工作流。
+- 若把凭据写入文档或提交信息，会造成安全风险。
+- 若部署方式变化但未更新工程整体分析，后续重新部署可能失败。
+
+## 待确认事项
+
+本次按用户指令直接建立工作流；后续任何业务代码修改都需要先等待用户确认实现方案和测试方案。