2026-05-20-11-51-05 默认医学数据入库

工程分析/实现方案-2026-05-20-11-51-05.md

@@ -0,0 +1,60 @@
+# 实现方案：默认医学数据资产入库
+
+实现方案文档路径：`工程分析/实现方案-2026-05-20-11-51-05.md`
+
+## 修改目标
+
+将默认项目依赖的 `Head_CT_DICOM/` 和 `Head_CT_ReConstruct/` 纳入 Git/Gitea，使新环境克隆仓库后能够直接加载默认演示项目。
+
+## 涉及路径
+
+- `.gitignore`
+- `.gitattributes`
+- `Head_CT_DICOM/`
+- `Head_CT_ReConstruct/`
+- `工程分析/需求分析-2026-05-20-11-51-05.md`
+- `工程分析/实现方案-2026-05-20-11-51-05.md`
+- `工程分析/测试方案-2026-05-20-11-51-05.md`
+- `工程分析/经验记录.md`
+
+## 技术路线
+
+1. 统计两个默认数据目录的文件数量与体积，记录入测试方案。
+2. 调整 `.gitignore`，移除 `Head_CT_DICOM/` 和 `Head_CT_ReConstruct/` 的忽略规则。
+3. 新增 `.gitattributes`，将 `*.dcm` 和 `*.stl` 作为二进制文件处理。
+4. 使用 `git add` 精确暂存默认数据目录、配置文件和本次工程分析文档。
+5. 检查暂存内容，确认不包含软著材料、历史删除状态或无关文件。
+6. 提交并推送到 Gitea。
+7. 构建并重新部署项目，验证默认项目接口返回 DICOM/STL 数量正常。
+
+## 执行步骤
+
+- 读取 `工程分析/经验记录.md` 后执行最终修改。
+- 使用 `du`、`find`、`git status` 检查数据目录状态。
+- 修改 `.gitignore` 与 `.gitattributes`。
+- 运行 `npm run build`。
+- 验证 `/api/health`、首页和 `/api/projects/head-ct-demo`。
+- 精确提交并推送。
+- 重启 `tmux` 会话 `revoxelseg-dicom`。
+
+## 兼容性与回滚方案
+
+- 目录名保持不变，后端默认项目扫描逻辑无需修改。
+- 回滚时可恢复 `.gitignore` 忽略规则，并从 Git 历史中移除或停止跟踪默认数据；但历史大文件仍会存在于旧提交中。
+- 若 Gitea push 因大小限制失败，应保留本地 commit 并记录失败原因，再考虑 Git LFS、压缩包发布或对象存储。
+
+## 预计文件变更
+
+- 修改 `.gitignore`。
+- 新增 `.gitattributes`。
+- 新增 300 个 DICOM 文件。
+- 新增 9 个 STL 文件。
+- 新增本次工程分析三份文档。
+- 追加 `工程分析/经验记录.md`。
+
+## 提交与部署策略
+
+- commit message 包含 `2026-05-20-11-51-05` 和“默认医学数据入库”描述。
+- 推送默认远端 `origin/main`。
+- 软著相关目录 `新撰写软著文档/` 不暂存、不提交。
+- 部署优先使用 `tmux` 会话 `revoxelseg-dicom` 与 `npm run serve -- --host 0.0.0.0 --port 4000`。

工程分析/测试方案-2026-05-20-11-51-05.md

@@ -0,0 +1,61 @@
+# 测试方案：默认 DICOM/STL 数据入库验证
+
+测试方案文档路径：`工程分析/测试方案-2026-05-20-11-51-05.md`
+
+## 静态检查
+
+- 使用 `du -sh Head_CT_DICOM Head_CT_ReConstruct` 记录目录体积。
+- 使用 `find Head_CT_DICOM -type f | wc -l` 确认 DICOM 文件数。
+- 使用 `find Head_CT_ReConstruct -type f | wc -l` 确认 STL 文件数。
+- 使用 `git check-ignore` 确认两个目录不再被 `.gitignore` 忽略。
+- 使用 `git diff --check` 确认文本配置和文档无空白错误。
+- 使用 `git diff --cached --name-status` 检查暂存内容不包含软著材料和无关历史删除。
+
+## 构建检查
+
+- 在 `WebSite/` 执行 `npm run build`，确认项目仍可构建。
+
+## 关键业务场景验证
+
+- 重新部署后访问 `http://127.0.0.1:4000/api/projects/head-ct-demo`。
+- 验证默认项目返回：
+  - `dicomCount = 300`
+  - `modelCount = 9`
+  - `dicomPath = Head_CT_DICOM`
+  - `modelPath = Head_CT_ReConstruct`
+- 验证 `/api/health` 正常。
+- 验证首页返回 200。
+
+## 医学影像数据相关边界验证
+
+- DICOM/STL 文件作为二进制资产纳入 Git，避免文本 diff。
+- 不修改文件名和目录结构，避免破坏后端默认扫描。
+- 记录新增数据资产约 395M，提示 clone/pull 时间增加。
+
+## 部署验证
+
+- 使用 `tmux` 会话 `revoxelseg-dicom` 重新启动服务。
+- 查看 `tmux capture-pane` 确认服务监听 `http://0.0.0.0:4000/`。
+
+## Git/Gitea 备份验证
+
+- commit message 包含 `2026-05-20-11-51-05`。
+- 推送到 Gitea 成功后记录 commit。
+- 若 push 失败，记录远端错误和本地 commit 状态。
+
+## 风险与回归关注点
+
+- 本次会显著增大仓库体积。
+- 不把 `新撰写软著文档/`、`参考软著构建模板/`、`head-ct-demo-pose-data.json` 混入提交。
+- 不处理已有历史 `工程分析/*2026-05-04/05-08*` 删除状态。
+
+## 实际验证记录
+
+- 数据体积：`Head_CT_DICOM` 约 154M，`Head_CT_ReConstruct` 约 241M，合计约 395M。
+- 文件数量：`Head_CT_DICOM` 为 300 个文件，`Head_CT_ReConstruct` 为 9 个文件。
+- 忽略规则：移除 `.gitignore` 中 `Head_CT_DICOM/` 与 `Head_CT_ReConstruct/` 忽略规则后，`git check-ignore` 对示例 DICOM/STL 无命中。
+- 二进制属性：新增 `.gitattributes`，配置 `*.dcm binary` 与 `*.stl binary`。
+- 构建检查：`npm run build` 通过；仍有 Vite 单 chunk 大小提示，不影响本次数据入库。
+- 空白检查：`git diff --check` 通过。
+- 服务检查：`http://127.0.0.1:4000/api/health` 返回正常，首页返回 `HTTP/1.1 200 OK`。
+- 默认项目接口：`/api/projects/head-ct-demo` 返回 `dicomCount=300`、`modelCount=9`、`dicomPath=Head_CT_DICOM`、`modelPath=Head_CT_ReConstruct`、`stlFiles=9`。

工程分析/经验记录.md

@@ -1189,3 +1189,21 @@ C. 解决问题方案
 D. 后续如何避免问题
 
 凡是为含三维场景的页面生成截图或录屏，都应优先验证截图不是空白，并检查浏览器控制台是否有 WebGL 创建失败信息。自动化截图应准备软件渲染兜底；Word 交付前必须用 `unzip -l` 检查 `word/media/` 是否包含预期图片。
+
+## 2026-05-20-11-51-05 默认医学数据资产入库需要明确体积与二进制属性
+
+A. 具体问题
+
+默认项目依赖 `Head_CT_DICOM/` 和 `Head_CT_ReConstruct/`，但两个目录原先被 `.gitignore` 排除。新环境只克隆代码时无法直接加载默认演示项目，需要额外复制医学数据资产。
+
+B. 产生问题原因
+
+早期工作流把 DICOM/STL 视为不进入普通文档备份的大型医学源数据，避免无意提交；但当前用户明确要求把默认项目数据作为仓库交付资产，以支持新环境开箱构建。
+
+C. 解决问题方案
+
+移除 `.gitignore` 中对 `Head_CT_DICOM/` 和 `Head_CT_ReConstruct/` 的忽略规则，新增 `.gitattributes` 将 `*.dcm` 和 `*.stl` 标记为 binary。提交前统计数据体积和文件数，验证默认项目接口仍返回 DICOM 300 张、STL 9 个构件。
+
+D. 后续如何避免问题
+
+默认演示数据和运行态输出要分开管理：默认项目资产可以入库，但导出文件、状态文件和用户临时数据仍应保持忽略。新增大体积医学数据前必须记录体积、文件数、脱敏/授权假设和远端推送结果；若体积继续增长，应评估 Git LFS 或独立数据包发布。

工程分析/需求分析-2026-05-20-11-51-05.md

@@ -0,0 +1,53 @@
+# 需求分析：默认 DICOM/STL 数据纳入 Gitea
+
+开始时间：`2026-05-20-11-51-05`
+
+## 原始需求摘要
+
+用户要求将 `Head_CT_DICOM/` 与 `Head_CT_ReConstruct/` 也加入 Gitea，因为它们是系统默认项目数据，新环境构建和演示时需要直接可用。
+
+## 业务目标
+
+- 默认演示项目的数据资产随代码仓库一起交付。
+- 新环境克隆仓库后，无需额外复制 DICOM 和 STL 目录即可加载默认项目。
+- 保持当前默认项目 `head-ct-demo` 的 DICOM 300 张、STL 9 个构件完整可用。
+
+## 输入与输出
+
+输入：
+
+- `Head_CT_DICOM/`：默认 DICOM 序列，当前 300 个文件，约 154M。
+- `Head_CT_ReConstruct/`：默认 STL 重建模型，当前 9 个文件，约 241M。
+- `.gitignore` 当前明确忽略上述两个目录。
+
+输出：
+
+- 调整 `.gitignore`，不再忽略默认医学数据资产。
+- 新增 `.gitattributes`，将 `.dcm` 与 `.stl` 标记为二进制文件。
+- 将 `Head_CT_DICOM/` 与 `Head_CT_ReConstruct/` 纳入 Git/Gitea。
+
+## 影响范围
+
+- 仓库体积会明显增加，新增约 395M 默认数据资产。
+- 新环境部署时默认项目数据可直接扫描并载入。
+- 不修改前后端业务代码。
+- 不纳入 `新撰写软著文档/`、参考模板、位姿素材等软著相关本地材料。
+
+## 关键约束
+
+- 仅提交本次相关数据资产、ignore/attributes 配置和工程分析文档。
+- 避免提交历史工程分析文档删除状态和无关未跟踪文件。
+- DICOM/STL 为二进制资产，应避免 Git 文本 diff。
+- 推送前需确认 Gitea 能接受较大体积提交。
+
+## 风险点
+
+- 仓库体积增加后，首次 clone/pull 时间会变长。
+- 若远端 Gitea 对单文件或仓库包大小有限制，push 可能失败。
+- DICOM 数据属于医学影像数据，后续正式生产数据入库前必须确认脱敏和授权；本次按用户说明作为默认演示项目纳入。
+
+## 默认假设
+
+- 用户已明确要求将两个默认数据目录加入 Gitea，本次不改用外部对象存储或 Git LFS。
+- 当前默认演示数据是允许进入内部 Gitea 的项目资产。
+- 保留现有目录名和文件名，避免影响后端默认扫描逻辑。