From cb681a45dfe1ecdeabaf0680463c2e247645cf2a Mon Sep 17 00:00:00 2001
From: admin <572701190@qq.com>
Date: Wed, 20 May 2026 12:24:34 +0800
Subject: [PATCH] =?UTF-8?q?2026-05-20-12-09-47=20=E5=AE=8C=E5=96=84?=
 =?UTF-8?q?=E8=BD=AF=E8=91=97=E9=80=90=E7=AB=A0=E9=85=8D=E5=9B=BE=E4=B8=8E?=
 =?UTF-8?q?=E7=B3=BB=E7=BB=9F=E8=A7=86=E9=A2=91?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 工程分析/实现方案-2026-05-20-12-09-47.md | 70 ++++++++++++++++++++++++
 工程分析/测试方案-2026-05-20-12-09-47.md | 67 +++++++++++++++++++++++
 工程分析/经验记录.md                     | 18 ++++++
 工程分析/需求分析-2026-05-20-12-09-47.md | 59 ++++++++++++++++++++
 4 files changed, 214 insertions(+)
 create mode 100644 工程分析/实现方案-2026-05-20-12-09-47.md
 create mode 100644 工程分析/测试方案-2026-05-20-12-09-47.md
 create mode 100644 工程分析/需求分析-2026-05-20-12-09-47.md

diff --git a/工程分析/实现方案-2026-05-20-12-09-47.md b/工程分析/实现方案-2026-05-20-12-09-47.md
new file mode 100644
index 0000000..2b50ba1
--- /dev/null
+++ b/工程分析/实现方案-2026-05-20-12-09-47.md
@@ -0,0 +1,70 @@
+# 实现方案：说明书逐章配图与系统视频生成
+
+实现方案文档路径：`工程分析/实现方案-2026-05-20-12-09-47.md`
+
+## 修改目标
+
+为软著说明书每个二级章节配置真实系统截图，并录制一段包含位姿导入流程的系统使用视频。
+
+## 涉及路径
+
+- `新撰写软著文档/1. 软著说明书.md`
+- `新撰写软著文档/1. 软著说明书.docx`
+- `新撰写软著文档/images/`
+- `新撰写软著文档/系统使用视频/`
+- `新撰写软著文档/功能验证与素材清单.md`
+- `head-ct-demo-pose-data.json`
+- `工程分析/需求分析-2026-05-20-12-09-47.md`
+- `工程分析/实现方案-2026-05-20-12-09-47.md`
+- `工程分析/测试方案-2026-05-20-12-09-47.md`
+- `工程分析/经验记录.md`
+
+## 技术路线
+
+1. 统计说明书 `## X.` 章节数量，建立章节与截图文件映射。
+2. 使用 Chrome DevTools Protocol 自动打开系统、登录、切换页面、点击控件、打开弹窗和导入位姿。
+3. 使用软件 WebGL 参数录制或截取逆向工作区，避免三维视图空白。
+4. 生成 23 张章节截图到 `新撰写软著文档/images/`。
+5. 将每个 `## X.` 章节下插入对应图片引用。
+6. 使用截图序列和 `ffmpeg` 生成系统使用视频 MP4，视频中包含 `head-ct-demo-pose-data.json` 位姿导入状态。
+7. 重新生成说明书 Word，确保所有图片嵌入。
+8. 更新素材清单，记录截图与视频。
+9. 运行检查、构建和部署验证。
+
+## 执行步骤
+
+- 检查 `ffmpeg`、Chrome 和系统服务状态。
+- 生成或刷新章节截图。
+- 自动化导入 `head-ct-demo-pose-data.json` 并截取/录制导入后的位姿状态。
+- 更新说明书 Markdown 和 Word。
+- 验证图片引用、Word 媒体数量、视频文件信息。
+- 工程分析文档与经验记录提交并推送。
+- 重新部署并验证服务。
+
+## 兼容性与回滚方案
+
+- 所有软著输出在本地目录，可通过历史 Markdown 或重新运行截图脚本恢复。
+- 若视频编码失败，保留截图序列并记录失败原因。
+- 若某个截图页面加载不完整，重新等待或切换到软件 WebGL 模式。
+
+## 预计文件变更
+
+软著本地材料：
+
+- `新撰写软著文档/1. 软著说明书.md`
+- `新撰写软著文档/1. 软著说明书.docx`
+- `新撰写软著文档/images/*.png`
+- `新撰写软著文档/系统使用视频/系统使用视频.mp4`
+- `新撰写软著文档/功能验证与素材清单.md`
+
+Gitea 备份：
+
+- 本轮工程分析三份文档。
+- `工程分析/经验记录.md`。
+
+## 提交与部署策略
+
+- 不暂存 `新撰写软著文档/` 和 `head-ct-demo-pose-data.json`。
+- 仅暂存本轮工程分析文档与经验记录。
+- commit message 包含 `2026-05-20-12-09-47`。
+- 推送后重启 `tmux` 会话 `revoxelseg-dicom` 并验证服务。
diff --git a/工程分析/测试方案-2026-05-20-12-09-47.md b/工程分析/测试方案-2026-05-20-12-09-47.md
new file mode 100644
index 0000000..030c6e6
--- /dev/null
+++ b/工程分析/测试方案-2026-05-20-12-09-47.md
@@ -0,0 +1,67 @@
+# 测试方案：章节配图与系统使用视频验证
+
+测试方案文档路径：`工程分析/测试方案-2026-05-20-12-09-47.md`
+
+## 静态检查
+
+- 统计 `新撰写软著文档/1. 软著说明书.md` 中 `## X.` 章节数量。
+- 检查每个 `## X.` 章节内均有至少一个 Markdown 图片引用。
+- 检查所有图片引用文件存在。
+- 检查无 `[插入图片]` 占位符残留。
+- 检查 `新撰写软著文档/系统使用视频/系统使用视频.mp4` 存在且大小不为 0。
+- 使用 `ffprobe` 或 `ffmpeg` 检查视频时长与编码信息。
+
+## 构建检查
+
+- 在 `WebSite/` 执行 `npm run build`。
+
+## 关键业务场景验证
+
+- 截图覆盖登录、总体概况、项目库、DICOM 浏览、DICOM 信息、STL 模型、构件层级、分割结果、逆向工作区、融合视角、可视化工具栏、位姿导入、映射视图、保存结果、导出选项、系统管理和退出。
+- 视频覆盖从登录到项目浏览、进入逆向工作区、导入 `head-ct-demo-pose-data.json`、查看映射视图和打开导出选项。
+
+## 医学影像数据相关边界验证
+
+- 视频和截图使用默认演示项目，不执行破坏性数据操作。
+- 位姿导入使用指定 JSON 文件并确认界面出现导入成功状态。
+- 逆向工作区截图与视频使用软件 WebGL 兜底，避免三维视图空白。
+
+## Word 与素材验证
+
+- 重新生成 `1. 软著说明书.docx`。
+- 使用 `unzip -t` 验证 Word 完整性。
+- 使用 `unzip -l` 检查 Word 内嵌图片数量不少于章节数。
+- 更新 `功能验证与素材清单.md`。
+
+## 部署验证
+
+- 验证 `http://127.0.0.1:4000/api/health`。
+- 验证 `http://127.0.0.1:4000/` 返回 200。
+- 重新部署后复验服务。
+
+## Git/Gitea 备份验证
+
+- commit message 包含 `2026-05-20-12-09-47`。
+- 推送 Gitea 成功后记录 commit。
+- 确认 `新撰写软著文档/` 未被暂存或提交。
+
+## 风险与回归关注点
+
+- 不把视频、截图和软著 Word 纳入 Gitea。
+- 不提交 `head-ct-demo-pose-data.json`。
+- 不处理已有历史工程分析文档删除状态。
+
+## 实际验证记录
+
+- 说明书章节检查：`新撰写软著文档/1. 软著说明书.md` 中共有 23 个 `## X.` 章节。
+- 图片覆盖检查：23 个章节均已配置图片引用，引用文件全部存在；`新撰写软著文档/images/` 中共有 23 张 `chapter-*.png` 章节图。
+- 占位与技术痕迹检查：未发现 `[插入图片]`、接口、路由、payload、state、useState、useEffect、组件、函数等不适合软著说明书正文的残留表达。
+- DICOM 信息截图处理：`chapter-09-dicom-info.png` 中患者姓名与患者编号显示区域已遮盖脱敏。
+- 视频文件检查：`新撰写软著文档/系统使用视频/系统使用视频.mp4` 为 H.264，1280x800，276 帧，时长 46.000000 秒，大小 826695 字节。
+- 位姿导入检查：第 16 章截图与视频素材使用 `head-ct-demo-pose-data.json`，界面显示“位姿数据已导入并保存”。
+- Word 完整性检查：`unzip -t 新撰写软著文档/1. 软著说明书.docx` 通过。
+- Word 图片嵌入检查：`unzip -l 新撰写软著文档/1. 软著说明书.docx | rg word/media | wc -l` 返回 23。
+- 素材清单检查：`新撰写软著文档/功能验证与素材清单.md` 已更新 23 张章节截图、视频文件、位姿来源和脱敏说明。
+- 构建检查：`WebSite/ npm run build` 通过，Vite 仅提示 chunk size warning。
+- 重新部署检查：已重启 `tmux` 会话 `revoxelseg-dicom`，服务日志显示 `ReVoxelSeg DICOM server ready at http://0.0.0.0:4000/`。
+- 服务检查：`http://127.0.0.1:4000/api/health` 返回 200，`http://127.0.0.1:4000/` 返回 200。
diff --git a/工程分析/经验记录.md b/工程分析/经验记录.md
index 7c4360a..8b35e96 100644
--- a/工程分析/经验记录.md
+++ b/工程分析/经验记录.md
@@ -1207,3 +1207,21 @@ C. 解决问题方案
 D. 后续如何避免问题
 
 默认演示数据和运行态输出要分开管理：默认项目资产可以入库，但导出文件、状态文件和用户临时数据仍应保持忽略。新增大体积医学数据前必须记录体积、文件数、脱敏/授权假设和远端推送结果；若体积继续增长，应评估 Git LFS 或独立数据包发布。
+
+## 2026-05-20-12-09-47 软著说明书逐章配图与视频需要同时校验交付格式
+
+A. 具体问题
+
+用户要求软著说明书中每一个 `## X.` 章节都配图，并录制系统使用视频，位姿导入必须使用 `head-ct-demo-pose-data.json`。如果只更新 Markdown 或只生成截图，不重新生成 Word 与视频，就会出现交付材料与源文档不一致的问题。
+
+B. 产生问题原因
+
+软著材料同时存在 Markdown、Word、截图目录和视频目录，多种格式之间没有自动同步机制；逆向工作区还依赖 WebGL 和隐藏文件输入，普通截图流程容易漏掉位姿导入成功状态或生成空白三维画面。
+
+C. 解决问题方案
+
+使用 Chrome 自动化打开系统核心页面并导入 `head-ct-demo-pose-data.json`，生成 23 张章节截图并插入到说明书 23 个 `## X.` 章节下；对 DICOM 信息截图中的患者姓名与编号区域进行遮盖脱敏；使用 `ffmpeg` 生成 H.264 MP4 系统使用视频；重新生成 `1. 软著说明书.docx` 并通过 `unzip -t` 和 `word/media` 数量检查确认 23 张图片已嵌入。
+
+D. 后续如何避免问题
+
+软著说明书增加、删除或改名章节后，应重新跑“章节数、图片数、图片文件存在、Word 媒体数量、视频信息”五类检查。涉及医学影像信息截图时必须先确认是否存在患者姓名、编号等敏感字段；涉及位姿展示时必须记录所用 JSON 文件，并在截图或视频中保留导入成功状态。
diff --git a/工程分析/需求分析-2026-05-20-12-09-47.md b/工程分析/需求分析-2026-05-20-12-09-47.md
new file mode 100644
index 0000000..e406c0f
--- /dev/null
+++ b/工程分析/需求分析-2026-05-20-12-09-47.md
@@ -0,0 +1,59 @@
+# 需求分析：软著说明书逐章配图与系统使用视频录制
+
+开始时间：`2026-05-20-12-09-47`
+
+## 原始需求摘要
+
+用户要求：
+
+1. 软著说明书中每一项 `## X.` 都配一个图。
+2. 录制一个系统使用视频。
+3. 视频中上传/导入位姿时使用 `head-ct-demo-pose-data.json`。
+
+## 业务目标
+
+- 让软著说明书每个二级章节均具备对应截图，形成完整图文说明。
+- 生成可用于软著材料附件或演示留档的系统使用视频。
+- 视频覆盖登录、项目浏览、逆向工作区、位姿导入、映射视图、导出选项等核心流程。
+
+## 输入与输出
+
+输入：
+
+- `新撰写软著文档/1. 软著说明书.md`
+- `新撰写软著文档/images/`
+- `head-ct-demo-pose-data.json`
+- 当前运行系统 `http://127.0.0.1:4000/`
+
+输出：
+
+- 更新 `新撰写软著文档/1. 软著说明书.md`
+- 更新 `新撰写软著文档/1. 软著说明书.docx`
+- 新增或更新 `新撰写软著文档/images/` 中 23 张章节截图
+- 新增 `新撰写软著文档/系统使用视频/系统使用视频.mp4`
+- 更新 `新撰写软著文档/功能验证与素材清单.md`
+
+## 影响范围
+
+- 仅影响软著材料本地输出目录和本轮工程分析记录。
+- 不修改产品源码。
+- 软著材料继续不纳入 Gitea；仅工程分析文档和经验记录进行备份提交。
+
+## 关键约束
+
+- 每个 `## X.` 章节至少有一张图片，且图片文件实际存在。
+- 视频录制过程中必须使用 `head-ct-demo-pose-data.json` 完成位姿导入。
+- 三维页面截图和视频需使用软件 WebGL 兜底，避免空白画面。
+- 说明书 Word 需嵌入所有章节图片。
+
+## 风险点
+
+- Headless 环境可能无法创建 WebGL 上下文，需要使用软件渲染参数。
+- 浏览器文件上传需通过自动化协议设置隐藏文件输入。
+- 视频生成依赖 `ffmpeg`，若编码失败需保留截图序列并记录原因。
+- 当前工作区存在历史文档删除状态和软著未跟踪目录，提交时需精确暂存。
+
+## 默认假设
+
+- 系统使用视频存放在 `新撰写软著文档/系统使用视频/`，作为软著本地材料，不提交到 Gitea。
+- 说明书每章配图可使用不同操作状态截图、局部截图或同一功能区不同状态截图，但不使用空白、错误或严重遮挡画面。