2026-05-20-11-34-57 完善软著说明书截图与代码汇总

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

@@ -0,0 +1,68 @@
+# 实现方案：软著说明书图文化与代码汇总扩容
+
+实现方案文档路径：`工程分析/实现方案-2026-05-20-11-34-57.md`
+
+## 修改目标
+
+将软著说明书从初稿扩展为更完整的图文说明书，插入当前系统真实截图；将代码汇总 Markdown 扩展至至少 1600 行，同时保留软著材料不进入 Gitea 的约束。
+
+## 涉及路径
+
+- `新撰写软著文档/1. 软著说明书.md`
+- `新撰写软著文档/1. 软著说明书.docx`
+- `新撰写软著文档/3. 代码汇总.md`
+- `新撰写软著文档/3. 代码汇总.docx`
+- `新撰写软著文档/images/`
+- `新撰写软著文档/功能验证与素材清单.md`
+- `工程分析/需求分析-2026-05-20-11-34-57.md`
+- `工程分析/实现方案-2026-05-20-11-34-57.md`
+- `工程分析/测试方案-2026-05-20-11-34-57.md`
+- `工程分析/经验记录.md`
+
+## 技术路线
+
+1. 阅读 `※撰写Agent.md` 和现有软著初稿，确认说明书、截图、Word、代码汇总要求。
+2. 使用当前部署服务打开系统页面，通过自动化截图生成登录页、概况页、项目库、DICOM 查看、逆向工作区、系统管理等图片。
+3. 重写并扩展软著说明书 Markdown，将图片以 `![](images/xx.png)` 形式插入对应章节。
+4. 从 `WebSite/src` 和 `WebSite/server.ts` 中抽取核心代码，生成至少 1600 行的 `3. 代码汇总.md`。
+5. 使用 `python-docx` 生成或覆盖说明书和代码汇总 Word，保证图片嵌入、代码文本可编辑。
+6. 使用 `unzip -t`、`wc -l`、图片引用检查验证交付物。
+7. 本次仅将工程分析文档与经验记录提交 Gitea，不提交 `新撰写软著文档/`。
+
+## 执行步骤
+
+- 检查本地服务与截图工具可用性。
+- 生成截图到 `新撰写软著文档/images/`。
+- 扩写 `1. 软著说明书.md`。
+- 扩充 `3. 代码汇总.md` 至不少于 1600 行。
+- 重新生成 `1. 软著说明书.docx` 和 `3. 代码汇总.docx`。
+- 更新素材清单。
+- 运行文档检查和必要的项目构建/健康检查。
+- 精确暂存本次工程分析文档和经验记录，提交并推送。
+
+## 兼容性与回滚方案
+
+- 软著材料位于本地输出目录，不影响应用运行。
+- 若自动化截图失败，可保留已有文档并记录失败原因；但目标仍是完成真实截图插入。
+- 若 Word 生成失败，保留 Markdown 和图片作为可恢复源文件。
+
+## 预计文件变更
+
+本地软著材料：
+
+- 更新说明书 Markdown/Word。
+- 更新代码汇总 Markdown/Word。
+- 新增截图图片。
+- 更新素材清单。
+
+版本库备份：
+
+- 新增本次工程分析三份文档。
+- 追加 `工程分析/经验记录.md`。
+
+## 提交与部署策略
+
+- 不暂存 `新撰写软著文档/`。
+- 不暂存 `参考软著构建模板/`、`※撰写Agent.md`、`head-ct-demo-pose-data.json`。
+- commit message 包含 `2026-05-20-11-34-57` 和简要描述。
+- 推送 Gitea 后执行或确认当前服务部署健康。

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

@@ -0,0 +1,63 @@
+# 测试方案：软著说明书截图与代码汇总行数检查
+
+测试方案文档路径：`工程分析/测试方案-2026-05-20-11-34-57.md`
+
+## 静态检查
+
+- 使用 `wc -l` 检查 `新撰写软著文档/3. 代码汇总.md` 行数不少于 1600。
+- 检查 `新撰写软著文档/1. 软著说明书.md` 中图片引用均指向实际存在文件。
+- 检查说明书文字不出现明显开发黑话，如接口、路由、payload、state 等。
+- 检查 `git status`，确认软著目录未暂存。
+
+## 构建检查
+
+- 如本次未修改代码，仍运行 `npm run build` 确认当前项目可正常构建。
+
+## 关键业务场景验证
+
+- 截图覆盖登录、首页概况、项目库、DICOM 查看、逆向工作区、构件与位姿配置、逆向分割映射、系统管理等主要界面。
+- 说明书章节覆盖账号创建/登录、核心管理界面、数据查看、导入导出、保存结果、系统管理和退出。
+
+## 医学影像数据相关边界验证
+
+- 说明书中对 DICOM、STL、NIfTI、逆向分割映射等能力按用户可见操作描述。
+- 代码汇总中包含 DICOM/STL 解析预览、NIfTI/导出包、模型位姿、项目库、逆向工作区等核心逻辑片段。
+
+## Word 与素材验证
+
+- 使用 `unzip -t` 验证更新后的 `1. 软著说明书.docx` 和 `3. 代码汇总.docx`。
+- 确认说明书 Word 中嵌入图片，而不是仅保留 Markdown 文本链接。
+- 更新 `功能验证与素材清单.md`，记录截图文件及对应功能。
+
+## 部署验证
+
+- 验证 `http://127.0.0.1:4000/api/health`。
+- 验证 `http://127.0.0.1:4000/` 返回 200。
+
+## Git/Gitea 备份验证
+
+- 本次工程分析文档 commit message 包含 `2026-05-20-11-34-57`。
+- 推送 Gitea 成功后记录 commit。
+- 确认软著材料目录没有进入 commit。
+
+## 风险与回归关注点
+
+- 截图可能包含演示账号与项目名，保持为演示环境信息。
+- 不提交软著材料，避免与用户“软著撰写相关内容不需要放到 Gitea”的要求冲突。
+- 不处理已有历史文档删除状态。
+
+## 实际验证记录
+
+- 说明书已扩写：`新撰写软著文档/1. 软著说明书.md` 从 109 行扩展到 161 行，功能说明覆盖 23 个章节。
+- 真实截图已生成：`新撰写软著文档/images/` 下共有 8 张 PNG，尺寸均为 `1680 x 1050`。
+- 说明书图片引用检查：8 个 Markdown 图片引用全部存在，无 `[插入图片]` 占位符残留。
+- 说明书开发黑话检查：未命中 `接口`、`路由`、`payload`、`state`、`useState`、`useEffect`、`组件`、`函数` 等词。
+- 逆向工作区截图处理：首次普通 headless Chrome 截图因 WebGL 上下文创建失败为空白，已改用软件 WebGL 模式重新截图，最终 `06-reverse-workspace.png` 和 `07-reverse-export-options.png` 正常显示。
+- 代码汇总行数：`新撰写软著文档/3. 代码汇总.md` 为 8116 行，满足不少于 1600 行要求。
+- Word 生成：已重新生成 `1. 软著说明书.docx` 与 `3. 代码汇总.docx`。
+- Word 完整性：`unzip -t` 校验 `1. 软著说明书.docx` 与 `3. 代码汇总.docx` 均通过。
+- Word 图片嵌入：`1. 软著说明书.docx` 中存在 `word/media/image1.png` 至 `word/media/image8.png`，确认图片已嵌入 Word。
+- 构建检查：`npm run build` 通过；仍有 Vite 单 chunk 大小提示，不影响本次文档需求。
+- 空白检查：`git diff --check` 通过。
+- 服务检查：`http://127.0.0.1:4000/api/health` 返回正常，首页 `http://127.0.0.1:4000/` 返回 `HTTP/1.1 200 OK`。
+- Git 暂存检查：软著目录 `新撰写软著文档/` 保持未暂存，不纳入 Gitea。

工程分析/经验记录.md

@@ -1171,3 +1171,21 @@ C. 解决问题方案
 D. 后续如何避免问题
 
 示例素材、专利素材、软著素材只能作为文档或手动导入资源使用，不能命名为“最佳”“推荐”等产品级默认值。今后新增默认位姿或默认参数时，应同时检查前端默认列表、后端状态归一化和项目加载优先级，避免文档素材污染运行时逻辑。
+
+## 2026-05-20-11-34-57 软著截图自动化要兼顾 WebGL 渲染环境
+
+A. 具体问题
+
+为软著说明书插入真实系统截图时，普通 Chrome Headless 能正常截取登录、概况和项目库界面，但进入逆向工作区后页面空白，导致逆向工作区和导出选项截图不可用。
+
+B. 产生问题原因
+
+逆向工作区包含 Three.js 三维融合视图，普通 headless 环境中 WebGL 上下文创建失败，React 渲染链路被三维视图错误打断，最终截图只得到空白页面。
+
+C. 解决问题方案
+
+截图脚本在进入逆向工作区时改用 Chrome 软件 WebGL 参数，包括 `--enable-unsafe-swiftshader`、`--use-gl=angle` 和 `--use-angle=swiftshader`，等待页面稳定后重新截取逆向工作区与导出面板。生成 Word 时解析 Markdown 图片语法，并将 8 张 PNG 以嵌入媒体的形式写入说明书 `.docx`。
+
+D. 后续如何避免问题
+
+凡是为含三维场景的页面生成截图或录屏，都应优先验证截图不是空白，并检查浏览器控制台是否有 WebGL 创建失败信息。自动化截图应准备软件渲染兜底；Word 交付前必须用 `unzip -l` 检查 `word/media/` 是否包含预期图片。

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

@@ -0,0 +1,62 @@
+# 需求分析：扩写软著说明书并扩充代码汇总
+
+开始时间：`2026-05-20-11-34-57`
+
+## 原始需求摘要
+
+用户要求对 `新撰写软著文档/` 中的软著材料继续完善：
+
+1. 软著说明书内容偏少，需要把功能介绍写得更细，并直接截图插入说明书。
+2. 代码汇总中的代码行数偏少，要求 Markdown 版本至少达到 1600 行。
+
+## 业务目标
+
+- 让软著说明书更接近正式申报材料，覆盖登录、首页概况、项目库、逆向工作区、构件管理、分割映射、导出、系统管理、退出等完整使用流程。
+- 使用系统真实界面截图替代占位符，并在 Word 中嵌入图片。
+- 扩充代码汇总，保留核心前后端代码片段，使 `3. 代码汇总.md` 不少于 1600 行。
+
+## 输入与输出
+
+输入：
+
+- `※撰写Agent.md`
+- `参考软著构建模板/`
+- `新撰写软著文档/` 已有初稿
+- 当前运行中的 Web 系统
+- `WebSite/` 前后端源码
+
+输出：
+
+- 更新 `新撰写软著文档/1. 软著说明书.md`
+- 更新 `新撰写软著文档/1. 软著说明书.docx`
+- 更新 `新撰写软著文档/3. 代码汇总.md`
+- 更新 `新撰写软著文档/3. 代码汇总.docx`
+- 新增或更新 `新撰写软著文档/images/` 截图
+- 更新 `新撰写软著文档/功能验证与素材清单.md`
+
+## 影响范围
+
+- 仅影响软著申报材料输出目录和本次工程分析记录。
+- 不修改产品运行代码。
+- 软著撰写相关内容按用户前序约束不提交到 Gitea。
+
+## 关键约束
+
+- 说明书面向用户和审查人员，避免接口、路由、组件、状态变量等开发黑话。
+- 截图必须来自当前系统真实界面，不使用错误状态或严重遮挡截图。
+- 代码汇总 Markdown 至少 1600 行，但仍应优先选取核心源码，不纳入构建产物和第三方依赖。
+- Word 文档应可编辑，说明书图片需嵌入 Word。
+- 避免提交无关历史删除状态、医学数据、运行态产物和软著材料。
+
+## 风险点
+
+- 页面需要登录态，截图自动化可能需要先完成登录或使用当前共享会话。
+- 部分截图若三维资源仍在加载，需要等待界面稳定后再截取。
+- 代码汇总扩展到 1600 行时，应避免机械拼接重复内容或引入第三方库源码。
+- 当前工作区存在历史文档删除状态，提交时必须精确暂存。
+
+## 默认假设
+
+- 继续沿用当前软件名称、版本、待确认主体字段。
+- 软著材料仍仅保存在本地 `新撰写软著文档/`。
+- 本次无产品代码变更，但按项目工作流仍记录工程分析、提交工程分析文档并验证部署服务。