admin/REVOXELSEG_DICOM
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

2026-05-24-10-09-37 精简工程分析文档

Browse Source
This commit is contained in:
admin
2026-05-24 10:13:31 +08:00
parent 4a57fbe537
commit f54dafb83d
186 changed files with 195 additions and 10897 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
工程分析/代码编纂工作流.md
View File

@@ -1,6 +1,6 @@
# 代码编纂工作流
更新时间：2026-05-19-22-59-07
更新时间：2026-05-24-10-09-37
本工作流适用于后续所有项目修改相关需求。只要用户提出的是项目修改、修复、重构、部署、文档治理或功能调整，都必须按本流程走；除非用户明确要求跳过其中某一步。
@@ -86,6 +86,17 @@
- 默认远程仓库：
- `http://192.168.31.5:5002/admin/REVOXELSEG_DICOM.git`
## 6.1 工程分析目录精简策略
- `工程分析/` 长期保留：
- `代码编纂工作流.md`
- `工程整体分析.md`
- `经验记录.md`
- 当次正在执行的 `需求分析-*`、`实现方案-*`、`测试方案-*`
- 历史三件套不再默认长期堆积在目录中；完成沉淀后可通过 Git 历史追溯。
- 可复用的坑点、约束和解决办法必须沉淀到 `经验记录.md`，不要只留在一次性三件套中。
- 删除历史三件套属于文档治理变更，提交前必须确认没有混入源码、医学数据、运行态文件或用户未确认的非文档改动。
## 7. 重新部署
- 最终修改完成并通过测试后，重新部署本项目。

47
工程分析/实现方案-2026-05-04-02-38-48.md
View File

@@ -1,47 +0,0 @@
# 实现方案
时间戳：2026-05-04-02-38-48
## 修改目标
建立项目级代码编纂工作流，并生成初始工程分析文档，使后续项目修改需求有固定执行路径。
## 涉及路径
- `工程分析/代码编纂工作流.md`
- `工程分析/工程整体分析.md`
- `工程分析/需求分析-2026-05-04-02-38-48.md`
- `工程分析/实现方案-2026-05-04-02-38-48.md`
- `工程分析/测试方案-2026-05-04-02-38-48.md`
- `工程分析/经验记录.md`
- `.gitignore`
- `README.md`
## 技术路线
1. 创建 `工程分析/` 目录及工作流文档。
2. 根据当前项目结构写入工程整体分析。
3. 按时间戳写入本次需求、实现、测试文档。
4. 创建经验记录知识库。
5. 初始化 Git 仓库。
6. 配置 Gitea 远程仓库。
7. 提交文档备份 commit。
8. 对 `WebSite/` 执行构建验证。
9. 启动或重启开发部署服务。
## 数据与提交策略
- 默认提交工程文档、项目说明和必要 Git 配置。
- 默认不提交 `Head_CT_DICOM/` 和 `Head_CT_ReConstruct/`，避免医学影像数据和 STL 模型进入普通文档备份。
- 默认不提交 `WebSite/node_modules/`、`WebSite/dist/` 等构建产物。
## 回滚方案
- 若文档内容需要调整，直接修改对应 Markdown 文档并追加新的 commit。
- 若 Gitea 推送失败，本地 commit 保留，可在网络或认证修复后重新 push。
- 若部署失败，保留错误信息并写入经验记录。
## 人工审核状态
- 本文档用于建立工作流基线。
- 后续业务代码修改时，必须在实现方案完成后等待用户二次确认。

66
工程分析/实现方案-2026-05-04-03-08-20.md
View File

@@ -1,66 +0,0 @@
# 实现方案
时间戳：2026-05-04-03-08-20
## 修改目标
将系统品牌标识统一为用户提供的 logo，并把浏览器 title 改为“模型逆向系统”；完成后部署到 `http://192.168.3.11:4000/`。
## 涉及路径
- `WebSite/index.html`
- `WebSite/src/components/Login.tsx`
- `WebSite/src/components/Sidebar.tsx`
- `WebSite/public/logo.png` 或等效 logo 资源路径
- `工程分析/经验记录.md`
## 技术路线
1. 确认 logo 资源可被项目读取。
- 优先将用户提供的 logo 存为 `WebSite/public/logo.png`。
- 前端通过 `/logo.png` 引用该资源。
2. 修改浏览器标题。
- 将 `WebSite/index.html` 中 `<title>` 改为 `模型逆向系统`。
3. 修改 favicon。
- 在 `WebSite/index.html` 中增加或更新 `<link rel="icon" href="/logo.png" />`。
4. 修改登录页。
- 将 `Login.tsx` 顶部的 lucide `Layout` 图标替换为 `<img src="/logo.png" alt="模型逆向系统" />`。
- 标题显示为 `模型逆向系统`，保留或简化副标题以避免视觉重复。
5. 修改左侧栏。
- 将 `Sidebar.tsx` 左上角的蓝色方块 `Box` 图标替换为 `<img src="/logo.png" alt="模型逆向系统" />`。
- 保持左侧栏文字标题为 `模型逆向系统`。
6. 构建验证。
- 执行 `npm run build`。
7. 部署到 4000。
- 检查 `4000` 端口占用。
- 使用 `tmux` 会话托管 Vite 服务：
- `node ./node_modules/vite/bin/vite.js --host 0.0.0.0 --port 4000 --strictPort`
- 若原 `revoxelseg-dicom` 会话仍在 `3001`，优先关闭旧会话后使用同名会话部署到 `4000`。
8. 验证访问。
- `curl -I http://127.0.0.1:4000/`
- `curl -I http://192.168.3.11:4000/`
## 预计文件变更
- 新增 `WebSite/public/logo.png`。
- 修改 `WebSite/index.html`。
- 修改 `WebSite/src/components/Login.tsx`。
- 修改 `WebSite/src/components/Sidebar.tsx`。
- 更新 `工程分析/测试方案-2026-05-04-03-08-20.md` 执行结果。
- 更新 `工程分析/经验记录.md`。
## 兼容性与回滚方案
- favicon 和 logo 统一引用 `/logo.png`，便于后续替换资源。
- 若 logo 文件不可用，可先不提交代码修改，等待用户提供本地图片文件。
- 若 `4000` 端口不可用，记录占用进程并等待用户决定是否停止占用服务或改端口。
- 回滚时恢复 `index.html`、`Login.tsx`、`Sidebar.tsx`，并停止 `4000` 对应 tmux 会话。
## 人工审核状态
已确认并执行。
确认记录：
- 用户已回复 `确认执行`。
- 附件 logo 已在环境中确认，对应文件为 `/tmp/logo_check.png`，已复制为 `WebSite/public/logo.png`。

105
工程分析/实现方案-2026-05-04-03-21-40.md
View File

@@ -1,105 +0,0 @@
# 实现方案
时间戳：2026-05-04-03-21-40
## 修改目标
将当前前端静态演示升级为前后端协调系统：
- 后端统一管理登录状态、用户列表、项目列表和演示环境。
- 项目列表默认载入 `Head_CT_DICOM` 与 `Head_CT_ReConstruct`。
- 恢复演示环境出厂设置后恢复默认项目和默认用户。
- 逆向工作区通过后端生成并下载 `.nii.gz` 分割 mask。
- 继续部署到 `http://192.168.3.11:4000/`。
## 涉及路径
- `WebSite/package.json`
- `WebSite/server.ts`
- `WebSite/src/lib/api.ts`
- `WebSite/src/types.ts`
- `WebSite/src/App.tsx`
- `WebSite/src/components/Login.tsx`
- `WebSite/src/components/Overview.tsx`
- `WebSite/src/components/ProjectLibrary.tsx`
- `WebSite/src/components/ReverseWorkspace.tsx`
- `WebSite/src/components/UserManagement.tsx`
- `WebSite/data/state.json`
- `WebSite/exports/`
- `.gitignore`
- `工程分析/测试方案-2026-05-04-03-21-40.md`
- `工程分析/经验记录.md`
## 技术路线
1. 新增 Express 后端 `server.ts`。
- 开发环境通过 Vite 中间件服务前端。
- API 和页面共用 `4000` 端口，避免跨域和前后端端口不一致。
2. 后端状态持久化。
- 使用 `WebSite/data/state.json` 保存演示状态。
- 默认用户包括 `admin / 123456`。
- 当前登录状态由后端统一维护，所有浏览器轮询 `/api/session` 同步。
3. 默认项目载入。
- 后端扫描 `../Head_CT_DICOM` 的 `.dcm` 数量。
- 后端扫描 `../Head_CT_ReConstruct` 的 `.stl` 文件列表。
- 构造默认项目 `head-ct-demo`，包含 DICOM/STL 路径、数量、模块名称。
4. 恢复演示环境出厂设置。
- `POST /api/demo/reset` 重建默认用户、默认项目、登录状态。
- 前端系统管理页点击按钮后调用该接口，并刷新用户和项目相关数据。
5. 前端 API 化。
- `Login` 调用 `/api/login`。
- `App` 调用 `/api/session` 并轮询同步登录状态。
- `Overview` 调用 `/api/overview`。
- `ProjectLibrary` 调用 `/api/projects`。
- `UserManagement` 调用 `/api/users` 与 `/api/demo/reset`。
- `ReverseWorkspace` 调用 `/api/projects/:id` 与 `/api/projects/:id/export-mask`。
6. NIfTI 导出。
- 后端生成 NIfTI-1 单文件 `.nii.gz`。
- 使用 Node `zlib.gzipSync` 压缩。
- 文件保存到 `WebSite/exports/`，同时以 attachment 下载。
- NIfTI 内容先采用演示 mask 体素数据，尺寸、标签信息和项目元数据由后端生成。
7. 部署。
- `npm run build`
- `npm run lint`
- 使用 `tmux` 运行 `npm run serve -- --host 0.0.0.0 --port 4000`。
## 数据流
登录：
前端登录页 -> `POST /api/login` -> 后端验证账号密码 -> 更新共享 session -> 所有浏览器轮询 `/api/session` 后同步状态。
项目：
前端项目库 -> `GET /api/projects` -> 后端扫描或读取默认项目状态 -> 展示 DICOM 数量、STL 模块、路径和状态。
重置：
系统管理页 -> `POST /api/demo/reset` -> 后端重建默认状态 -> 前端刷新用户和项目。
导出：
逆向工作区 -> `POST /api/projects/:id/export-mask` -> 后端生成 `.nii.gz` -> 前端下载。
## 兼容性与回滚方案
- 保留 Vite/React 前端结构，后端通过同端口中间件接入。
- DICOM/STL 仍不进入 Git。
- `WebSite/data/state.json` 和 `WebSite/exports/` 作为运行态文件默认不纳入提交。
- 若后端服务异常，可回滚 `server.ts` 和前端 API 调用改动，恢复纯前端 Vite 部署。
## 预计文件变更
- 新增 `WebSite/server.ts`
- 新增 `WebSite/src/lib/api.ts`
- 修改 `WebSite/package.json`
- 修改 `WebSite/src/types.ts`
- 修改主要页面组件以接入 API。
- 修改 `.gitignore` 排除运行态数据和导出文件。
- 更新工程分析文档和经验记录。
## 人工审核状态
本次用户明确要求需求分析、实现方案、测试方案、执行修改均不用人工二次确认。
状态：自动确认，继续执行。

91
工程分析/实现方案-2026-05-04-03-50-07.md
View File

@@ -1,91 +0,0 @@
# 实现方案
时间戳：2026-05-04-03-50-07
## 修改目标
修复概况统计、图表警告和模块高亮问题；完善项目库真实 DICOM/STL/分割结果展示；增加项目创建和重命名能力；补齐 README 构建方案并重新部署。
## 涉及路径
- `WebSite/server.ts`
- `WebSite/src/lib/api.ts`
- `WebSite/src/types.ts`
- `WebSite/src/components/Overview.tsx`
- `WebSite/src/components/ProjectLibrary.tsx`
- `WebSite/README.md`
- `README.md`
- `工程分析/测试方案-2026-05-04-03-50-07.md`
- `工程分析/经验记录.md`
## 技术路线
1. 后端项目状态增强。
- 保留默认项目，同时允许新增用户创建项目。
- 新增 `POST /api/projects` 创建项目。
- 新增 `PATCH /api/projects/:projectId` 修改项目名称。
2. 后端 DICOM 预览。
- 新增 `GET /api/projects/:projectId/dicom-preview?slice=0`。
- 读取当前 DICOM 文件，解析 Rows、Columns、Pixel Data、Window Center/Width、Rescale Slope/Intercept。
- 返回 `width`、`height`、`pixels` base64 灰度数据和 slice 元数据。
3. 后端 STL 文件服务。
- 新增 `GET /api/projects/:projectId/models/:fileName`。
- 只允许读取项目对应 STL 列表中的文件，避免任意路径读取。
4. 前端项目库。
- DICOM 视图使用 canvas 绘制后端返回灰度像素。
- 3D 模型视图使用 Three.js `STLLoader` 加载真实 STL。
- 新增 `分割结果` tab，展示 mask 预览、标签图例和 NII/NII.GZ 下载。
- 项目列表顶部增加创建按钮和名称输入。
- 项目卡右侧增加编辑图标，可重命名。
- 移除首个 STL 模块默认蓝色高亮，所有模块同等样式。
5. 概况页。
- 已处理项目改为“已导出 Mask 项目”，避免项目总数 1 时已处理 1 的误导。
- 趋势数据改为平稳小范围变化。
- Recharts 容器增加 `min-w-0`、固定高度和加载态，避免宽高 -1 警告。
6. README。
- 补充 Node 构建运行方案。
- 说明当前无需 Python/conda；真实体素化阶段再引入 Python 环境建议。
7. 验证与部署。
- `npm run lint`
- `npm run build`
- API smoke test
- 重新部署 `tmux` 会话到 `4000`。
## 数据流
DICOM 预览：
前端切片滑块 -> `/api/projects/:id/dicom-preview?slice=n` -> 后端解析 DICOM 像素 -> 前端 canvas 绘制。
STL 预览：
前端选择 STL 模块 -> `/api/projects/:id/models/:fileName` -> `STLLoader` 加载几何体 -> Three.js 渲染。
分割结果：
前端 `分割结果` tab -> 展示 mask 预览 -> 调用已有 `/api/projects/:id/export-mask` 导出 `nii` 或 `nii.gz`。
项目管理：
创建/重命名 -> 后端写入 `state.json` -> 项目列表刷新。
## 兼容性与回滚方案
- DICOM/STL 原始文件仍不提交 Git。
- 若 DICOM 解析失败，前端显示错误态，不影响其他页面。
- 若 STL 加载失败，前端显示模型加载失败提示，不影响 DICOM 和分割结果。
- 回滚时恢复 `server.ts` 和项目库组件即可回到上一版前后端演示状态。
## 预计文件变更
- 修改后端 API。
- 修改项目库和概况页。
- 修改 API 类型和封装。
- 修改 README。
- 更新工程分析文档和经验记录。
## 人工审核状态
本次用户明确要求无需人工二次确认。
状态：自动确认，继续执行。

77
工程分析/实现方案-2026-05-04-04-12-34.md
View File

@@ -1,77 +0,0 @@
# 实现方案
时间戳：2026-05-04-04-12-34
## 修改目标
完善项目库导入/下载按钮语义、DICOM 三方向预览、STL 多模型颜色透明度控制、项目创建弹窗、删除确认和编辑自动保存。
## 涉及路径
- `WebSite/server.ts`
- `WebSite/src/lib/api.ts`
- `WebSite/src/types.ts`
- `WebSite/src/components/ProjectLibrary.tsx`
- `工程分析/测试方案-2026-05-04-04-12-34.md`
- `工程分析/经验记录.md`
## 技术路线
1. 后端 DICOM 预览扩展。
- `GET /api/projects/:projectId/dicom-preview?slice=&plane=`
- 支持 `plane=axial|sagittal|coronal`。
- 横断面读取单张 DICOM。
- 矢状面/冠状面从 DICOM 序列采样生成重建平面。
2. 后端项目删除。
- 新增 `DELETE /api/projects/:projectId`。
- 删除后写入共享状态。
3. 前端 API 扩展。
- `getDicomPreview(projectId, slice, plane)`。
- `deleteProject(projectId)`。
4. 项目库交互。
- 顶部右侧按钮：DICOM/3D 视图显示“导入”；分割结果不显示顶部第二按钮。
- 创建项目改为点击 `+` 弹窗输入名称。
- 编辑项目名称改为输入框失焦或回车自动保存。
- 删除项目点击垃圾桶后弹窗二次确认。
5. DICOM UI。
- 增加横断面、矢状面、冠状面切换。
- 右侧滑块改为稳定轨道，显示 `第 n / 总数`。
- 圆点与轨道对齐。
6. 3D 模型 UI。
- 右侧眼睛为全体显示/隐藏。
- 每个 STL 使用颜色输入框和透明度滑块。
- Three.js 同时渲染所有可见 STL，并应用对应颜色和透明度。
- 删除无意义状态点。
## 数据流
DICOM：
前端选择方向和切片 -> 后端按方向返回灰度像素 -> 前端 canvas 绘制。
3D：
后端提供 STL 文件 -> 前端为每个 STL 建立颜色/透明度/可见性状态 -> Three.js 渲染多模型。
项目：
创建弹窗 -> `POST /api/projects`；编辑失焦 -> `PATCH /api/projects/:id`；删除确认 -> `DELETE /api/projects/:id`。
## 兼容性与回滚方案
- 保留原 `axial` 行为，新增方向参数不影响旧调用。
- 若矢状面/冠状面解析失败，前端显示错误态。
- 若 STL 多模型性能不足，可通过全体眼睛或单项眼睛隐藏模型。
- 回滚时恢复 `ProjectLibrary.tsx` 和相关 API 即可。
## 预计文件变更
- 修改 `server.ts`、`api.ts`、`types.ts`、`ProjectLibrary.tsx`。
- 更新测试方案执行结果。
- 更新经验记录。
## 人工审核状态
本次用户明确要求无需人工二次确认。
状态：自动确认，继续执行。

76
工程分析/实现方案-2026-05-04-04-58-36.md
View File

@@ -1,76 +0,0 @@
# 实现方案
时间戳：2026-05-04-04-58-36
## 修改目标
修复项目列表按钮重叠；增强逆向工作区当前项目与融合视图；增加 DICOM 缓存和显示模式；重做 3D 模型渲染加载状态，避免 React Three Fiber 引入的 Three.js `Clock` 警告。
## 涉及路径
- `WebSite/server.ts`
- `WebSite/src/lib/api.ts`
- `WebSite/src/types.ts`
- `WebSite/src/components/ProjectLibrary.tsx`
- `WebSite/src/components/ReverseWorkspace.tsx`
- `工程分析/测试方案-2026-05-04-04-58-36.md`
- `工程分析/经验记录.md`
## 技术路线
1. 项目列表布局。
- 将收缩按钮从标题区右侧移到侧栏外侧中线位置。
- 保留 `+` 在项目列表标题行内，避免重叠。
2. DICOM 预览缓存与显示模式。
- 后端增加内存缓存：按 project、plane、slice、mode 缓存灰度预览。
- API 增加 `mode=default|bone|soft|contrast`。
- 前端增加显示模式切换，并将 mode 传给 API。
3. 3D 模型渲染。
- 项目库中不再使用 React Three Fiber Canvas。
- 后端增加 STL 二进制采样预览 API，避免浏览器一次解析 240MB 原始 STL。
- 前端改用原生 Three.js 手动创建 renderer、camera、scene、geometry。
- 显示加载进度条；WebGL 不可用时使用二维 canvas 模型预览兜底。
- 使用自动包围盒归一化、居中、缩放，确保模型可见。
4. 逆向工作区。
- 拉取当前项目详情。
- 顶部显示当前项目名、DICOM/STL 数量和路径。
- 融合视图显示 DICOM canvas 背景，并叠加简化 STL/模型轮廓或模型投影效果，表达等比例缩放、中心对齐状态。
5. 验证与部署。
- `npm run lint`
- `npm run build`
- API smoke test
- headless Chrome 冒烟检查
- 重启 `tmux` 会话部署到 `4000`。
## 数据流
DICOM：
前端选择 plane/slice/mode -> 后端命中或生成缓存预览 -> 前端 canvas 显示。
3D：
前端读取 STL 采样预览 API -> 后端返回抽样三角面顶点 -> 原生 Three.js 生成材质、居中缩放 -> 渲染；WebGL 不可用时绘制二维投影预览。
逆向融合：
前端按当前项目获取 DICOM 预览和项目信息 -> canvas 绘制影像 -> HTML/SVG/Three 投影层叠加中心对齐模型轮廓。
## 兼容性与回滚方案
- DICOM preview API 兼容旧参数，不传 mode 时默认为 default。
- 如果原生 Three.js 渲染异常，页面会使用二维 canvas 兜底预览，不影响项目库浏览。
- 运行态缓存仅在进程内，不写入 Git。
## 预计文件变更
- 修改后端 DICOM preview API。
- 修改项目库 3D 组件和 DICOM 控件。
- 修改逆向工作区融合视图。
- 更新工程分析文档和经验记录。
## 人工审核状态
本次用户明确要求无需人工二次确认。
状态：自动确认，继续执行。

61
工程分析/实现方案-2026-05-04-05-20-16.md
View File

@@ -1,61 +0,0 @@
# 实现方案 - 2026-05-04-05-20-16
## 修改目标
围绕项目库 DICOM/3D 浏览体验和逆向工作区标题信息进行收敛修复，保证 DICOM 切片控制可连续移动、三平面可旋转且显示完整清晰，补充下载能力，并修复 3D 模型加载完成后仍不可见的问题。
## 涉及路径
- `WebSite/server.ts`
- `WebSite/src/components/ProjectLibrary.tsx`
- `WebSite/src/components/ReverseWorkspace.tsx`
- `WebSite/src/lib/api.ts`
- `WebSite/src/types.ts`
- `工程分析/经验记录.md`
## 技术路线
1. DICOM 文件排序
- 将 DICOM 文件列表改为基于文件名的自然排序，确保 `1.dcm`、`2.dcm`、`10.dcm` 顺序正确。
2. DICOM 重建与清晰度
- 后端对矢状面/冠状面重建结果进行非黑边界裁切并保留安全边距，减少“只显示一半”的视觉问题。
- 对预览灰度图做轻量边缘增强，提高 DCM 影像边界辨识度。
3. 切片控制与旋转
- 前端新增上下箭头按钮，长按时用定时器连续推进或回退切片。
- DICOM 三平面统一支持左/右 90 度旋转，旋转状态参与画布绘制和 PNG 导出。
4. 下载能力
- 后端新增 DICOM 序列压缩包接口，使用 `tar.gz` 生成压缩包，不引入额外依赖。
- 前端增加下载按钮，支持当前图片 PNG 和 DICOM 压缩包。
5. 3D 模型显示
- 继续使用后端 STL 抽样预览，前端原生 Three.js 渲染。
- 修正模型居中和相机适配逻辑，增加坐标轴容错、投影兜底和加载进度。
6. 逆向工作区
- 去掉 `Head_CT_DICOM ↔ Head_CT_ReConstruct` 路径说明，仅保留当前项目、DICOM 数量、STL 数量等上下文。
## 数据流与交互流程
- 项目库加载项目 -> 选择 DICOM 面/模式/切片 -> 后端返回灰度预览 -> 前端 canvas 绘制并按旋转角度显示。
- 用户点击 PNG 下载 -> 使用当前 canvas 像素、平面、切片、模式、旋转角度生成命名完整的 PNG。
- 用户点击 DICOM 压缩包下载 -> 后端按文件名自然排序打包 `Head_CT_DICOM`。
- 用户进入 3D 模型页 -> 前端请求 STL 抽样预览 -> Three.js 居中缩放显示全部可见构件。
## 兼容性与回滚方案
- 若 DICOM 压缩包下载异常，不影响 DICOM 预览和 PNG 下载。
- 若 WebGL 不可用，仍保留二维 canvas 投影兜底预览。
- 回滚时可恢复本次提交前的 `server.ts`、项目库和逆向工作区组件。
## 预计文件变更
- 前后端代码 4-5 个文件。
- 本次流程文档 3 个文件。
- 经验记录追加 2-3 条。
## 人工审核状态
用户已在需求中明确：“本次的 需求分析、实现方案、测试方案、执行修改 都不用我人工二次确认了”。因此本方案记录后直接执行。

82
工程分析/实现方案-2026-05-04-05-41-22.md
View File

@@ -1,82 +0,0 @@
# 实现方案 - 2026-05-04-05-41-22
## 修改目标
在不直接加载全部原始 STL 的前提下，提高 3D 模型预览的实体感，并加入整体位姿控制；改进 DICOM 长按切片时的连续图像反馈；精简逆向工作区重复标题与项目描述。
## 涉及路径
- `WebSite/src/components/ProjectLibrary.tsx`
- `WebSite/src/components/ReverseWorkspace.tsx`
- `WebSite/server.ts`
- `工程分析/经验记录.md`
## 技术路线
### 1. 3D 模型实体化程度
- 在项目库 3D 模型页增加“实体化程度”控制，建议分为：
- `预览`：维持较低三角面抽样，优先速度。
- `标准`：提高抽样数量，呈现连续表面。
- `精细`：进一步提高抽样数量，但仍保留上限防止卡顿。
- 将当前固定 `/preview?limit=6000` 改为根据实体化程度动态请求，例如 `6000 / 16000 / 36000`。
- Three.js 渲染继续使用 `MeshStandardMaterial`，但新增：
- `flatShading: false`
- 更强的环境光、主光和边缘光。
- 可选整体白色实体显示模式，让模型更接近用户参考图。
- 保留每个 STL 构件的颜色和透明度控制，新增“整体白色实体”开关时临时覆盖颜色为白/灰，不破坏原配置。
### 2. 3D 模型位姿控制
- 在 3D 模型左侧画布上方或右侧面板增加整体位姿控制：
- 旋转 X/Y/Z 滑块，范围 `-180° ~ 180°`。
- 平移 X/Y/Z 微调，范围建议 `-2 ~ 2`。
- 缩放滑块，范围建议 `0.5 ~ 2`。
- 重置按钮。
- 将自动旋转改为可开关；当用户调整位姿时，自动旋转默认关闭，避免控制冲突。
- 将位姿状态传入 `NativeStlViewer`，渲染循环中应用到 group。
### 3. DICOM 长按连续图像变化
- 当前 `startSliceStep` 只是连续改变 `sliceIndex`，图像依赖 API 响应更新。为增强“动起来”的感觉：
- 将步进间隔保持在 `90~120ms`，同时在请求期间显示轻量切片过渡效果。
- 增加 `latestPreviewRequestRef` 或请求序列号，确保旧请求返回时不会覆盖新切片。
- 在 `sliceIndex` 变化时，立即更新右下角切片文字和 canvas 容器的轻微淡入/亮度变化。
- 若接口响应较慢，保留上一帧图像并叠加“正在切换”状态，避免画面停滞误解。
### 4. 逆向工作区信息精简
- 删除 `ReverseWorkspace` 页面内 `h2` 标题“逆向工作区”，保留全局 header 的标题。
- 删除页面内副标题中的上方“当前项目：xxx”文本。
- 保留下方标签行：
- `当前项目：头部 CT 模型逆向体素化演示`
- `DICOM 300`
- `STL 9`
- 将标签字号从 `text-[11px]` 提升为 `text-sm` 或 `text-[13px]`，内边距加大，提高可读性。
## 数据流或交互流程
1. 用户进入项目库 3D 模型页。
2. 前端根据实体化程度选择 STL preview limit 请求后端抽样数据。
3. Three.js 将各 STL 抽样三角面生成实体 mesh，按当前实体化、颜色、透明度、白色实体模式、整体位姿状态渲染。
4. 用户拖动位姿控制滑块，前端立即更新 group 的 rotation / position / scale。
5. 用户在 DICOM 页长按切片按钮，前端连续改变 `sliceIndex`，后端返回切片预览，前端按最新请求序号绘制最新帧。
6. 用户进入逆向工作区，只看到全局 header 的“逆向工作区”和加大后的当前项目标签行。
## 兼容性与回滚方案
- 实体化程度默认使用“标准”，若性能不佳可切回“预览”。
- WebGL 不可用时继续使用二维投影兜底，实体化和位姿控制主要作用于 WebGL 路径。
- 若提高抽样上限导致性能问题，可只回滚实体化程度 limit 参数，不影响项目列表、DICOM 和导出功能。
- 逆向工作区文案调整为纯 UI 变更，可直接回滚组件 JSX。
## 预计文件变更
- `ProjectLibrary.tsx`：新增 3D 渲染控制状态、实体化程度、位姿控制 UI、DICOM 请求序号和切片过渡反馈。
- `server.ts`：可能提高 STL preview 的安全上限。
- `ReverseWorkspace.tsx`：删除重复标题/副标题，调整标签字号。
- `经验记录.md`：执行后追加本次经验。
## 人工审核状态
用户已回复“确认方案”，按已确认方案执行项目业务代码修改。

85
工程分析/实现方案-2026-05-04-05-56-34.md
View File

@@ -1,85 +0,0 @@
# 实现方案 - 2026-05-04-05-56-34
## 修改目标
修正 DICOM 矢状面/冠状面的物理比例，新增 DICOM 详细信息查询；简化 3D 模型显示控制，加入更高实体化档位，并实现画布内鼠标旋转、平移、滚轮缩放且同步整体位姿控件。
## 涉及路径
- `WebSite/server.ts`
- `WebSite/src/types.ts`
- `WebSite/src/lib/api.ts`
- `WebSite/src/components/ProjectLibrary.tsx`
- `工程分析/经验记录.md`
## 技术路线
### 1. DICOM 空间信息解析
- 扩展后端 DICOM tag 解析：
- Pixel Spacing `(0028,0030)`：单张切片内行/列像素实际距离。
- Slice Thickness `(0018,0050)`。
- Spacing Between Slices `(0018,0088)`。
- Image Position Patient `(0020,0032)`：优先用相邻切片空间位置差计算真实切片间距。
- Patient、Study、Series、Modality、Manufacturer、Rows、Columns、Window、Rescale 等基础信息。
- 在 DICOM volume cache 中保存 `rowSpacing`、`columnSpacing`、`sliceSpacing`。
### 2. 多平面物理比例重采样
- 当前矢状面/冠状面生成后先得到原始矩阵。
- 根据物理尺寸计算目标比例：
- 横向：`切片数 * sliceSpacing`
- 矢状面纵向：`rows * rowSpacing`
- 冠状面纵向：`columns * columnSpacing`
- 以较小物理间距作为输出采样单位，将重建图像最近邻重采样到接近真实物理比例的像素宽高。
- 返回 `spacing` 和 `physicalSize`，供前端信息展示。
### 3. DICOM 详细信息查询
- 新增后端接口：`GET /api/projects/:projectId/dicom-info`。
- 返回默认项目第一张 DICOM 与序列聚合信息：
- patient、study、series、image、window、spacing、sequence、source 等分组。
- 前端 DICOM 影像页新增“信息”按钮，打开弹窗/面板展示基本信息、像素间距、切片间距、图像矩阵、物理尺寸、文件数量、首尾文件等。
### 4. 3D 模型控制简化与增强
- 去掉“白色实体”开关和“自动旋转”开关。
- 默认模型不自动旋转，正向放置。
- 实体化档位改为：`预览 / 标准 / 精细 / 超精细`。
- 后端 STL preview 抽样上限提升到 `72000`，前端超精细档使用 `72000`。
- 重置位姿按钮移动到“整体位姿”标题右侧。
### 5. 鼠标/滚轮位姿交互
- 在 `NativeStlViewer` 容器上监听 pointer 和 wheel：
- 左键拖拽：旋转 X/Y。
- 右键或 Shift+拖拽：平移 X/Y。
- 滚轮：缩放。
- 交互时通过 `onPoseChange` 回写 React state，使滑块数值同步变化。
- 禁用浏览器右键菜单，避免右键平移时弹出菜单。
- 位姿仍作用于整体 group，不改变 STL 构件相对位置。
## 数据流或交互流程
1. 前端请求 DICOM preview，后端解析/缓存体数据和空间信息，按真实物理比例输出矢状面/冠状面。
2. 前端点击 DICOM 信息按钮，请求 dicom-info，弹窗展示元数据和空间参数。
3. 前端进入 3D 模型页，按当前实体化档位请求 STL preview。
4. 用户拖拽/滚轮操作画布，`NativeStlViewer` 更新位姿并回写父组件，右侧滑块同步变化。
5. 用户点击重置位姿，模型回到默认正向摆放。
## 兼容性与回滚方案
- 若某些 DICOM tag 缺失，后端使用默认 spacing `1mm`，并在详情中展示“未知/默认”。
- 多平面重采样使用最近邻，避免引入新依赖；如比例异常可回滚到原始矩阵输出。
- 超精细档可能更慢，但保留低档位可回退。
- 鼠标交互只作用于项目库 3D 视图，不影响 DICOM、导出和逆向工作区。
## 预计文件变更
- 后端：DICOM metadata/spacing 解析、多平面重采样、dicom-info API、STL 上限。
- 前端：DICOM 信息弹窗、3D 控件重构、鼠标交互回写位姿。
- 文档：测试结果和经验记录追加。
## 人工审核状态
用户已明确本次无需人工二次确认，文档落地后直接执行。

46
工程分析/实现方案-2026-05-07-16-20-46.md
View File

@@ -1,46 +0,0 @@
# 实现方案 - 2026-05-07-16-20-46
## 修改目标
修正项目库 3D 模型页默认位姿，使初次打开和点击“重置位姿”都恢复到类似参考图的正常俯视/正向姿态。
## 涉及路径
- `WebSite/src/components/ProjectLibrary.tsx`
- `工程分析/经验记录.md`
## 技术路线
1. 默认位姿
- 保持 `defaultModelPose` 的旋转、平移和缩放为中性值，避免默认滑块显示已经偏转。
- 重置位姿继续设置为 `defaultModelPose`。
2. 默认相机
- 将 `NativeStlViewer` 默认 camera 从斜向等距视角调整为更接近参考图的俯视视角。
- 使用 `camera.position.set(0, 0, 6)`、`camera.up.set(0, 1, 0)`、`camera.lookAt(0, 0, 0)`，让模型以 XY 平面正向进入视野。
- resize 后保留相机方向。
3. 视觉验证
- 进入 3D 模型页后，模型不再以明显斜向等距视角显示。
- 通过鼠标/滚轮改变位姿后，点击重置回到标准默认视角。
4. 与上一轮未提交改动合并
- 保留并验证 DICOM 空间比例、DICOM 信息面板、3D 超精细档、鼠标交互同步等改动。
## 数据流或交互流程
用户进入项目库 -> 点击 3D 模型 -> 前端创建 Three.js camera 并使用默认俯视相机 -> STL group 居中缩放 -> 默认位姿滑块为 0/0/0 与缩放 1 -> 用户交互后可点击重置恢复。
## 兼容性与回滚方案
- 如果参考视角需要再微调，可只调整 camera position/up，不影响 STL 数据和后端接口。
- 回滚可恢复相机到原先 `(4.5, 3.5, 5)` 等距视角。
## 预计文件变更
- `ProjectLibrary.tsx` 中相机默认位置和说明文字。
- `经验记录.md` 追加默认位姿经验。
## 人工审核状态
用户已明确本次无需人工二次确认，文档落地后直接执行。

111
工程分析/实现方案-2026-05-07-16-35-52.md
View File

@@ -1,111 +0,0 @@
# 实现方案 - 2026-05-07-16-35-52
## 修改目标
围绕项目库 3D 模型预览页，完善整体位姿控制、旋转中心和方位提示：
- 将单个 `重置位姿` 拆为 `重置旋转位姿`、`重置平移缩放位姿`。
- 旋转 X/Y/Z 增加 `-90°` 和 `+90°` 快捷按钮。
- 平移 X/Y/Z 增加负向/正向快捷步进按钮，缩放增加缩小/放大快捷按钮。
- 将模型旋转中心稳定在所有 STL 拼装后整体包围盒的中心。
- 在 3D 模型画布右下角增加 X/Y/Z 方位坐标提示和当前旋转角度。
## 涉及路径
- `WebSite/src/components/ProjectLibrary.tsx`
## 技术路线
### 1. 拆分重置按钮
新增两个函数：
- `resetModelRotationPose()`
- 只重置 `rotateX`、`rotateY`、`rotateZ` 为 `0`。
- 保留 `translateX/Y/Z` 和 `scale`。
- `resetModelTransformPose()`
- 重置 `translateX`、`translateY`、`translateZ` 为 `0`，`scale` 为 `1`。
- 保留 `rotateX/Y/Z`。
将 `整体位姿` 标题右侧按钮改为两个小按钮：
- `重置旋转位姿`
- `重置平移缩放位姿`
### 2. 增加快捷调整按钮
为位姿控制行增加快捷按钮：
- 旋转 X/Y/Z：
- `-90°`：当前角度减 90，并限制在 `[-180, 180]`。
- `+90°`：当前角度加 90，并限制在 `[-180, 180]`。
- 平移 X/Y/Z：
- 负向按钮：每次减 `0.25`。
- 正向按钮：每次加 `0.25`。
- 仍限制在 `[-2, 2]`。
- 缩放：
- 缩小按钮：每次减 `0.1`。
- 放大按钮：每次加 `0.1`。
- 仍限制在 `[0.5, 2.5]`。
为避免数值越界和重复逻辑，新增统一的 `clampModelPoseValue()` 和 `nudgeModelPose()`。
### 3. 修正模型旋转中心
当前 STL 预览已经会对 mesh geometry 进行中心化处理。本次进一步显式拆分 Three.js 层级：
- `poseGroup`：负责整体平移。
- `pivotGroup`：位于模型整体几何中心，负责旋转和缩放。
- 所有 STL mesh 挂载在 `pivotGroup` 下，并在写入顶点时先减去整体包围盒中心。
动画循环中：
- `poseGroup.position = translateX/Y/Z`
- `pivotGroup.rotation = rotateX/Y/Z`
- `pivotGroup.scale = baseScale * scale`
这样模型始终围绕整体包围盒中心旋转，平移不会改变旋转轴心。
### 4. 增加右下角 X/Y/Z 方位提示
在 `NativeStlViewer` 容器中增加绝对定位 overlay：
- 显示三个彩色轴向：X 红色、Y 绿色、Z 蓝色。
- 显示当前 `rotateX/Y/Z` 数值，随滑块、快捷按钮、鼠标拖拽同步刷新。
- 放置于画布右下角，避免遮挡左下角 `MODEL PATH` 状态信息。
## 数据流与交互流程
1. 用户点击快捷按钮或拖动滑块。
2. 前端调用 `updateModelPose()` 或 `nudgeModelPose()`。
3. `modelPose` React 状态更新。
4. `NativeStlViewer` 通过 `poseRef` 在 Three.js 动画循环中读取最新状态。
5. Three.js 更新 `poseGroup` 与 `pivotGroup`。
6. 右下角方位提示读取同一份 `modelPose` 并更新显示。
## 兼容性与回滚方案
- 修改只影响 3D 模型页面，不影响 DICOM 影像、分割结果、后端 API。
- 若旋转中心方案出现异常，可回滚到单 group 结构，同时保留 UI 快捷按钮。
- 若 overlay 影响视觉，可只保留文本角度提示，不影响核心模型显示。
## 预计文件变更
- `WebSite/src/components/ProjectLibrary.tsx`
- 新增位姿 clamp/nudge/reset 方法。
- 更新整体位姿控制区 UI。
- 调整 `NativeStlViewer` 的 group 层级。
- 增加右下角方位提示 overlay。
## 人工审核状态
- 实现方案：用户已确认。
- 确认信息：用户回复“都确认，后续直接搞”。
## 执行结果
- 已在 `WebSite/src/components/ProjectLibrary.tsx` 完成实现。
- 已拆分 `重置旋转位姿`、`重置平移缩放位姿`。
- 已为旋转、平移、缩放增加快捷调整按钮。
- 已将 3D 模型渲染层级拆为平移容器和中心旋转容器。
- 已新增右下角 X/Y/Z 方位与旋转角度提示。

82
工程分析/实现方案-2026-05-07-16-53-23.md
View File

@@ -1,82 +0,0 @@
# 实现方案 - 2026-05-07-16-53-23
## 修改目标
修复 3D 模型在细节档位切换和鼠标旋转时的中心漂移问题，并完善右下角坐标系联动和按钮样式。
## 涉及路径
- `WebSite/src/components/ProjectLibrary.tsx`
## 技术路线
### 1. 分离 Three.js 渲染容器和 React overlay
当前 `NativeStlViewer` 会对 `containerRef.current.innerHTML = ''`，容易把 React overlay 或其他子节点一起清掉。改为：
- `viewportRef`：只用于挂载 Three.js canvas。
- 外层 React 容器保留进度条、状态条、右下角坐标系等 overlay。
- 清理时只清理 `viewportRef` 内的 canvas。
### 2. 修正模型重载后的中心与缩放
模型加载完成后：
- 先把所有 mesh 加入 `pivotGroup`。
- 基于 `pivotGroup` 的整体包围盒计算 `center` 和 `size`。
- 将所有 mesh geometry 统一平移 `-center`，保证拼装后的整体中心落在局部原点。
- 使用 `pivotGroup.rotation` 和 `pivotGroup.scale`，使用 `poseGroup.position` 做平移。
- 每次切换细节档位时重建模型，但继承同一份 `modelPose`，并确保新模型仍以整体中心为 pivot。
### 3. 鼠标拖拽围绕模型中心旋转
- 鼠标左键拖拽只更新 `rotateX/rotateY`，不改变 `translateX/Y/Z`。
- 旋转继续作用在 `pivotGroup`，而不是同时承担平移的 group。
- 对 `poseRef.current` 做统一 clamp，保持鼠标、滑块、快捷按钮状态一致。
### 4. 坐标系随位姿同步旋转
新增一个轻量 SVG 坐标轴组件：
- 根据 `rotateX/Y/Z` 构造 Three.js `Euler` 和 `Matrix4`。
- 将 X/Y/Z 三个单位轴向量通过旋转矩阵变换后投影到 2D。
- 在右下角 SVG 中绘制红色 X、绿色 Y、蓝色 Z 三条轴。
- 继续显示 X/Y/Z 当前角度数值。
### 5. 调整按钮颜色
- 将 `重置平移缩放位姿` 的文字颜色改为 `text-blue-600 hover:text-blue-700`，与 `重置旋转位姿` 一致。
## 数据流或交互流程
1. 用户拖拽鼠标或点击位姿按钮。
2. `modelPose` 更新并 clamp。
3. `NativeStlViewer` 的动画循环读取 `poseRef.current`。
4. `poseGroup` 只应用平移，`pivotGroup` 只应用旋转和缩放。
5. 右下角坐标轴组件读取同一份 `pose`，同步更新方向。
6. 切换模型显示细节档时重新请求 STL preview，但模型仍以整体包围盒中心作为 pivot。
## 兼容性与回滚方案
- 修改仅影响项目库 3D 模型页，不修改 DICOM 后端和 mask 导出。
- 若 SVG 坐标轴表现不佳，可回滚为静态坐标轴加角度文本。
- 若新的 viewportRef 清理方式导致 canvas 不显示，可回滚为原始 containerRef，但必须避免清掉 overlay。
## 预计文件变更
- `WebSite/src/components/ProjectLibrary.tsx`
- 新增 `OrientationGizmo`。
- `NativeStlViewer` 改用 `viewportRef`。
- 调整模型中心化和清理逻辑。
- 调整重置按钮样式。
## 人工审核状态
- 本次免二次确认，方案写入后直接执行。
## 执行结果
- 已在 `WebSite/server.ts` 为 STL preview 增加全量包围盒 `bounds`。
- 已在 `WebSite/src/components/ProjectLibrary.tsx` 使用所有可见 STL 的稳定全量包围盒计算整体中心和缩放基准。
- 已将右下角静态坐标轴替换为基于 `rotateX/Y/Z` 投影的动态 SVG 坐标轴。
- 已统一 `重置旋转位姿` 与 `重置平移缩放位姿` 的字体颜色。

64
工程分析/实现方案-2026-05-07-17-05-43.md
View File

@@ -1,64 +0,0 @@
# 实现方案 - 2026-05-07-17-05-43
## 修改目标
将 3D 模型显示档位由 `预览 / 标准 / 精细 / 超精细` 改为 `标准 / 精细 / 超精细 / 实体`，并让 `实体` 更接近完整 STL 面片渲染。
## 涉及路径
- `WebSite/src/components/ProjectLibrary.tsx`
- `WebSite/server.ts`
## 技术路线
### 1. 更新档位类型和配置
- 将 `SolidityLevel` 从 `preview | standard | fine | ultra` 改为 `standard | fine | ultra | solid`。
- 删除 `预览` 选项。
- 新增 `实体` 选项。
- 设置 `实体` 的 `limit` 为更高值，尽量覆盖默认 9 个 STL 的完整三角面。
### 2. 提升后端 STL preview 上限
- 后端 `createStlPreview()` 当前最大抽样上限为 `72000`。
- 将上限提升到 `200000`，支持实体档位请求更多三角面。
- 继续保留 `sampleLimit` clamp，避免异常超大请求拖垮服务。
### 3. 优化实体档位材质
- 在 `NativeStlViewer` 中判断当前档位是否为 `solid`。
- `solid` 档位下使用更高的不透明度下限，例如 `0.92`，增强实体感。
- 其他档位继续使用构件层级中的用户透明度设置。
## 数据流或交互流程
1. 用户点击 `实体`。
2. 前端 `solidityLevel` 切换为 `solid`。
3. `selectedSolidity.limit` 变大，`NativeStlViewer` 重新请求 STL preview。
4. 后端按更高上限返回更多三角面和稳定 `bounds`。
5. 前端以实体材质重新渲染模型。
## 兼容性与回滚方案
- 若实体档位渲染压力过大，可降低 `solid.limit` 或后端最大上限。
- 若用户仍需要低质量快速预览，可恢复 `preview` 配置。
## 预计文件变更
- `WebSite/src/components/ProjectLibrary.tsx`
- 更新 `SolidityLevel`、`solidityOptions`。
- `NativeStlViewer` 增加 `solidMode` 参数。
- 实体档位材质增强不透明度。
- `WebSite/server.ts`
- 提升 STL preview 最大抽样上限。
## 人工审核状态
- 本次免二次确认，方案写入后直接执行。
## 执行结果
- 已删除 `模型显示` 中的 `预览` 档位。
- 已新增 `实体` 档位，前端请求上限为 `200000`。
- 已将后端 STL preview 最大抽样上限从 `72000` 提升到 `200000`。
- 已在实体档位提高材质不透明度下限，增强实体面片视觉。

119
工程分析/实现方案-2026-05-07-17-28-34.md
View File

@@ -1,119 +0,0 @@
# 实现方案 - 2026-05-07-17-28-34
## 修改目标
在逆向工作区实现三维 DICOM 体与 STL 模型融合视角：
- DICOM 切片范围可控。
- DICOM 以黑色长方体和多张切片纹理展示。
- 最后一张切片显示在体表面。
- STL 模型叠加在 DICOM 体中。
- 用户可以调整模型位姿。
- DICOM 和 STL 可以一起旋转、平移、缩放观察。
## 涉及路径
- `WebSite/server.ts`
- `WebSite/src/types.ts`
- `WebSite/src/lib/api.ts`
- `WebSite/src/components/ReverseWorkspace.tsx`
## 技术路线
### 1. 后端新增 DICOM 融合体接口
新增接口：
```text
GET /api/projects/:projectId/dicom-fusion-volume?start=0&end=49&mode=soft
```
返回内容：
- `width`、`height`
- `start`、`end`、`total`
- `indices`
- `frames`：每张切片灰度图 base64
- `spacing`：row/column/slice
- `physicalSize`：width/height/depth
为控制传输和纹理压力：
- 单次最多返回 64 张切片。
- 纹理最大边长限制为 256。
- 使用已有 `getDicomVolume()` 和 `resampleNearest()`，避免重复实现 DICOM 解析。
### 2. 前端新增类型与 API
- 在 `types.ts` 新增 `DicomFusionVolume`。
- 在 `api.ts` 新增 `getDicomFusionVolume(projectId, start, end, mode)`。
### 3. 重构融合视角为 Three.js 场景
在 `ReverseWorkspace.tsx` 中新增 `FusionThreeView`：
- 创建 Three.js scene/camera/renderer。
- DICOM：
- 用半透明黑色 box 表示 CT 体。
- 将范围内切片转为 `CanvasTexture`。
- 按切片索引在 Z 方向分层放置。
- 最后一帧贴到体表面并提高不透明度。
- STL：
- 调用已有 STL preview 接口加载模型构件。
- 使用后端返回 `bounds` 合成稳定模型中心。
- 将模型挂到 `modelGroup`。
- 场景：
- DICOM 体和模型都放入 `fusionRoot`，整体旋转和平移缩放作用在 `fusionRoot`。
- 模型位姿单独作用在 `modelPoseGroup`。
### 4. 交互与控制
- 鼠标左键拖拽：旋转整体融合场景。
- Shift/右键拖拽：平移整体融合场景。
- 滚轮：缩放整体融合场景。
- UI 控件：
- 切片起点、切片终点。
- 模型旋转 X/Y/Z。
- 模型平移 X/Y/Z。
- 模型缩放。
- 重置模型位姿。
## 数据流或交互流程
1. 进入逆向工作区后加载项目详情。
2. 根据默认切片范围请求 DICOM 融合体数据。
3. 请求 STL preview 并加载模型。
4. Three.js 创建 DICOM 体和 STL 模型。
5. 用户拖拽场景时 DICOM 与 STL 一起旋转。
6. 用户调整模型位姿时只改变 STL 模型相对 DICOM 的位置。
7. 用户调整切片范围时重新请求 DICOM 融合体数据并刷新 CT 体。
## 兼容性与回滚方案
- 若 WebGL 不可用，显示加载失败/不支持提示，不影响其他页面。
- 若融合体接口失败，保留逆向工作区其他 mask 导出功能。
- 若性能不足，可降低最大返回切片数和纹理尺寸。
## 预计文件变更
- `WebSite/server.ts`
- 新增 `createDicomFusionVolume()` 和 API route。
- `WebSite/src/types.ts`
- 新增 `DicomFusionVolume` 类型。
- `WebSite/src/lib/api.ts`
- 新增 `getDicomFusionVolume()`。
- `WebSite/src/components/ReverseWorkspace.tsx`
- 新增 Three.js 融合视角组件和位姿控制。
## 人工审核状态
- 本次免二次确认，方案写入后直接执行。
## 执行结果
- 已新增 `GET /api/projects/:projectId/dicom-fusion-volume`，支持按 `start/end/mode` 返回一段轴向 DICOM 体数据纹理。
- 已新增 `DicomFusionVolume` 类型和 `api.getDicomFusionVolume()`。
- 已将逆向工作区 `影像与模型融合视角` 重构为 Three.js 三维场景。
- 已实现黑色 DICOM 长方体、范围内切片纹理层叠、最后一帧体表面显示。
- 已将 STL 模型加载进同一融合场景，可通过模型位姿控件相对 DICOM 体调整。
- 已支持鼠标拖拽/滚轮对 DICOM 体和 STL 模型整体旋转、平移、缩放。

83
工程分析/实现方案-2026-05-07-18-11-12.md
View File

@@ -1,83 +0,0 @@
# 实现方案 - 2026-05-07-18-11-12
## 修改目标
- 修复项目库构件层级眼睛按钮。
- 为构件层级增加可编辑 ID。
- 左侧导航新增 `模型库`。
- 逆向工作区将 `分割 Mask` 替换为 `可视化工具栏`，并加入模型显示、整体位姿保存/选择、构件层级。
## 涉及路径
- `WebSite/src/types.ts`
- `WebSite/src/App.tsx`
- `WebSite/src/components/Sidebar.tsx`
- `WebSite/src/components/ProjectLibrary.tsx`
- `WebSite/src/components/ReverseWorkspace.tsx`
## 技术路线
### 1. 左侧新增模型库
- 在 `ViewType` 中新增 `MODELS`。
- Sidebar 增加 `模型库` 导航项。
- App 中点击 `模型库` 时复用 `ProjectLibrary`，但通过 `initialViewMode="model"` 默认进入 3D 模型页。
### 2. 项目库构件层级眼睛修复与 ID
- `ModuleStyle` 增加 `partId`。
- 初始化构件层级时按文件顺序写入 `partId=index+1`。
- `toggleModuleVisibility()` 明确保留 `partId/color/opacity`，只切换 `visible`。
- 构件眼睛按钮阻止冒泡，避免父级点击干扰。
- 每个构件显示 `ID` 输入框，输入值限制为 1 到 255 的整数。
### 3. 逆向工作区可视化工具栏
- 将标题 `分割 Mask` 改为 `可视化工具栏`。
- 增加模型显示档位：标准、精细、超精细、实体。
- 增加整体位姿保存/选择：
- 默认预设：默认、俯视、侧视。
- 用户可保存当前位姿为 `位姿N`。
- 选择后更新 `modelPose`。
- 增加构件层级：
- 眼睛显示/隐藏。
- 颜色。
- 透明度。
- ID 1 到 255。
- 将逆向工作区 Three.js 模型加载逻辑接入构件样式和显示档位。
## 数据流或交互流程
1. 用户进入 `模型库` 或项目库 3D 模型页。
2. 构件样式状态按 STL 文件初始化。
3. 用户点击眼睛按钮，前端更新对应构件 `visible`，Three.js 重新加载/渲染可见构件。
4. 用户修改 ID，前端 clamp 到 1 到 255 并显示。
5. 用户进入逆向工作区，工具栏显示模型显示、位姿预设、构件层级。
6. 用户保存或选择整体位姿，融合视角模型位姿更新。
## 兼容性与回滚方案
- `模型库` 复用项目库，不新增后端路由。
- 构件 ID 仅在前端状态中使用，若后续需要持久化可再扩展后端项目状态。
- 若逆向工作区工具栏过长，可后续拆成 tabs 或折叠区。
## 预计文件变更
- `types.ts`：新增 ViewType。
- `Sidebar.tsx`：新增导航项。
- `App.tsx`：支持模型库视图和 ProjectLibrary 初始 tab。
- `ProjectLibrary.tsx`：构件 ID、眼睛修复、初始 viewMode 参数。
- `ReverseWorkspace.tsx`：可视化工具栏与模型样式/位姿预设。
## 人工审核状态
- 本次免二次确认，方案写入后直接执行。
## 执行结果
- 已新增左侧导航 `模型库`，默认进入项目库的 3D 模型页。
- 已为项目库构件层级增加 `ID` 输入，默认 1 到 N，输入限制为 1 到 255。
- 已修正项目库构件眼睛按钮切换时保留颜色、透明度、ID 状态。
- 已将逆向工作区 `分割 Mask` 改为 `可视化工具栏`。
- 已在可视化工具栏加入模型显示档位、整体位姿保存/选择、构件层级。
- 已将逆向工作区融合视角的 STL 加载接入构件显示、颜色、透明度和模型显示档位。

79
工程分析/实现方案-2026-05-07-18-42-53.md
View File

@@ -1,79 +0,0 @@
# 实现方案 - 2026-05-07-18-42-53
## 修改目标
1. 移除逆向工作区可视化工具栏底部 Metadata 信息块。
2. 将 DICOM 融合切片范围控制改为融合视角下方单滑条，滑条值表示展示到第几张切片。
3. 将整体位姿控制区统一命名为“模型位姿”，并保留现有位姿保存、选择、重置和调节能力。
4. 将构件 ID 从纯组件状态提升为后端项目状态字段，使项目库 3D 模型与逆向工作区可视化工具栏联动。
## 涉及路径
- `WebSite/src/components/ReverseWorkspace.tsx`
- `WebSite/src/components/ProjectLibrary.tsx`
- `WebSite/src/server.ts`
- `WebSite/src/types.ts`
- `工程分析/经验记录.md`
## 技术路线
### 构件 ID 联动
- 在后端项目数据中增加 `moduleStyles` 字段，存储每个 STL 文件的：
- `visible`
- `color`
- `opacity`
- `partId`
- 项目库与逆向工作区读取项目时都使用同一个 `project.moduleStyles` 初始化。
- 任一页面修改 ID、颜色、透明度、显示状态时，通过 `PATCH /api/projects/:projectId/module-styles` 写回后端。
- 前端本地状态更新后同步调用 API，保证跨页面和跨浏览器一致。
### 融合切片范围
- 保留后端接口需要的 `start/end` 参数。
- 前端只展示一个滑条 `sliceEnd`，内部固定 `start = 0`，`end = sliceEnd`。
- 滑条放在影像与模型融合视角下方，便于操作与结果对应。
### 位姿模块整合
- 将工具栏内的“整体位姿”标题改为“模型位姿”。
- 保留模型显示、位姿保存/选择、旋转、平移、缩放与重置功能，但减少重复命名。
### UI 清理
- 删除可视化工具栏底部 Metadata 代码块。
## 数据流
1. 后端读取或重置项目时生成默认 `moduleStyles`，`partId` 默认从 1 到 N。
2. 项目库修改构件 ID 后调用 API 保存。
3. 逆向工作区加载项目时读取最新 `moduleStyles`。
4. 逆向工作区修改构件 ID 后同样调用 API 保存。
5. 融合视角滑条变化后触发 `dicom-fusion-volume?start=0&end=<sliceEnd>` 重新加载体数据。
## 兼容性与回滚方案
- 对旧 `state.json` 做兼容：项目没有 `moduleStyles` 时由后端按 STL 列表自动补齐。
- 若新增 API 出现问题，前端仍可回退为本地状态，但 ID 联动会退化。
- 所有修改集中在项目状态、项目库与逆向工作区，回滚本次 commit 即可恢复。
## 预计文件变更
- `server.ts`：补齐项目 moduleStyles、增加更新 API。
- `types.ts`：补充项目 moduleStyles 类型。
- `ProjectLibrary.tsx`：读取/保存共享 moduleStyles。
- `ReverseWorkspace.tsx`：读取/保存共享 moduleStyles，调整切片范围 UI，删除 Metadata，重命名位姿模块。
## 人工审核状态
用户已声明本次不需要二次人工确认，按默认执行确认规则直接执行。
## 执行记录
- 已新增共享构件样式数据 `moduleStyles`，包含 `visible/color/opacity/partId`。
- 已新增 `PATCH /api/projects/:projectId/module-styles`，用于项目库与逆向工作区同步构件 ID、颜色、透明度、显示隐藏状态。
- 已将项目库和逆向工作区的构件 ID 读写改为同一后端项目状态。
- 已删除逆向工作区可视化工具栏下方 `Metadata` 信息块。
- 已将融合视角下方 DICOM 切片范围改为单一进度条，内部固定从第 1 张开始显示。
- 已将可视化工具栏中的“整体位姿”改为“模型位姿”，并合并位姿保存、选择和各项旋转/平移/缩放控制。
- 已同步将项目库 3D 模型中的“整体位姿”标题改为“模型位姿”。

108
工程分析/实现方案-2026-05-08-01-19-42.md
View File

@@ -1,108 +0,0 @@
# 实现方案 - 2026-05-08-01-19-42
## 修改目标
1. 修复模型库大缩放时构件层级不可见或不可滚动的问题。
2. 更换逆向工作区侧栏图标，避免与模型库重复。
3. 优化逆向工作区模型位姿控制：拆分重置按钮、增加 ±90° 旋转、位姿重命名、单击最低刻度、长按连续移动。
4. 为融合视角增加 DICOM 体数据缓存与五个预存点位。
5. 在融合视角显示 DICOM 边界框、模型边界框，并以 DICOM 中心作为模型旋转中心。
6. 增加 DICOM 透明度三档控制。
7. 增加基于 DICOM 帧的模型切分预览，显示切割面。
## 涉及路径
- `WebSite/src/components/Sidebar.tsx`
- `WebSite/src/components/ProjectLibrary.tsx`
- `WebSite/src/components/ReverseWorkspace.tsx`
- `WebSite/src/lib/api.ts`
- `WebSite/src/types.ts`
- `WebSite/server.ts`
- `工程分析/经验记录.md`
## 技术路线
### 模型库滚动
- 调整项目库 3D 模型页右侧栏为 `min-h-0` + 内部滚动结构。
- 构件层级列表占用剩余高度，标题和控制区固定，防止浏览器放大后构件列表被挤出。
### 侧栏图标
- 侧栏中模型库继续使用 `Box`，逆向工作区改用 `Workflow` 或 `ScanLine` 类图标，保证含义和视觉不同。
### 位姿控制
- 在逆向工作区可视化工具栏中替换 `重置默认位姿` 为：
- `重置旋转位姿`
- `重置平移缩放位姿`
- 旋转 X/Y/Z 增加 `-90°` 和 `+90°` 按钮。
- 平移和缩放增加正负最小步进按钮。
- 单击按钮只移动一个最低刻度；鼠标或触摸长按时启动定时器连续移动。
- 保存位姿列表中允许重命名非默认位姿，默认位姿保持不可改名。
### DICOM 缓存与预存点
- 前端维护 `fusionVolumeCacheRef`，以 `projectId/mode/end` 作为 key 缓存融合体数据。
- DICOM 切片范围显示五个点位按钮，分别映射 20%、40%、60%、80%、100%。
- 点击预存点位时优先从缓存读取；缓存未命中则请求接口并写入缓存。
- 增加“预存五点”按钮，后台并发预取五个点位。
### 边界框与旋转中心
- FusionThreeView 增加 DICOM BoxHelper/LineSegments 边界和模型边界。
- 模型 STL 顶点以自身中心归一化后，整体 group 的 pivot 固定在 DICOM 体中心。
- 旋转、缩放围绕 DICOM 中心进行，平移作为模型相对 DICOM 中心的偏移。
### DICOM 透明度
- 新增 `dicomOpacityLevel`，提供低/中/高三档。
- 传入 FusionThreeView，控制 DICOM 体素切片和切片纹理材质透明度。
### 模型切分
- 新增切割开关、切割帧滑条和切割面显示。
- Three.js 中使用 DICOM 切片帧在 Z 方向的相对位置作为切割平面。
- 通过 local clipping plane 对模型材质裁剪，并显示半透明切割面。
## 数据流或交互流程
1. 进入逆向工作区后读取项目与 `moduleStyles`。
2. Fusion 视角按当前切片范围加载体数据，先查前端缓存，未命中再请求后端。
3. 用户点击五个点位或预存按钮，前端将对应 `end` 的 DICOM volume 写入缓存。
4. 用户调整模型位姿，模型围绕 DICOM 中心旋转缩放，并实时更新边界框。
5. 用户启用模型切分并选择 DICOM 帧，Three.js 使用对应切割平面裁剪模型并显示切割面。
## 兼容性与回滚方案
- 缓存仅存在浏览器内存中，不改变后端数据结构。
- 新增控制项都保留默认值，旧项目数据可直接使用。
- 若切割平面对部分浏览器性能影响较大，可关闭切割功能回到原始渲染。
- 回滚本次 commit 即可恢复。
## 预计文件变更
- `Sidebar.tsx`：调整逆向工作区图标。
- `ProjectLibrary.tsx`：修复右侧构件层级滚动布局。
- `ReverseWorkspace.tsx`：增加缓存、预存点、位姿控制、边界框、透明度和切割功能。
- `api.ts/types.ts/server.ts`：如需支持缓存辅助或类型扩展则同步调整。
## 人工审核状态
用户已声明本次不需要二次人工确认，按默认执行确认规则直接执行。
## 执行记录
- 已将左侧逆向工作区图标从 `Box` 改为 `Workflow`，与模型库图标区分。
- 已将模型库 3D 模型右侧栏改为整栏滚动结构，解决浏览器放大后构件层级下方内容不可见的问题。
- 已在逆向工作区模型位姿中增加：
- `重置旋转位姿`
- `重置平移缩放位姿`
- X/Y/Z 的 ±90° 快捷旋转
- 旋转/平移/缩放的最低刻度单击步进与长按连续步进
- 非默认位姿重命名输入
- 已在融合视角中增加 DICOM 透明度低/中/高三档。
- 已在融合视角中增加 DICOM 边界框和模型边界框显示开关。
- 已将模型旋转中心改为以 DICOM 体中心为 pivot，模型自身偏移放入子节点，避免旋转时围绕模型偏移点运动。
- 已增加 DICOM 切片范围五个点位和 `预存五点` 功能，前端使用内存 Map 缓存融合体数据。
- 已增加模型切分开关、切割帧滑条、橙色切割面显示，并通过 Three.js clipping plane 裁剪模型。

85
工程分析/实现方案-2026-05-08-01-53-07.md
View File

@@ -1,85 +0,0 @@
# 实现方案 - 2026-05-08-01-53-07
## 修改目标
1. 固定融合视角的 DICOM 物理尺寸基准，使切片范围变化不改变模型原始位置。
2. DICOM 切片范围默认显示到最高切片，并支持 `M-N` 双向范围选择。
3. 优化逆向工作区布局，浏览器放大后可滚动访问 DICOM 切片范围。
4. 项目库项目加载/导入后后台预加载 DICOM 与模型预览。
5. 模型切分开启后，在 DICOM 切割帧上叠加 Mask 轮廓/填充，直观看到切割位置。
## 涉及路径
- `WebSite/src/components/ProjectLibrary.tsx`
- `WebSite/src/components/ReverseWorkspace.tsx`
- `WebSite/server.ts`
- `工程分析/经验记录.md`
## 技术路线
### 固定 DICOM 体基准
- 后端 `dicom-fusion-volume` 的 `physicalSize.depth` 改为完整 DICOM 序列深度，而不是当前 `start/end` 范围深度。
- 前端 FusionThreeView 使用完整物理尺寸计算 DICOM box 和模型缩放，范围变化只改变参与显示的帧，不改变空间基准。
- 模型 pivot 保持 DICOM 中心，不根据切片范围重新定位。
### 双向范围滑条
- 恢复 `sliceStart` 与 `sliceEnd` 两个状态，但 UI 使用同一范围卡片表达。
- 初始值设为 `sliceStart=maxSlice`、`sliceEnd=maxSlice`，即默认最高切片。
- 请求接口前将 `min(sliceStart,sliceEnd)` 和 `max(sliceStart,sliceEnd)` 作为真实 `M-N`。
- UI 显示 `M-N / total`，并提供两个滑条在同一区域控制左右端点。
### 放大布局
- 逆向工作区根容器允许纵向滚动。
- 主三列区域保留内部滚动，左侧融合区域不因高度压缩导致 DICOM 范围卡片不可达。
### 后台预加载
- 项目库加载项目列表后，对默认/选中项目发起低成本预加载：
- DICOM 预览中间帧。
- 前几个 STL preview。
- 融合体最高切片。
- 使用 `void` 异步调用，不阻塞 UI。
### 切割 Mask 叠加
- FusionThreeView 中当 `cutEnabled` 时，根据当前切割帧创建 DICOM texture overlay。
- 在切割帧平面上叠加半透明橙色 Mask 区域和边界线，表示模型切割位置。
- 该 Mask 是可视化辅助层，不改变模型、不写出 NIfTI。
## 数据流或交互流程
1. 进入逆向工作区读取项目，计算 `maxSlice=dicomCount-1`。
2. 初始范围设为 `maxSlice-maxSlice`。
3. 用户拖动双向范围控制，前端排序后请求 `dicom-fusion-volume?start=M&end=N`。
4. 后端返回当前范围帧，但 physical depth 始终以完整 DICOM 序列计算。
5. FusionThreeView 使用固定 DICOM box 渲染 DICOM 与模型，模型位姿不受范围变化影响。
6. 启用模型切分后，在切割帧平面叠加 Mask 预览。
## 兼容性与回滚方案
- 对任意 DICOM 总数使用 `dicomCount` 和接口返回 `total`，不硬编码 300。
- 若项目没有 DICOM 或 STL，预加载自动跳过。
- 回滚本次 commit 可恢复旧的单端点切片范围与切割显示。
## 预计文件变更
- `server.ts`：修正融合体 physical depth 基准。
- `ProjectLibrary.tsx`：新增项目后台预加载。
- `ReverseWorkspace.tsx`：双向范围、布局滚动、固定模型空间、切割 Mask 叠加。
## 人工审核状态
用户已声明本次不需要二次人工确认，按默认执行确认规则直接执行。
## 执行记录
- 已将后端 `dicom-fusion-volume` 的 `physicalSize.depth` 改为完整 DICOM 序列深度，避免切片范围变化导致 DICOM 体和模型空间重新缩放。
- 已将融合视图中每张 DICOM 帧的 Z 位置改为按真实 `volume.indices` 映射到完整 DICOM 深度，范围变化只增减显示帧，不重新铺满空间。
- 已将逆向工作区 DICOM 切片范围改为双端点控制，支持 `M-N` 显示范围。
- 已将默认切片范围初始化为最高切片 `maxSlice-maxSlice`，不硬编码 300。
- 已让逆向工作区根容器支持纵向滚动，浏览器放大时仍可滚动访问 DICOM 切片范围。
- 已在项目库中加入项目后台预加载：最高 DICOM 预览、最高融合体、前三个 STL 预览。
- 已在模型切分开启时，在切割 DICOM 帧上叠加橙色 Mask 预览和边界标记，使用户能直接在 DICOM 上看到切割位置。

53
工程分析/实现方案-2026-05-08-03-03-52.md
View File

@@ -1,53 +0,0 @@
# 实现方案：单条 DICOM 范围滑块
时间戳：2026-05-08-03-03-52
## 修改目标
将逆向体素化工作区“DICOM 切片范围”从两个上下排列的原生进度条，改为一条自绘轨道叠加两个可拖动端点的范围条。
## 涉及路径
- `WebSite/src/components/ReverseWorkspace.tsx`
- `WebSite/src/index.css`
- `工程分析/经验记录.md`
## 技术路线
1. 在 `ReverseWorkspace.tsx` 中基于 `safeSliceStart`、`safeSliceEnd`、`displayStart`、`displayEnd` 计算范围条起止百分比。
2. 替换原有两个 `<label><input type="range"></label>`。
3. 使用一个 `relative` 容器绘制：
- 灰色底轨；
- 蓝色选中范围；
- 两个透明轨道的 `range input`，只显示滑块端点。
4. 在 `index.css` 中新增 `.dicom-range-input` 样式，隐藏原生轨道，保留 thumb，并让 thumb 可点击拖动。
5. 端点重合时提高“起点”滑块层级，便于从默认 `300-300` 状态向左拖出范围。
## 数据流与交互流程
- 用户拖动起点端点：调用 `setSliceStart(Number(event.target.value))`。
- 用户拖动终点端点：调用 `setSliceEnd(Number(event.target.value))`。
- 当前显示范围继续由 `displayStart = min(start, end)` 与 `displayEnd = max(start, end)` 决定。
- 后续 `loadFusionVolume(displayStart/displayEnd)` 相关逻辑保持现状。
## 兼容性与回滚方案
- 若自定义样式在目标浏览器表现异常，可回滚本次对 `ReverseWorkspace.tsx` 和 `index.css` 的修改，恢复两个原生 range。
- 本次不修改后端 API 和数据结构，回滚风险较低。
## 风险控制
- 保留无障碍 `aria-label`，明确起点和终点端点。
- 通过 `npm run lint` 和 `npm run build` 检查 TypeScript 与构建。
- 部署后通过页面源码或构建产物搜索确认不存在“起点/终点两个 label + 两个进度条”的旧结构。
## 预计文件变更
- 新增本次需求、实现、测试方案文档。
- 修改 `ReverseWorkspace.tsx` 中 DICOM 范围控件 JSX。
- 修改 `index.css` 增加范围条浏览器兼容样式。
- 追加 `经验记录.md`。
## 人工审核状态
用户已在项目工作流历史中确认后续直接执行，本次不等待二次人工审核。

54
工程分析/实现方案-2026-05-08-03-13-20.md
View File

@@ -1,54 +0,0 @@
# 实现方案：DICOM 范围驱动模型切分
时间戳：2026-05-08-03-13-20
## 修改目标
将逆向工作区模型切分从“独立帧滑块 + 单切面 + CUT MASK 贴图”改为“DICOM 切片范围双端点 + 双 clipping plane + 保留中间模型”。
## 涉及路径
- `WebSite/src/components/ReverseWorkspace.tsx`
- `工程分析/经验记录.md`
## 技术路线
1. 删除 `createCutMaskTexture` 及其调用，彻底去掉 `CUT MASK` 贴图。
2. 删除 `cutSlice` 状态、初始化和模型切分的帧进度条。
3. 项目加载时将 `sliceStart` 初始化为 `0`，`sliceEnd` 初始化为 `maxIndex`，让初始范围显示 `1~300`。
4. `FusionThreeView` 接收 `cutStart`、`cutEnd`，来自 `displayStart`、`displayEnd`。
5. 根据 DICOM 全序列总数和物理深度，将 `cutStart/cutEnd` 映射为 DICOM Z 坐标。
6. 创建两个 clipping plane：
- 起点切面：剔除起点外侧。
- 终点切面：剔除终点外侧。
7. 模型材质在 `cutEnabled` 时使用两个 clipping plane，`clipIntersection=false`，从而保留两平面之间的中间区域。
8. 用两张半透明橙色切面辅助显示切割位置，但不再显示任何 mask 图片。
## 数据流或交互流程
- 用户调整 `DICOM 切片范围`。
- `displayStart/displayEnd` 归一化端点顺序。
- 前端按该范围加载 DICOM 纹理，并将同一范围传给 `FusionThreeView` 的模型切割逻辑。
- 用户启用 `模型切分` 后，STL 模型只显示两帧之间的区域。
## 兼容性与回滚方案
- 若双 clipping plane 行为异常，可回滚本次 `ReverseWorkspace.tsx` 修改，恢复 `cutSlice` 单切面逻辑。
- 本次不改 API 和数据文件，回滚只影响前端可视化。
## 风险控制
- 使用 `npm run lint` 检查 TypeScript。
- 使用 `npm run build` 检查生产构建。
- 用 `rg` 确认源码和构建产物不再包含 `CUT MASK` 与 `createCutMaskTexture`。
- 重新部署后从 dev server 拉取源码确认不再存在模型切分帧滑块。
## 预计文件变更
- 修改 `ReverseWorkspace.tsx`。
- 新增本次需求、实现、测试方案文档。
- 追加 `经验记录.md`。
## 人工审核状态
用户已在项目工作流历史中确认后续直接执行，本次不等待二次人工审核。

51
工程分析/实现方案-2026-05-08-03-23-51.md
View File

@@ -1,51 +0,0 @@
# 实现方案：精简导航与切分显示
时间戳：2026-05-08-03-23-51
## 修改目标
删除重复“模型库”入口，简化逆向工作区 DICOM 范围卡片，并去掉模型切分时的红色辅助平面。
## 涉及路径
- `WebSite/src/types.ts`
- `WebSite/src/components/Sidebar.tsx`
- `WebSite/src/App.tsx`
- `WebSite/src/components/ReverseWorkspace.tsx`
- `工程分析/经验记录.md`
## 技术路线
1. 从 `ViewType` 中删除 `MODELS`。
2. 从侧边栏 `menuItems` 中删除“模型库”，并移除不再使用的图标导入。
3. 从 `App.tsx` 中删除 `ViewType.MODELS` 的标题和渲染分支，保留“项目库”中的模型查看能力。
4. 删除 `ReverseWorkspace.tsx` 中 DICOM 范围说明文案、五点预存按钮、预存状态和相关函数。
5. 保留 `fusionVolumeCacheRef`，让初始 `1~最终` 和用户实际访问过的范围自动进入缓存。
6. 删除 `lowerCutPlane/upperCutPlane` Mesh 创建与加入场景逻辑，只保留 `lowerClippingPlane/upperClippingPlane` 用于真实裁切。
## 数据流或交互流程
- 项目入口统一从“项目库”进入。
- 逆向工作区加载项目后默认请求完整 DICOM 范围，返回后写入缓存。
- 启用模型切分后，STL 材质继续使用两张 clipping plane 裁切，不再渲染红色平面。
## 兼容性与回滚方案
- 若用户仍需要独立模型入口，可恢复 `ViewType.MODELS`、侧边栏项和 `App.tsx` 对应分支。
- 若需要切割面可视化，可重新添加半透明辅助平面；本次不影响 clipping plane 逻辑。
## 风险控制
- 使用 `rg` 确认不再存在 `ViewType.MODELS`、`模型库`、`预存五点`、红色切面 Mesh。
- 执行 `npm run lint` 和 `npm run build`。
- 重新部署并从 dev server 拉取源码确认变更生效。
## 预计文件变更
- 修改 4 个前端源码文件。
- 新增 3 个工程分析文档。
- 追加经验记录。
## 人工审核状态
用户已在项目工作流历史中确认后续直接执行，本次不等待二次人工审核。

50
工程分析/实现方案-2026-05-08-03-35-22.md
View File

@@ -1,50 +0,0 @@
# 实现方案：右侧实体切面预览
时间戳：2026-05-08-03-35-22
## 修改目标
在 `Mask 展示` 区域新增真实 STL 切割实体预览组件，替代旧的二维示意 Mask，并删除底部导出进度栏。
## 涉及路径
- `WebSite/src/components/ReverseWorkspace.tsx`
- `工程分析/经验记录.md`
## 技术路线
1. 新增 `CutSectionPreview` 组件。
2. 组件使用 Three.js 渲染 STL preview 顶点数据。
3. 使用 DICOM `physicalSize.depth` 和 `total` 将 `displayStart/displayEnd` 映射到 Z 方向两张 clipping plane。
4. 当“模型切分”启用时，对 STL 材质应用两张 clipping plane，保留中间实体区域；未启用时展示完整实体模型。
5. 复用构件颜色、显示隐藏、模型位姿和高质量实体请求上限。
6. 删除旧 `mappings` 假 Mask 形状、`MaskMapping` 类型引用、`exportMessage` 和底部导出进度栏。
## 数据流或交互流程
- DICOM 范围条更新 `displayStart/displayEnd`。
- `FusionThreeView` 和 `CutSectionPreview` 都接收相同范围。
- `CutSectionPreview` 请求 STL preview，居中、缩放并应用当前模型位姿。
- 启用模型切分后，右侧实体预览显示裁切后的 STL 中间段。
## 兼容性与回滚方案
- 若实体预览性能不满足要求，可降低 `detailLimit` 或回滚到旧 Mask 展示区域。
- 本次不改 API 和数据文件，回滚只涉及前端组件。
## 风险控制
- 使用 `npm run lint` 验证类型。
- 使用 `npm run build` 验证构建。
- 使用 `rg` 确认旧 `导出进度`、`mappings`、假 Mask 结构已移除。
- 重启服务并验证 4000 端口。
## 预计文件变更
- 修改 `ReverseWorkspace.tsx`。
- 新增本次需求、实现、测试文档。
- 追加经验记录。
## 人工审核状态
用户已在项目工作流历史中确认后续直接执行，本次不等待二次人工审核。

55
工程分析/实现方案-2026-05-19-22-59-07.md
View File

@@ -1,55 +0,0 @@
# 实现方案-2026-05-19-22-59-07
## 实现方案文档路径
`工程分析/实现方案-2026-05-19-22-59-07.md`
## 修改目标
建立并固化项目级代码编纂工作流，使后续项目修改必须留下需求分析、实现方案、测试方案、经验记录、备份 commit 与部署验证。
## 涉及路径
- `工程分析/工程整体分析.md`
- `工程分析/代码编纂工作流.md`
- `工程分析/需求分析-2026-05-19-22-59-07.md`
- `工程分析/实现方案-2026-05-19-22-59-07.md`
- `工程分析/测试方案-2026-05-19-22-59-07.md`
- `工程分析/经验记录.md`
- `AGENTS.md`
## 技术路线
1. 记录本次开始时间 `2026-05-19-22-59-07`。
2. 阅读项目 README、`WebSite/README.md`、`package.json`、`server.ts`、API 封装和主要 React 组件。
3. 从 Git 中读取旧 `工程分析/工程整体分析.md`、`代码编纂工作流.md`、`经验记录.md`，保留旧知识库。
4. 恢复并更新三个核心文档，只处理本次必要文件。
5. 新增本次需求分析、实现方案、测试方案。
6. 新增根目录 `AGENTS.md`，提醒后续进入仓库的助手优先执行该工作流。
7. 执行静态检查和构建。
8. 使用 `tmux` 重新部署 `WebSite` 服务到 `0.0.0.0:4000`。
9. 验证 HTTP 健康检查和页面响应。
10. 仅暂存本次相关文档和 `AGENTS.md`，创建包含时间戳和简要描述的 commit，并尝试推送到 Gitea。
## 兼容性与回滚方案
- 本次不修改业务代码，不改变 API、前端页面和运行态数据结构。
- 若文档内容需要回滚，可回退本次 commit。
- 若部署失败，可保留当前代码构建结果，检查 `tmux` 会话日志和端口占用后重新启动。
- 若 Gitea 推送失败，本地 commit 仍保留，可稍后网络恢复后执行 `git push origin main`。
## 预计文件变更
- 更新：`工程分析/工程整体分析.md`
- 更新：`工程分析/代码编纂工作流.md`
- 更新：`工程分析/经验记录.md`
- 新增：`工程分析/需求分析-2026-05-19-22-59-07.md`
- 新增：`工程分析/实现方案-2026-05-19-22-59-07.md`
- 新增：`工程分析/测试方案-2026-05-19-22-59-07.md`
- 新增：`AGENTS.md`
## 提交与部署策略
- 暂存时显式列出本次文件，避免把工作区已有历史删除状态混入 commit。
- commit message 使用：`2026-05-19-22-59-07 建立代码编纂工作流`
- 部署方式沿用项目约定：`tmux` 会话 `revoxelseg-dicom` + `npm run serve -- --host 0.0.0.0 --port 4000`。

57
工程分析/实现方案-2026-05-19-23-47-31.md
View File

@@ -1,57 +0,0 @@
# 实现方案-2026-05-19-23-47-31
## 实现方案文档路径
`工程分析/实现方案-2026-05-19-23-47-31.md`
## 修改目标
将逆向工作区右侧 `Mask 展示` 改造成二维多图层“逆向分割映射视图”，实现 DICOM Base Layer、STL 逆向投影 Overlay Label Map、构件层级属性联动和独立 Slice Navigator。
## 涉及路径
- `WebSite/src/components/ReverseWorkspace.tsx`
- `WebSite/src/index.css`
- `工程分析/需求分析-2026-05-19-23-47-31.md`
- `工程分析/实现方案-2026-05-19-23-47-31.md`
- `工程分析/测试方案-2026-05-19-23-47-31.md`
- `工程分析/经验记录.md`
## 技术路线
1. 在 `ReverseWorkspace.tsx` 中新增独立 `mappingSlice` 状态。
2. 将右侧 `CutSectionPreview` 替换为 `VoxelizationMappingView`。
3. `VoxelizationMappingView` 使用两个叠放 Canvas：
- Base Canvas 绘制 `api.getDicomPreview(project.id, mappingSlice, 'axial', 'soft')` 返回的 DICOM 灰度像素。
- Overlay Canvas 根据 STL preview 顶点、当前切片 Z 位置和 `moduleStyles` 生成 Label Map 投影。
4. Overlay 绘制规则：
- 对每个可见 STL 构件读取颜色、透明度、`partId`。
- 将 STL 顶点 bounds 归一化映射到 DICOM canvas。
- 只绘制与当前 Z 切片带宽相交的三角面。
- 隐藏构件不绘制，透明度随构件层级滑条变化。
5. 在右侧视图底部添加专属 Slice Navigator：
- 独立范围为 `0 ~ project.dicomCount - 1`。
- 支持拖动和左右单步按钮。
- 不修改左侧 DICOM 范围，也不影响三维融合切分状态。
6. 保留 NII/NII.GZ 导出按钮。
7. 为新滑条补充稳定尺寸和样式，避免 UI 抖动。
## 兼容性与回滚方案
- 不修改后端接口和数据结构，回滚时只需恢复 `ReverseWorkspace.tsx` 与 `index.css`。
- 如果 STL preview 加载失败，右侧仍显示 DICOM Base Layer，并显示 Overlay 状态提示。
- 如果 DICOM preview 加载失败，显示加载或错误状态，不影响左侧三维融合视图。
## 预计文件变更
- 更新 `ReverseWorkspace.tsx`：新增二维映射视图、独立切片状态、右侧标题与图层联动。
- 更新 `index.css`：新增独立 Slice Navigator 滑条样式。
- 新增本次三份工程文档。
- 更新 `经验记录.md`。
## 提交与部署策略
- 仅暂存本次代码和文档文件。
- 提交信息使用：`2026-05-19-23-47-31 优化逆向分割映射视图`
- 运行 `npm run lint`、`npm run build`。
- 重新部署 `tmux` 会话 `revoxelseg-dicom`，验证 `http://127.0.0.1:4000/api/health` 和首页响应。

54
工程分析/实现方案-2026-05-20-00-19-47.md
View File

@@ -1,54 +0,0 @@
# 实现方案-2026-05-20-00-19-47
## 实现方案文档路径
`工程分析/实现方案-2026-05-20-00-19-47.md`
## 修改目标
让右侧“逆向分割映射视图”的 Overlay Label Map 实时响应中部模型位姿，并将渲染形态从表面三角面投影升级为闭合实体 Mask 区域填充。
## 涉及路径
- `WebSite/src/components/ReverseWorkspace.tsx`
- `工程分析/需求分析-2026-05-20-00-19-47.md`
- `工程分析/实现方案-2026-05-20-00-19-47.md`
- `工程分析/测试方案-2026-05-20-00-19-47.md`
- `工程分析/经验记录.md`
## 技术路线
1. 在 `VoxelizationMappingView` 新增 `modelPose` 入参，父组件直接传入中部工具栏当前位姿。
2. 新增浏览器端刚性变换函数：
- 以全局 STL bounds 中心归一化顶点。
- 按 `scale -> rotateX -> rotateY -> rotateZ -> translate` 顺序变换。
- 将变换后坐标映射到固定 DICOM Overlay 画布坐标系。
3. 将原先“靠近切片的三角面填充”改为“切片平面求交”：
- 对每个三角面与当前 Z 平面求交。
- 收集切面边界线段。
4. 将边界线段按扫描线射线法光栅化为实心 Mask：
- 逐行收集边界线段与水平扫描线的交点。
- 采用奇偶配对填充闭合区域内部像素。
- 按构件颜色与透明度写入 Overlay ImageData，并通过离屏画布合成，避免多构件互相覆盖。
5. 对边界不完全闭合的极少数抽样场景，使用端点多边形保底填充，避免完全空白。
6. 使用 `requestAnimationFrame` 合并高频位姿变化，做到位姿滑条拖动时实时刷新。
7. 更新右侧状态文案，显示实心 Mask 像素数量和参与构件数量。
## 兼容性与回滚方案
- 不修改后端 API，不影响 DICOM preview、STL preview 和导出接口。
- 如果新填充算法异常，可回退到上一版 `drawVoxelOverlayLayer`。
- 如果某个构件没有形成闭合区域，只影响该构件 Overlay，不影响 Base Layer 和其他构件。
## 预计文件变更
- `ReverseWorkspace.tsx`：新增位姿变换、切面求交、Mask flood fill、Overlay rAF 重绘。
- 新增本次三份工程文档。
- 更新 `经验记录.md`。
## 提交与部署策略
- 执行 `npm run lint` 与 `npm run build`。
- 重新部署 `tmux` 会话 `revoxelseg-dicom`。
- 提交信息：`2026-05-20-00-19-47 同步位姿并填充实体映射`
- 使用已验证的 Gitea 临时凭据方式推送。

67
工程分析/实现方案-2026-05-20-00-38-39.md
View File

@@ -1,67 +0,0 @@
# 实现方案-2026-05-20-00-38-39
## 实现方案文档路径
`工程分析/实现方案-2026-05-20-00-38-39.md`
## 修改目标
将右侧“逆向分割映射视图”的坐标映射改为与左侧“三维融合视图”同源的 DICOM 物理 FOV，并强化 STL Mesh-Plane Intersection 与实体填充，减少尺度错位和截面漏隙。
## 涉及路径
- `WebSite/src/components/ReverseWorkspace.tsx`
- `工程分析/需求分析-2026-05-20-00-38-39.md`
- `工程分析/实现方案-2026-05-20-00-38-39.md`
- `工程分析/测试方案-2026-05-20-00-38-39.md`
- `工程分析/经验记录.md`
## 技术路线
1. 新增统一空间指标计算：
- 从 DICOM `physicalSize.width/height` 和 `spacing.slice` 推导物理深度。
- 复用左侧三维融合视图 `baseExtent=4.6` 的归一化策略。
- 计算 `dicomWidth/dicomHeight/dicomDepth`、当前 slice 对应 Z 坐标、STL bounds 中心和 `modelBaseScale`。
- 左侧三维视图也改为使用全部 STL bounds 作为全局模型尺度，隐藏构件只影响渲染，不再改变全局比例。
2. 修改右侧 STL 顶点变换：
- 按左侧三维层级顺序复现 `modelPivot` 和 `modelPoseGroup`。
- 使用 `modelBaseScale * pose.scale`、旋转、平移和 pivot Z 偏移。
3. 修改右侧画布坐标映射：
- `x` 映射到 `[-dicomWidth/2, dicomWidth/2]`。
- `y` 映射到 `[-dicomHeight/2, dicomHeight/2]`。
- 画布宽高仍为 DICOM preview 像素，物理 FOV 与 Base Layer 完全一致。
4. 提升 Overlay 数据精度：
- 右侧 STL preview 请求改为 `200000` 上限，尽量使用完整网格。
- 继续逐三角面执行 Mesh-Plane Intersection，得到截面线段。
5. 强化实体填充：
- 扫描线收集截面线段交点并进行内部填充。
- 对填充结果做边界外 flood fill，自动补齐内部未填孔洞。
- 使用离屏 canvas 合成每个构件，避免多构件透明区域互相擦除。
## 执行步骤
- 更新右侧空间指标、位姿变换和点到画布映射函数。
- 更新左侧三维视图的模型 bounds 计算，保证构件显隐不改变全局 FOV。
- 更新 STL preview 请求 limit。
- 更新实体填充函数，加入内部孔洞填充。
- 执行 `npm run lint` 和 `npm run build`。
- 重新部署并验证服务。
- 追加经验记录并提交推送。
## 兼容性与回滚方案
- 不改变外部 API 和状态结构。
- 若新 FOV 映射异常，可回退到上一版 `drawVoxelOverlayLayer` 的归一化映射。
- 若最大 STL preview 请求导致性能压力，可降低右侧独立请求 limit，但保留同源 FOV 计算。
## 预计文件变更
- `ReverseWorkspace.tsx`：更新 FOV 坐标、模型变换、填充算法和请求精度。
- 新增本次三份工程文档。
- 更新 `经验记录.md`。
## 提交与部署策略
- 提交信息：`2026-05-20-00-38-39 对齐FOV并强化网格截面填充`
- 显式暂存本次相关文件，避免提交历史删除状态。
- 使用 Gitea origin/main 备份并重新部署 `revoxelseg-dicom`。

56
工程分析/实现方案-2026-05-20-01-08-38.md
View File

@@ -1,56 +0,0 @@
# 实现方案-2026-05-20-01-08-38
## 实现方案文档路径
`工程分析/实现方案-2026-05-20-01-08-38.md`
## 修改目标
优化逆向工作区三栏空间分配，降低左侧三维融合视图宽度并扩大中部可视化工具栏，同时将模型平移步长精细化为 `0.005`。
## 涉及路径
- `WebSite/src/components/ReverseWorkspace.tsx`
- `工程分析/需求分析-2026-05-20-01-08-38.md`
- `工程分析/实现方案-2026-05-20-01-08-38.md`
- `工程分析/测试方案-2026-05-20-01-08-38.md`
- `工程分析/经验记录.md`
## 技术路线
1. 调整逆向工作区桌面端 grid 栅格：
- 左侧 `lg:col-span-7` 改为 `lg:col-span-6`。
- 中部 `lg:col-span-2` 改为 `lg:col-span-3`。
- 右侧保持 `lg:col-span-3`。
2. 修改 `poseStepConfig`：
- `translateX/Y/Z.step` 从 `0.05` 改为 `0.005`。
3. 新增或调整数值精度显示函数：
- 根据 step 自动判断显示位数。
- `0.005` 显示三位小数，旋转仍显示整数，缩放仍显示两位小数。
## 执行步骤
- 修改 `ReverseWorkspace.tsx`。
- 执行 `npm run lint`。
- 执行 `npm run build`。
- 重新部署 `tmux` 服务并验证。
- 更新测试结果与经验记录。
- 显式暂存本次文件并提交推送。
## 兼容性与回滚方案
- 不修改数据结构与 API。
- 如布局不合适，可回退为原 `7 / 2 / 3` 栅格。
- 如 `0.005` 过细，可只回调 `poseStepConfig` 的平移 step。
## 预计文件变更
- `ReverseWorkspace.tsx`：布局栅格、平移步长、数值显示精度。
- 新增本次三份工程文档。
- 更新 `经验记录.md`。
## 提交与部署策略
- 提交信息：`2026-05-20-01-08-38 调整工具栏布局与平移步长`
- 显式暂存本次相关文件，避免提交历史删除状态。
- 推送到 Gitea `origin/main` 并重新部署。

71
工程分析/实现方案-2026-05-20-01-38-33.md
View File

@@ -1,71 +0,0 @@
# 实现方案-2026-05-20-01-38-33
## 实现方案文档路径
`工程分析/实现方案-2026-05-20-01-38-33.md`
## 修改目标
完善逆向工作区导出与位姿持久化：移除自动配准演示入口，新增可选导出 DICOM NIfTI、分割 NIfTI 和位姿 JSON，修复 blob 下载警告，增加三维坐标轴示意，并让保存位姿跨项目进入持久保留。
## 涉及路径
- `WebSite/server.ts`
- `WebSite/src/lib/api.ts`
- `WebSite/src/types.ts`
- `WebSite/src/components/ReverseWorkspace.tsx`
- `工程分析/需求分析-2026-05-20-01-38-33.md`
- `工程分析/实现方案-2026-05-20-01-38-33.md`
- `工程分析/测试方案-2026-05-20-01-38-33.md`
- `工程分析/经验记录.md`
## 技术路线
1. 后端扩展项目状态：
- 增加 `modelPoses` 字段，保存默认、俯视、侧视与用户自定义位姿。
- 新增 `PATCH /api/projects/:projectId/model-poses`。
2. 后端重写导出：
- 新增通用 NIfTI-1 写入函数。
- DICOM 原始影像导出为 int16 HU `.nii.gz`，维度与 spacing 来自 DICOM。
- 分割影像导出为 STL 构件采样切面填充后的 uint8 label map `.nii.gz`，维度与 spacing 与 DICOM 完全一致。
- 位姿数据导出为 JSON，并记录导出时的当前 activePose。
- 保留 `/export-mask` 兼容旧分割导出。
3. 前端下载方式：
- 用直链 `<a href>` 下载替代 `fetch -> Blob -> URL.createObjectURL`。
- 新增导出选项复选框和“导出所选”动作，分割和位姿导出会携带当前模型位姿。
4. UI 调整：
- 去掉“开始自动配准”按钮和相关演示进度状态。
- 顶部按钮改为“导出全部 NII.GZ”。
- 三维融合视角右下角增加固定 XYZ 坐标轴示意。
5. 位姿持久化：
- 项目加载时读取 `project.modelPoses`。
- 保存/重命名位姿时写回后端。
## 执行步骤
- 更新类型定义和后端状态归一化。
- 实现 NIfTI/位姿导出接口。
- 更新前端 API 下载方法。
- 更新 ReverseWorkspace UI、导出选项、位姿保存逻辑和坐标轴。
- 执行 `npm run lint` 与 `npm run build`。
- 验证新导出接口返回文件，重新部署并推送。
## 兼容性与回滚方案
- 旧 `downloadMask` 与 `/export-mask` 保持可用，只把底层分割 NIfTI 改为同维度数据。
- 如果完整 DICOM NIfTI 导出耗时过高，可后续增加范围导出或后台任务。
- 如果浏览器仍对 HTTP 下载提示安全警告，需要部署 HTTPS；本次先消除 blob URL 警告来源。
## 预计文件变更
- `server.ts`：项目位姿字段、DICOM NIfTI 导出、STL Label Map 导出、位姿导出、兼容旧导出。
- `api.ts`：直链下载和导出选项 API。
- `types.ts`：项目位姿类型。
- `ReverseWorkspace.tsx`：移除自动配准、导出选项、坐标轴、位姿持久化。
- 新增本次三份工程文档，更新经验记录。
## 提交与部署策略
- 提交信息：`2026-05-20-01-38-33 完善NII导出与位姿持久化`
- 显式暂存本次相关文件，避免提交历史删除状态。
- 推送到 Gitea `origin/main` 并重新部署。

59
工程分析/实现方案-2026-05-20-02-02-37.md
View File

@@ -1,59 +0,0 @@
# 实现方案-2026-05-20-02-02-37
## 实现方案文档路径
`工程分析/实现方案-2026-05-20-02-02-37.md`
## 修改目标
让“模型位姿”每一项都支持直接数字输入，并新增导入位姿数据功能，兼容当前导出的位姿 JSON，导入后同步当前位姿和保存位姿列表。
## 涉及路径
- `WebSite/src/components/ReverseWorkspace.tsx`
- `工程分析/需求分析-2026-05-20-02-02-37.md`
- `工程分析/实现方案-2026-05-20-02-02-37.md`
- `工程分析/测试方案-2026-05-20-02-02-37.md`
- `工程分析/经验记录.md`
## 技术路线
1. 增加位姿归一化辅助函数：
- 对每个位姿字段按 `poseStepConfig` 执行数字校验、clamp 和默认值补齐。
- 对导入的保存位姿列表补齐默认/俯视/侧视，并去重。
2. 模型位姿数值输入：
- 将原只读数值改成 `<input type="number">`。
- 使用现有 step/min/max/precision。
- 输入合法时立即更新 `modelPose`，继续触发三维与二维映射联动。
3. 导入位姿数据：
- 新增隐藏 file input 与“导入”按钮。
- 读取 JSON，兼容 `{ activePose, modelPoses }`、`{ pose }`、直接 pose 对象三种形式。
- 导入 `modelPoses` 时调用现有 `commitSavedPoses` 持久化。
4. 反馈与容错：
- 导入成功设置提示；导入失败设置 `fusionError`。
- 清空 file input value，允许重复导入同一文件。
## 执行步骤
- 更新 `ReverseWorkspace.tsx` 的 import、ref、辅助函数和 handlers。
- 调整模型位姿 UI，将保存按钮组改为保存/导入两个操作。
- 将数值展示替换为可编辑数字输入。
- 运行 `npm run lint` 与 `npm run build`。
- 重新部署并验证服务。
## 兼容性与回滚方案
- 旧滑条、加减按钮、保存位姿、重命名位姿逻辑继续保留。
- 导入功能只读本地 JSON，不改后端接口。
- 如导入格式异常，只提示错误，不覆盖当前状态。
## 预计文件变更
- `ReverseWorkspace.tsx`：位姿数字输入、导入按钮、JSON 解析与归一化。
- 工程分析文档：新增本次三份文档并追加经验记录。
## 提交与部署策略
- Commit message：`2026-05-20-02-02-37 支持位姿输入与导入`
- 显式暂存本次相关文件，避免提交历史删除状态。
- 推送到 Gitea `origin/main` 后，沿用 `tmux` 会话 `revoxelseg-dicom` 重新部署。

56
工程分析/实现方案-2026-05-20-02-15-10.md
View File

@@ -1,56 +0,0 @@
# 实现方案-2026-05-20-02-15-10
## 实现方案文档路径
`工程分析/实现方案-2026-05-20-02-15-10.md`
## 修改目标
缩小“影像与模型融合视角”右下角 XYZ 标识，并将其从静态 SVG 改为随模型位姿和三维场景旋转联动的方向指示器。
## 涉及路径
- `WebSite/src/components/ReverseWorkspace.tsx`
- `工程分析/需求分析-2026-05-20-02-15-10.md`
- `工程分析/实现方案-2026-05-20-02-15-10.md`
- `工程分析/测试方案-2026-05-20-02-15-10.md`
- `工程分析/经验记录.md`
## 技术路线
1. 新增轴向投影数据结构：
- 定义 X/Y/Z 三个方向在屏幕 inset SVG 中的投影向量。
- 提供默认轴向，避免 DICOM/模型未加载时空白。
2. 改造 `CoordinateAxesInset`：
- 视觉尺寸由 72px 缩小到约 54px。
- 线段终点、标签位置和透明度由投影数据驱动。
3. 在 `FusionThreeView` 中计算动态方向：
- 在 Three.js animation loop 中让 `fusionRoot` 和 `modelPoseGroup` 更新矩阵。
- 读取 `modelPoseGroup.getWorldPosition()` 与 `getWorldQuaternion()`。
- 将模型局部 X/Y/Z 方向投影到当前 camera 屏幕空间。
- 仅在投影签名变化时更新 React 状态，减少无意义重渲染。
## 执行步骤
- 增加 AxisProjection 类型、默认值和投影辅助函数。
- 改造坐标轴 inset 的 SVG 尺寸和绘制逻辑。
- 在融合视图动画中调用投影计算并传给 inset。
- 执行 `npm run lint` 和 `npm run build`。
- 追加经验记录、提交、推送并重新部署。
## 兼容性与回滚方案
- 如果动态投影出现异常，默认轴向仍可显示。
- 不修改 DICOM/STL 真实数据、模型位姿状态和实际渲染变换，仅增加可视化辅助。
- 回滚只需恢复 `CoordinateAxesInset` 为静态 SVG。
## 预计文件变更
- `ReverseWorkspace.tsx`：动态坐标轴投影与缩小样式。
- 工程分析文档：新增本次三份文档，更新经验记录。
## 提交与部署策略
- Commit message：`2026-05-20-02-15-10 优化融合视角方向标识`
- 显式暂存本次相关文件，避免提交历史删除状态。
- 推送到 Gitea `origin/main`，并使用 `tmux` 会话 `revoxelseg-dicom` 重新部署。

68
工程分析/实现方案-2026-05-20-02-32-47.md
View File

@@ -1,68 +0,0 @@
# 实现方案-2026-05-20-02-32-47
## 实现方案文档路径
`工程分析/实现方案-2026-05-20-02-32-47.md`
## 修改目标
将顶部“导出全部 NII.GZ”改为一次性下载 `.tar.gz` 导出包；分割影像导出时自动附带 label/category 映射 JSON，并支持“所有类别/可见类别”范围选择。
## 涉及路径
- `WebSite/server.ts`
- `WebSite/src/lib/api.ts`
- `WebSite/src/components/ReverseWorkspace.tsx`
- `工程分析/需求分析-2026-05-20-02-32-47.md`
- `工程分析/实现方案-2026-05-20-02-32-47.md`
- `工程分析/测试方案-2026-05-20-02-32-47.md`
- `工程分析/经验记录.md`
## 技术路线
1. 后端扩展分割生成参数：
- 增加 `SegmentationExportScope = all | visible`。
- `createSegmentationData` 按 scope 决定是否跳过隐藏构件。
2. 后端新增类别映射 JSON：
- 根据 `project.stlFiles` 和 `project.moduleStyles` 生成 label/name/fileName/color/opacity/visible。
- scope 为 visible 时只包含可见构件。
3. 后端新增导出包接口：
- `GET /api/projects/:projectId/export-bundle`
- 参数：`targets=dicom,segmentation,pose`、`format=nii.gz`、`pose=...`、`segmentationScope=visible|all`
- 使用现有 tar header 工具封装为 `.tar.gz`。
4. 前端 API：
- 新增 `downloadProjectExportBundle`。
- 保留单个分割 NII/NII.GZ 下载兼容。
5. 前端菜单：
- “导出所选”改为下载单个压缩包。
- 增加分割类别范围的 segmented control。
- 仅选中分割影像时显示类别范围选项。
## 执行步骤
- 新增后端 tar entry 通用函数和 bundle 生成函数。
- 修改 NIfTI 分割生成函数支持 scope。
- 新增 label map JSON 生成逻辑。
- 调整前端 API 和导出菜单。
- 执行 `npm run lint`、`npm run build`。
- 用临时/正式服务验证 bundle 接口返回 `.tar.gz`，并检查包内文件名。
- 追加经验记录、commit、push、部署。
## 兼容性与回滚方案
- `/export-nifti` 与 `/export-mask` 保持可用。
- 单独分割导出默认沿用 visible scope。
- 若 bundle 导出异常，可回滚到多文件直链下载。
## 预计文件变更
- `server.ts`：新增 bundle、分割 scope、类别映射 JSON。
- `api.ts`：新增 bundle 下载 API。
- `ReverseWorkspace.tsx`：导出菜单增加 scope 选择并调用 bundle。
- 工程分析文档：新增本次文档，更新经验记录。
## 提交与部署策略
- Commit message：`2026-05-20-02-32-47 支持NII导出包与分割类别范围`
- 显式暂存本次相关文件，避免提交历史删除状态。
- 推送到 Gitea `origin/main`，并使用 `tmux` 会话 `revoxelseg-dicom` 重新部署。

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

@@ -1,51 +0,0 @@
# 实现方案：完整 STL 网格导出与实体填充增强
实现方案文档路径：`工程分析/实现方案-2026-05-20-02-55-11.md`
## 修改目标
修复大面数 STL 构件导出后在 ITK-SNAP 中呈散点的问题，使分割 NIfTI 的 Label Map 基于完整二进制 STL 三角面求交，并在每层生成连续实体区域。
## 涉及路径
- `WebSite/server.ts`
- `工程分析/需求分析-2026-05-20-02-55-11.md`
- `工程分析/实现方案-2026-05-20-02-55-11.md`
- `工程分析/测试方案-2026-05-20-02-55-11.md`
- `工程分析/经验记录.md`
## 技术路线
1. 保留 `createStlPreview` 作为网页预览和 bounds 统计来源。
2. 新增导出专用 STL 迭代逻辑，直接读取完整二进制 STL buffer 中的全部三角面，不再使用 `sampleLimit=200000` 的预览顶点数组作为 NIfTI 生成输入。
3. 对每个三角面执行当前位姿变换、DICOM 物理坐标映射、Mesh-Plane Intersection 和扫描线光栅化。
4. 将每个构件、每个 slice 的 rows 光栅化到临时 mask，再做四边 flood fill，填补闭合区域内部孔洞后写入最终 Label Map。
5. 保持 `visible/all` 分割范围、labels JSON、导出包结构不变。
## 执行步骤
1. 阅读当前导出生成链路，确认抽样来源和填充缺口。
2. 编写完整 STL 三角面读取辅助函数，避免长期缓存完整顶点数组。
3. 替换 `createSegmentationData` 中遍历 `payload.vertices` 的逻辑。
4. 增强后端 slice mask 的内部孔洞填补。
5. 运行类型检查、构建、导出接口验证。
6. 用脚本检查导出的 Label Map 体素分布，重点确认 `头部` label 不再只集中于少量散点。
7. 追加经验记录、提交、推送并重新部署。
## 兼容性与回滚方案
- API 参数和前端调用不变，外部使用者无需调整。
- 若完整 STL 导出耗时不可接受，可在后续引入后台任务或空间索引；本次先保证导出结果正确。
- 回滚时可恢复到上一个提交，但会重新暴露大面数构件抽样导致的散点问题。
## 预计文件变更
- `WebSite/server.ts`：新增完整 STL 迭代与 slice mask 填充逻辑。
- `工程分析/*-2026-05-20-02-55-11.md`：记录本次工作流。
- `工程分析/经验记录.md`：追加 A/B/C/D 经验。
## 提交与部署策略
- 只暂存本次相关代码和工程分析文档。
- commit message 包含 `2026-05-20-02-55-11` 和简要描述。
- 推送到 Gitea 后使用 `tmux` 会话 `revoxelseg-dicom` 重新部署。

62
工程分析/实现方案-2026-05-20-03-19-25.md
View File

@@ -1,62 +0,0 @@
# 实现方案：导出与项目库分割结果闭环
实现方案文档路径：`工程分析/实现方案-2026-05-20-03-19-25.md`
## 修改目标
补齐原始 STL 导出、分割结果保存到项目库、项目库复用导出包功能、工作区布局与右侧构件提示优化，并新增系统使用说明 `Agent.md`。
## 涉及路径
- `WebSite/server.ts`
- `WebSite/src/types.ts`
- `WebSite/src/lib/api.ts`
- `WebSite/src/components/ReverseWorkspace.tsx`
- `WebSite/src/components/ProjectLibrary.tsx`
- `Agent.md`
- `工程分析/需求分析-2026-05-20-03-19-25.md`
- `工程分析/实现方案-2026-05-20-03-19-25.md`
- `工程分析/测试方案-2026-05-20-03-19-25.md`
- `工程分析/经验记录.md`
## 技术路线
1. 后端导出目标新增 `stl`，在 `/export-bundle` 中将 `Head_CT_ReConstruct` 下的原始 STL 文件写入同一个 tar.gz。
2. 项目状态新增 `segmentationResults`，保存当前分割结果的名称、时间、位姿、分割范围与构件样式快照。
3. 新增 `POST /api/projects/:projectId/segmentation-results`，供逆向工作区 `保存至项目库` 调用。
4. 项目库 `分割结果` 视图读取保存记录，并提供与逆向工作区一致的导出内容选择、分割范围选择和压缩包下载。
5. 将默认/推荐位姿加入前后端默认位姿列表，逆向工作区加载项目时优先选择 `最佳位姿`。
6. 工作区三栏布局从 `6/3/3` 调整为更偏向工具栏与映射视图的比例，压缩左侧融合视角。
7. `OverlayStats` 增加当前 slice 的构件明细，图例仅显示当前切片中实际有边或像素的构件，并用紧凑表格呈现。
8. 编写 `Agent.md`，包含系统使用方式和 500~1300 字主要功能说明。
## 执行步骤
1. 增加类型定义和后端状态归一化。
2. 扩展导出包生成逻辑与 API 参数解析。
3. 增加项目库保存接口与前端 API。
4. 修改逆向工作区按钮、布局、右侧图例。
5. 修改项目库分割结果区域和导出菜单。
6. 编写 `Agent.md`。
7. 运行 lint、build、接口导出验证、保存接口验证、部署验证。
8. 追加经验记录、提交、推送、重新部署。
## 兼容性与回滚方案
- 原有导出目标 `dicom/segmentation/pose` 保持兼容。
- `stl` 为新增可选目标，默认可不选以避免包过大。
- 旧项目没有 `segmentationResults` 时归一化为空数组。
- 回滚到上一提交会移除项目库保存结果和 STL 导出选项，但不影响原始医学数据。
## 预计文件变更
- 后端状态、导出和保存接口。
- 前端 API、类型、逆向工作区与项目库 UI。
- 新增 `Agent.md`。
- 工程分析与经验记录。
## 提交与部署策略
- 只暂存本次相关文件。
- commit message 包含 `2026-05-20-03-19-25` 和简要说明。
- 推送 Gitea 后使用 `tmux` 会话 `revoxelseg-dicom` 重启服务并验证。

52
工程分析/实现方案-2026-05-20-11-07-27.md
View File

@@ -1,52 +0,0 @@
# 实现方案：取消最佳位姿与软著材料生成
实现方案文档路径：`工程分析/实现方案-2026-05-20-11-07-27.md`
## 修改目标
修正产品逻辑，取消“最佳位姿”的默认位姿和优先加载行为；按 `※撰写Agent.md` 流程生成软著材料到 `新撰写软著文档/`，且软著材料不提交到 Gitea。
## 涉及路径
- `WebSite/server.ts`
- `WebSite/src/components/ReverseWorkspace.tsx`
- `新撰写软著文档/`
- `工程分析/需求分析-2026-05-20-11-07-27.md`
- `工程分析/实现方案-2026-05-20-11-07-27.md`
- `工程分析/测试方案-2026-05-20-11-07-27.md`
- `工程分析/经验记录.md`
## 技术路线
1. 后端 `defaultModelPoses()` 移除 `best/最佳位姿` 默认项。
2. 前端 `ReverseWorkspace` 移除 `headCtBestPose` 与 `defaultSavedPoses` 中的最佳位姿，并取消加载项目时优先选择最佳位姿/位姿2的逻辑，恢复默认位姿优先。
3. 读取 `参考软著构建模板/` 三份样例，学习章节结构、登记表字段和代码汇总格式。
4. 分析 README、前后端入口、核心页面、导出与体素化逻辑，整理软著说明书、登记表和代码汇总。
5. 创建 `新撰写软著文档/`，写入三份 Markdown、系统使用视频脚本/分镜、素材清单。
6. 优先使用 Pandoc 生成 docx；若 Pandoc 不存在，则尝试使用 `python-docx` 或 LibreOffice 可行方案。
7. 运行 lint、build、部署验证。
8. 工程分析和代码修正提交到 Git/Gitea；软著输出目录不暂存、不提交。
## 兼容性与回滚方案
- 取消最佳位姿不影响用户已保存的自定义位姿。
- 如用户后续需要导入 `head-ct-demo-pose-data.json`，仍可通过位姿导入入口使用。
- 回滚代码提交可恢复最佳位姿逻辑，但与用户当前要求相反。
## 预计文件变更
- 修改：
- `WebSite/server.ts`
- `WebSite/src/components/ReverseWorkspace.tsx`
- `工程分析/经验记录.md`
- 新增：
- 本次工程分析三份文档。
- `新撰写软著文档/` 下软著交付材料（不提交）。
## 提交与部署策略
- Git 仅暂存代码修正和工程分析文档。
- 不暂存 `新撰写软著文档/`、`head-ct-demo-pose-data.json`、`※撰写Agent.md` 等软著素材。
- commit message 包含 `2026-05-20-11-07-27` 和简要描述。
- 推送 Gitea 若网络不可达，记录失败原因并保留本地 commit。
- 重新部署项目并验证服务。

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

@@ -1,68 +0,0 @@
# 实现方案：软著说明书图文化与代码汇总扩容
实现方案文档路径：`工程分析/实现方案-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 后执行或确认当前服务部署健康。

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

@@ -1,60 +0,0 @@
# 实现方案：默认医学数据资产入库
实现方案文档路径：`工程分析/实现方案-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`。

70
工程分析/实现方案-2026-05-20-12-09-47.md
View File

@@ -1,70 +0,0 @@
# 实现方案：说明书逐章配图与系统视频生成
实现方案文档路径：`工程分析/实现方案-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` 并验证服务。

64
工程分析/实现方案-2026-05-20-12-29-06.md
View File

@@ -1,64 +0,0 @@
# 实现方案：完整页面截图替换与下载内容核查
实现方案文档路径：`工程分析/实现方案-2026-05-20-12-29-06.md`
## 修改目标
把软著说明书每个章节配图替换为未裁剪的完整页面截图，并核查说明书中涉及下载、导出和文件保存的内容。
## 涉及路径
- `新撰写软著文档/1. 软著说明书.md`
- `新撰写软著文档/1. 软著说明书.docx`
- `新撰写软著文档/images/chapter-*.png`
- `新撰写软著文档/功能验证与素材清单.md`
- `工程分析/需求分析-2026-05-20-12-29-06.md`
- `工程分析/实现方案-2026-05-20-12-29-06.md`
- `工程分析/测试方案-2026-05-20-12-29-06.md`
- `工程分析/经验记录.md`
## 技术路线
1. 使用全文搜索定位说明书中的“下载”“导出”“保存”“NII.GZ”等相关表述。
2. 使用 Chrome DevTools Protocol 自动化打开系统并截取完整视口截图。
3. 对登录、总体概况、项目库、DICOM、STL、分割结果、逆向工作区、导出选项、系统管理、退出等章节生成对应完整图。
4. 保持 Markdown 图片引用路径不变，仅覆盖图片文件内容。
5. 重新生成 `1. 软著说明书.docx`，保证 23 张图片嵌入 Word。
6. 更新素材清单，标注图片为完整页面截图。
## 执行步骤
- 检查当前服务是否可访问。
- 运行自动化截图脚本生成 23 张完整页面截图。
- 对 DICOM 信息截图做必要脱敏。
- 重新生成 Word。
- 验证章节数、图片数、图片尺寸、Word 媒体数量和下载相关文本命中结果。
- 构建与重新部署项目。
- 提交工程分析文档与经验记录并推送到 Gitea。
## 兼容性与回滚方案
- 若某个截图失败，可重新运行自动化截图脚本覆盖对应图片。
- 若 Word 生成失败，保留 Markdown 和图片，可再次用 `python-docx` 生成。
- 若下载相关内容需要后续删除，可基于本轮搜索结果进一步调整说明书正文。
## 预计文件变更
本地软著材料：
- `新撰写软著文档/images/chapter-*.png`
- `新撰写软著文档/1. 软著说明书.docx`
- `新撰写软著文档/功能验证与素材清单.md`
Gitea 备份：
- 本轮工程分析三份文档。
- `工程分析/经验记录.md`。
## 提交与部署策略
- 不提交 `新撰写软著文档/`。
- 不提交 `head-ct-demo-pose-data.json`。
- 仅暂存本轮工程分析文档与经验记录。
- commit message 包含 `2026-05-20-12-29-06`。
- 重新部署后验证 `/api/health` 和首页。

79
工程分析/实现方案-2026-05-20-14-19-23.md
View File

@@ -1,79 +0,0 @@
# 实现方案：逆向分割结果单结果化与入口统一
实现方案文档路径：`工程分析/实现方案-2026-05-20-14-19-23.md`
## 修改目标
调整项目库与逆向工作区的逆向分割结果保存、展示、读取和导出交互，使结果只保留一个、命名统一、入口集中、退出有保存提醒。
## 涉及路径
- `WebSite/src/App.tsx`
- `WebSite/src/components/ProjectLibrary.tsx`
- `WebSite/src/components/ReverseWorkspace.tsx`
- `WebSite/src/types.ts`
- `WebSite/src/lib/api.ts`
- `WebSite/server.ts`
- `工程分析/需求分析-2026-05-20-14-19-23.md`
- `工程分析/实现方案-2026-05-20-14-19-23.md`
- `工程分析/测试方案-2026-05-20-14-19-23.md`
- `工程分析/经验记录.md`
## 技术路线
1. 后端保存分割结果接口改为覆盖保存，只保留最新一条记录。
2. 项目归一化时保留最新一条 `segmentationResults`，兼容旧状态中已有多条记录。
3. 扩展 `SegmentationResult` 存储必要的切片范围、当前映射切片、显示/融合配置等上下文，用于重新进入工作区恢复。
4. 逆向工作区加载项目时读取最新保存结果，恢复位姿、构件样式、分割范围和映射切片。
5. `App.tsx` 接入工作区离开保护：离开逆向工作区时调用工作区注册的保存确认逻辑。
6. 项目库页签改名为“逆向分割结果”，内容改为两张视图预览卡片和右侧导出面板。
7. 顶部导出文案统一改为“导出项目及结果”，并将保存按钮移动到旁边。
8. 删除映射视图标题旁边的 `NII`、`NII.GZ` 小下载按钮。
9. 保存成功后显示顶部悬浮提示并渐隐消失。
## 执行步骤
- 阅读现有类型、API、后端保存接口、项目库和逆向工作区组件结构。
- 更新类型定义与后端归一化/保存逻辑。
- 更新 API payload 和前端保存调用。
- 更新项目库 UI 与导出按钮文案。
- 更新逆向工作区顶部操作区和映射视图标题区。
- 接入退出保存确认和进入工作区结果恢复。
- 运行类型/构建检查、服务部署验证。
## 兼容性与回滚方案
- 后端归一化兼容旧的多条 `segmentationResults`，只取最后一条作为当前结果。
- 若保存上下文字段缺失，前端继续使用默认位姿、默认切片范围和默认显示配置。
- 若导出按钮菜单异常，可继续调用现有 `/api/projects/:projectId/export-bundle` 后端接口。
## 预计文件变更
程序文件：
- `WebSite/src/App.tsx`
- `WebSite/src/components/ProjectLibrary.tsx`
- `WebSite/src/components/ReverseWorkspace.tsx`
- `WebSite/src/types.ts`
- `WebSite/src/lib/api.ts`
- `WebSite/server.ts`
工程分析：
- 本轮三份分析文档。
- `工程分析/经验记录.md`。
## 提交与部署策略
- 暂存本轮程序改动与工程分析文档。
- 避免提交软著材料、运行态导出文件、旧历史文档删除状态。
- commit message 包含 `2026-05-20-14-19-23`。
- 构建通过后重启 `tmux` 会话 `revoxelseg-dicom` 并验证服务。
## 实际实现记录
- 后端 `segmentationResults` 归一化改为只保留最新一条，并扩展保存切片、显示、边界与切割状态字段。
- 导出接口默认使用最新保存结果的位姿、构件样式和类别范围。
- 逆向工作区进入时恢复最新保存结果，退出时注册保存确认守卫。
- 项目库“逆向分割结果”改为两张预览图加右侧统一导出面板。
- 顶部保存按钮迁移到导出按钮旁，并加入保存成功悬浮渐隐提示。

83
工程分析/实现方案-2026-05-20-14-53-31.md
View File

@@ -1,83 +0,0 @@
# 实现方案：逆向结果复核增强与管理功能修复
实现方案文档路径：`工程分析/实现方案-2026-05-20-14-53-31.md`
## 修改目标
增强项目库逆向分割结果的复核交互，补齐逆向工作区映射视图 DICOM 控制，优化离开保存提示逻辑，修复起始页标题和系统管理用户操作。
## 涉及路径
- `WebSite/src/App.tsx`
- `WebSite/src/components/Login.tsx`
- `WebSite/src/components/ProjectLibrary.tsx`
- `WebSite/src/components/ReverseWorkspace.tsx`
- `WebSite/src/components/UserManagement.tsx`
- `WebSite/src/lib/api.ts`
- `WebSite/src/types.ts`
- `WebSite/server.ts`
- `工程分析/需求分析-2026-05-20-14-53-31.md`
- `工程分析/实现方案-2026-05-20-14-53-31.md`
- `工程分析/测试方案-2026-05-20-14-53-31.md`
- `工程分析/经验记录.md`
## 技术路线
1. 检查登录页、主入口、项目库、逆向工作区和用户管理现有实现。
2. 后端项目状态归一化时默认项目不再继承旧保存结果，确保初始逆向分割结果为空。
3. 项目库逆向分割结果页复用 `NativeStlViewer` 提供可拖拽融合视图，固定精细模型显示和 DICOM 高融合语义；DICOM+分割卡片加入横向 Slice Navigator、DICOM 显示模式和旋转控制。
4. 逆向工作区给映射视图加入 DICOM 显示模式与旋转状态，并用该状态请求/渲染预览。
5. 逆向工作区保存后建立状态快照，只有当前可视化工具栏状态与快照不同才注册离开确认；确认文本改成单行语义。
6. 起始页标题顺序调整；根地址访问时按最初起始页处理共享会话。
7. 用户管理前后端补齐新增/更新/删除接口能力，前端禁止删除当前用户。
8. 运行类型检查、构建、服务部署与接口验证。
## 执行步骤
- 阅读相关源码与 API 封装。
- 编写项目状态、API 与用户管理后端补丁。
- 编写项目库和逆向工作区 UI/交互补丁。
- 修复登录页标题与主入口初始会话策略。
- 更新测试方案实际执行记录和经验记录。
- 精确暂存本轮文件，提交并推送 Gitea。
## 兼容性与回滚方案
- 旧项目若已有保存结果，保留用户保存结果；默认演示项目初始状态按空结果处理。
- 用户管理新增接口只操作 `WebSite/data/state.json` 中用户列表，不影响 DICOM/STL 原始数据。
- 若项目库预览异常，仍可进入逆向工作区重新保存结果并导出。
## 预计文件变更
程序文件：
- `WebSite/src/App.tsx`
- `WebSite/src/components/Login.tsx`
- `WebSite/src/components/ProjectLibrary.tsx`
- `WebSite/src/components/ReverseWorkspace.tsx`
- `WebSite/src/components/UserManagement.tsx`
- `WebSite/src/lib/api.ts`
- `WebSite/src/types.ts`
- `WebSite/server.ts`
工程分析：
- 本轮三份分析文档。
- `工程分析/经验记录.md`。
## 提交与部署策略
- 暂存本轮程序改动与工程分析文档。
- 避免提交软著材料、历史删除状态和运行态导出文件。
- commit message 包含 `2026-05-20-14-53-31`。
- 构建通过后重启 `tmux` 会话 `revoxelseg-dicom`，验证 4000 端口服务。
## 实际实现记录
- 项目库逆向分割结果页新增结果 DICOM 显示模式、旋转控制和横向 Slice Navigator。
- 项目库融合视角改为可拖拽结果位姿预览，并固定使用精细模型语义。
- 后端分割结果记录增加 `schemaVersion`，过滤旧演示结果，默认项目初始结果为空；新保存结果继续持久化。
- 逆向工作区映射视图新增默认/骨窗/软组织/高对比和左转/右转控制。
- 逆向工作区新增保存快照判断，仅在保存相关状态变化后离开才弹窗。
- 根页面启动时清理共享会话，显示起始登录页；登录页标题改为全称在上、简称在下。
- 系统管理补齐用户新增、编辑、改密、删除接口和前端表单，并禁止删除当前登录用户。

55
工程分析/实现方案-2026-05-20-15-20-15.md
View File

@@ -1,55 +0,0 @@
# 实现方案：复用逆向工作区真实视图与拆分密码编辑
实现方案文档路径：`工程分析/实现方案-2026-05-20-15-20-15.md`
## 修改目标
让项目库逆向分割结果页直接复用逆向工作区的三维融合和二维映射视图，实现显示效果一致；同时细化用户编辑弹窗，分离资料编辑和密码修改。
## 涉及路径
- `WebSite/src/components/ProjectLibrary.tsx`
- `WebSite/src/components/ReverseWorkspace.tsx`
- `WebSite/src/components/UserManagement.tsx`
- `工程分析/需求分析-2026-05-20-15-20-15.md`
- `工程分析/实现方案-2026-05-20-15-20-15.md`
- `工程分析/测试方案-2026-05-20-15-20-15.md`
- `工程分析/经验记录.md`
## 技术路线
1. 将逆向工作区内部 `FusionThreeView`、`VoxelizationMappingView`、`displayOptions`、`dicomOpacityOptions` 导出为可复用对象。
2. 项目库逆向结果页新增 fusion volume 状态和加载逻辑，按保存结果的切片范围请求 `api.getDicomFusionVolume`。
3. 项目库结果页替换简化 `NativeStlViewer` 和静态 DICOM Canvas，改为直接渲染 `FusionThreeView` 与 `VoxelizationMappingView`。
4. 保留项目库二维映射视图的 DICOM 模式、旋转和 Slice Navigator 控制，将状态传入复用组件。
5. 用户管理表单增加字段标签；编辑模式移除密码输入框；密码模式使用新密码/确认新密码双输入校验。
6. 运行类型检查、构建、部署和接口验证。
## 执行步骤
- 阅读当前项目库和逆向工作区视图组件。
- 调整逆向工作区组件导出。
- 更新项目库视图导入、fusion volume 加载和 JSX 结构。
- 更新用户管理弹窗表单和校验。
- 更新测试记录、经验记录。
- 精确暂存、提交并推送 Gitea。
## 兼容性与回滚方案
- 如果项目库 fusion volume 加载失败，复用组件仍显示原有错误/空状态。
- 逆向工作区原组件调用方式保持不变，只增加导出能力。
- 用户密码后端接口保持不变，前端只增加确认密码约束。
## 预计文件变更
- `WebSite/src/components/ProjectLibrary.tsx`
- `WebSite/src/components/ReverseWorkspace.tsx`
- `WebSite/src/components/UserManagement.tsx`
- 本轮工程分析文档与 `工程分析/经验记录.md`
## 提交与部署策略
- 暂存本轮相关代码和工程分析文档。
- 不提交软著材料、历史删除状态、运行态导出文件。
- commit message 包含 `2026-05-20-15-20-15`。
- 构建通过后重启 `tmux` 会话 `revoxelseg-dicom` 并验证服务。

51
工程分析/实现方案-2026-05-20-15-33-38.md
View File

@@ -1,51 +0,0 @@
# 实现方案：右侧竖向 Slice Navigator 与影像遮挡治理
实现方案文档路径：`工程分析/实现方案-2026-05-20-15-33-38.md`
## 修改目标
调整逆向分割映射视图布局：将切片导航从影像底部迁移到右侧竖向栏，并把 Overlay Label Map 的构件统计面板从影像内部移到影像下方，避免遮挡 DICOM 影像。
## 涉及路径
- `WebSite/src/components/ReverseWorkspace.tsx`
- `工程分析/需求分析-2026-05-20-15-33-38.md`
- `工程分析/实现方案-2026-05-20-15-33-38.md`
- `工程分析/测试方案-2026-05-20-15-33-38.md`
- `工程分析/经验记录.md`
## 技术路线
1. 定位 `VoxelizationMappingView` 中当前底部 `Slice Navigator` 与影像内 Overlay 状态面板。
2. 将组件整体布局改为横向网格：左侧影像与独立信息区，右侧竖向切片导航栏。
3. 保留顶部 `Base DICOM`、`Overlay Label Map`、`Z` 状态标签，但缩小为影像角落提示，避免大面积遮挡。
4. 将构件统计列表改为影像下方独立面板，显示当前 Overlay 状态、构件数、边数、像素数和当前切片构件表。
5. 为竖向 range 增加内联样式或类名，使用 `writingMode: 'vertical-rl'` 与 `direction: 'rtl'` 实现从上到下浏览切片。
6. 执行类型检查、构建、部署验证。
## 执行步骤
- 阅读当前 `VoxelizationMappingView` JSX 与相关样式。
- 修改布局结构和样式。
- 检查 `mapping-slice-input` 是否有全局 CSS 影响，必要时增加独立竖向类。
- 运行 `npm run lint` 和 `npm run build`。
- 重启 `tmux` 服务并验证健康接口和首页。
- 更新测试方案与经验记录。
- 精确暂存、提交并推送 Gitea。
## 兼容性与回滚方案
- 该改动只影响前端布局，不改变数据结构和 API。
- 如竖向 `range` 在某浏览器显示异常，可回滚为右侧竖排按钮加数值输入，或补充 WebKit 专用 CSS。
- 项目库复用同一组件，因此无需额外复制样式逻辑。
## 预计文件变更
- `WebSite/src/components/ReverseWorkspace.tsx`
- 本轮工程分析文档与 `工程分析/经验记录.md`
## 提交与部署策略
- 暂存本轮相关代码和工程分析文档。
- commit message 包含 `2026-05-20-15-33-38`。
- 推送 Gitea 后重启 `revoxelseg-dicom` 服务，验证 `http://127.0.0.1:4000/api/health` 与首页。

65
工程分析/实现方案-2026-05-20-15-54-46.md
View File

@@ -1,65 +0,0 @@
# 实现方案：逆向工作区控件外置、视图复位与手动拉伸
实现方案文档路径：`工程分析/实现方案-2026-05-20-15-54-46.md`
## 修改目标
优化逆向工作区整体布局和交互：右侧二维映射控件白底外置，支持缩放/平移/复位；左侧三维融合视图支持复位；主布局给右侧更多空间并底部对齐；位姿工具栏新增受角度约束的模型等比例拉伸。
## 涉及路径
- `WebSite/src/components/ReverseWorkspace.tsx`
- `WebSite/src/index.css`
- `工程分析/需求分析-2026-05-20-15-54-46.md`
- `工程分析/实现方案-2026-05-20-15-54-46.md`
- `工程分析/测试方案-2026-05-20-15-54-46.md`
- `工程分析/经验记录.md`
## 技术路线
1. 调整逆向工作区主网格比例，左侧略窄，右侧加宽；统一设置三列拉伸高度，减少底部错位。
2. 改造 `VoxelizationMappingView`：
- 顶部图层状态改成白底信息条；
- 右侧 `DICOM 切片位置` 控件改成白底卡片，风格接近 `DICOM 切片范围`；
- 保留竖向切片条并外置于影像右侧；
- 添加滚轮缩放、鼠标拖拽平移和“位置重置”按钮；
- Base DICOM 与 Overlay Canvas 共用同一 transform。
3. 改造 `FusionThreeView`：
- 新增 `viewResetToken` 属性；
- 在 Three.js 场景内部保存 camera/controls 引用，token 变化时恢复相机初始位置；
- 在视图右侧或角落添加“位置重置”按钮入口。
4. 位姿工具栏新增模型等比例拉伸按钮：
- 判断 `rotateX/Y/Z` 是否均为 90 度整数倍；
- 在可用时提供 X/Y/Z 方向拉伸按钮；
- 拉伸仅调整 `modelPose.scale`，作为手动校正，不默认自动执行。
5. 保持保存快照和导出语义使用现有 `modelPose.scale`，不新增后端结构。
6. 运行 lint/build，部署验证，并提交 Gitea。
## 执行步骤
- 阅读 `ReverseWorkspace.tsx` 中主布局、`FusionThreeView`、`VoxelizationMappingView`、位姿工具栏实现。
- 修改二维映射视图布局和交互状态。
- 修改三维融合视图复位接口和按钮。
- 修改主布局比例和位姿拉伸按钮。
- 运行 `npm run lint` 与 `npm run build`。
- 重新部署 `tmux` 服务并验证健康接口和首页。
- 更新测试方案与经验记录。
- 精确暂存本轮相关文件，commit 并推送 Gitea。
## 兼容性与回滚方案
- 二维缩放和平移仅影响 CSS transform，可直接回滚到原 `rotation` transform。
- 三维复位按钮只触发相机状态，不改变数据，可安全移除。
- 手动拉伸只复用既有 `scale` 字段，不改变保存结果结构；若用户需要按轴非等比例拉伸，可后续新增独立 scaleX/Y/Z 字段。
## 预计文件变更
- `WebSite/src/components/ReverseWorkspace.tsx`
- `WebSite/src/index.css`
- 本轮工程分析文档与 `工程分析/经验记录.md`
## 提交与部署策略
- 暂存本轮相关代码和工程分析文档。
- commit message 包含 `2026-05-20-15-54-46`。
- 推送到 Gitea 后重新部署并验证 `http://127.0.0.1:4000/api/health` 与首页。

58
工程分析/实现方案-2026-05-20-21-25-19.md
View File

@@ -1,58 +0,0 @@
# 实现方案-2026-05-20-21-25-19
## 实现方案文档路径
`工程分析/实现方案-2026-05-20-21-25-19.md`
## 修改目标
1. 优化项目库“逆向分割结果”中的三维融合视图默认/复位视角，使复位后呈现用户示意的正向融合观察效果。
2. 为 `VoxelizationMappingView` 增加项目库紧凑展示模式，去掉无意义标签，把窗宽按钮、复位按钮、视图标题、DICOM 切片位置和竖向导航重新布局。
3. 调整项目库结果区左右面板高度与底部对齐。
4. 为逆向工作区增加加载中页面，展示加载进度、加载速度和当前阶段，数据未就绪时不显示完整工作区。
5. 增加 DICOM 融合体与 STL 预览数据的内存缓存，减少跨模块返回后的重复加载。
## 涉及路径
- `WebSite/src/components/ReverseWorkspace.tsx`
- `WebSite/src/components/ProjectLibrary.tsx`
- `WebSite/src/index.css`
- `工程分析/经验记录.md`
## 技术路线
- 在 `ReverseWorkspace.tsx` 中增加模块级缓存 Map，用于缓存 DICOM fusion volume、STL preview、映射视图预览数据。
- 为 `FusionThreeView` 增加 `variant` 或复位视角参数，项目库复用同一组件但使用较适合结果复核的默认视角。
- 为 `VoxelizationMappingView` 增加 `variant="workspace" | "library"`，项目库模式采用黑色画布、精简标题和窄导航栏；工作区保持完整操作信息。
- 用加载指标组合逆向工作区所需数据状态，未完成时显示独立加载卡片。
- 调整项目库逆向结果布局为等高网格，并保证左右图容器底部一致。
## 执行步骤
1. 阅读现有 `ProjectLibrary.tsx`、`ReverseWorkspace.tsx` 的视图复用和数据加载逻辑。
2. 写入本次需求、实现、测试方案文档。
3. 修改融合视图与映射视图组件参数，补齐紧凑模式和复位视角。
4. 增加数据缓存与加载页，避免跨页面返回时重复拉取大数据。
5. 调整项目库结果区布局和控件位置。
6. 执行类型检查、构建、服务重启与健康检查。
7. 追加经验记录并提交推送到 Gitea。
## 兼容性与回滚方案
- 新增 UI 变体保持默认值为工作区模式，避免影响已有调用。
- 缓存仅保存在浏览器内存中，刷新页面会自然清空；若出现旧数据问题，可删除缓存分支回退为原请求逻辑。
- 如果紧凑模式影响项目库结果展示，可只回退 `variant="library"` 调用，不影响逆向工作区主流程。
## 预计文件变更
- 修改 `ReverseWorkspace.tsx`：组件参数、缓存、加载页、视图布局。
- 修改 `ProjectLibrary.tsx`：调用参数、布局对齐、控件位置。
- 视需要修改 `index.css`：竖向导航样式微调。
- 新增本次三份工程分析文档，并追加经验记录。
## 提交与部署策略
- 只暂存本次修改的源码和本次工程分析文档。
- commit message 使用 `2026-05-20-21-25-19 项目库结果视图与加载缓存优化`。
- 推送到 `http://192.168.31.5:5002/admin/REVOXELSEG_DICOM.git` 的 `main` 分支。
- 使用 `tmux` 会话 `revoxelseg-dicom` 重新部署并验证。

57
工程分析/实现方案-2026-05-20-22-07-46.md
View File

@@ -1,57 +0,0 @@
# 实现方案-2026-05-20-22-07-46
## 实现方案文档路径
`工程分析/实现方案-2026-05-20-22-07-46.md`
## 修改目标
1. 后端导出压缩包文件名改成 `项目名_时间.tar.gz`，兼容中文项目名。
2. `VoxelizationMappingView` 支持把 Overlay Label Map 摘要放到右侧下方或底部下方。
3. 项目库使用右侧 Overlay 摘要布局；逆向工作区使用项目库风格的黑底工具行和右侧切片导航，但 Overlay 仍在下方。
4. 项目库“逆向分割结果”摘要只显示构件总数、最后保存时间和模型位姿。
## 涉及路径
- `WebSite/server.ts`
- `WebSite/src/components/ReverseWorkspace.tsx`
- `WebSite/src/components/ProjectLibrary.tsx`
- `WebSite/src/index.css`
- `工程分析/经验记录.md`
## 技术路线
- 在后端新增项目名/时间文件名格式化函数，并用于 bundle 下载响应头。
- 在 `VoxelizationMappingView` 中抽出 Overlay 摘要渲染片段，通过 `variant` 与布局参数区分项目库和逆向工作区。
- 逆向工作区把窗宽、旋转和位置重置按钮传入映射视图内部，外层只保留模块标题或直接交给组件渲染。
- 项目库结果摘要卡片移除切片和类别范围字段，增加位姿字段的紧凑网格。
## 执行步骤
1. 定位 `server.ts` 导出 bundle 的文件名生成逻辑。
2. 定位 `ProjectLibrary.tsx` 结果摘要和映射视图调用逻辑。
3. 调整 `ReverseWorkspace.tsx` 的映射视图 `variant`、工具栏和 Overlay 位置。
4. 更新样式文件中的暗色竖向滑块或新增必要类名。
5. 执行 `npm run lint`、`npm run build`。
6. 重启 `tmux` 服务并验证 `/api/health` 与页面响应。
7. 追加经验记录，提交并推送到 Gitea。
## 兼容性与回滚方案
- 导出文件名只改响应头，不改变压缩包内部结构，回滚时恢复旧 `filename` 即可。
- 视图布局通过组件参数控制，若项目库右侧摘要不合适，可回退为下方摘要或隐藏摘要。
- 逆向工作区仍使用同一 `VoxelizationMappingView`，回滚风险集中在一个组件。
## 预计文件变更
- 修改 `server.ts` 导出文件名。
- 修改 `ReverseWorkspace.tsx` 和 `ProjectLibrary.tsx` 视图布局与摘要字段。
- 视需要修改 `index.css` 滑块样式。
- 新增三份工程分析文档，追加 `经验记录.md`。
## 提交与部署策略
- 只暂存本次相关源码和本次工程分析文档。
- commit message 使用 `2026-05-20-22-07-46 导出命名与映射视图摘要优化`。
- 推送到 Gitea `main` 分支。
- 构建后重启 `tmux` 会话 `revoxelseg-dicom`。

61
工程分析/实现方案-2026-05-20-22-35-42.md
View File

@@ -1,61 +0,0 @@
# 实现方案-2026-05-20-22-35-42
## 实现方案文档路径
`工程分析/实现方案-2026-05-20-22-35-42.md`
## 修改目标
- 精简 Overlay Label Map 状态文案。
- 导出项目及结果支持分割整体/分构件导出，并调整默认勾选与排序。
- 为项目库 DICOM/STL 导入按钮接入真实上传流程，空项目展示导入提示。
- 项目级上传资产独立存储，恢复演示环境仍使用默认数据。
- 用户账号重名冲突给出可读反馈。
- 逆向工作区无保存结果时初次加载默认执行 Z 轴等比例拉伸。
## 涉及路径
- `WebSite/server.ts`
- `WebSite/src/lib/api.ts`
- `WebSite/src/components/ProjectLibrary.tsx`
- `WebSite/src/components/ReverseWorkspace.tsx`
- `WebSite/src/components/UserManagement.tsx`
- `工程分析/经验记录.md`
## 技术路线
1. 后端新增项目上传资产目录 `WebSite/data/uploads/<projectId>/dicom|stl`，导入接口接收 base64 文件并写入项目专属目录。
2. 后端统一项目 DICOM/STL 路径解析，预览、三维融合、模型文件、导出和分割生成均读取项目路径。
3. 导出包接口增加 `segmentationExportMode=combined|separate` 参数；整体模式沿用现有 label map，分构件模式逐个构件生成独立 NII.GZ。
4. 前端导出面板增加分割导出方式单选，调整默认选择和选项顺序。
5. 项目库导入按钮使用隐藏文件输入，按当前视图选择 DICOM 或 STL 上传，并刷新项目状态。
6. 用户管理编辑接口 409 时展示“账号已存在，请更换账号”等提示。
7. 逆向工作区加载项目后，若没有保存结果，则在 fusion volume 和模型边界都就绪后触发一次 Z 拉伸。
## 执行步骤
1. 编写本次需求分析、实现方案、测试方案。
2. 阅读并定位导出、导入、项目路径、用户管理和逆向工作区相关源码。
3. 修改后端资产导入与导出逻辑。
4. 修改前端项目库、逆向工作区和用户管理交互。
5. 执行 `npm run lint` 与 `npm run build`。
6. 使用 tmux 重启 `revoxelseg-dicom` 服务并验证 `/api/health` 与首页。
7. 追加经验记录，提交并推送本次相关文件。
## 兼容性与回滚方案
- 未导入资产的默认项目继续读取 `Head_CT_DICOM/` 与 `Head_CT_ReConstruct/`。
- 已保存的项目路径由状态文件保存，恢复演示环境可通过现有重置接口回到默认路径。
- 若分构件导出失败，可回退为 `segmentationExportMode=combined` 的原有整体导出。
## 预计文件变更
- 前端：3 个组件与 API 封装。
- 后端：1 个 Express 服务文件。
- 工程文档：本次三件套与经验记录。
## 提交与部署策略
- 仅暂存本次修改的源码与工程分析文档。
- commit message 包含 `2026-05-20-22-35-42` 与简要描述。
- 提交后推送到既有 Gitea 远端，并重启 4000 端口服务。

58
工程分析/实现方案-2026-05-20-23-28-51.md
View File

@@ -1,58 +0,0 @@
# 实现方案-2026-05-20-23-28-51
## 实现方案文档路径
`工程分析/实现方案-2026-05-20-23-28-51.md`
## 修改目标
- 修复位姿按钮首次点击导致中部可视化工具栏滚动上跳。
- 统一项目库与逆向工作区竖向 Slice Navigator 滑块居中样式。
- 将项目库 Overlay Label Map 摘要从映射视图右侧黑色面板改为导出按钮下方浅色信息格。
- 调整逆向分割结果状态徽标与标题同行。
- 导入已有 DICOM/STL 时增加覆盖确认。
- DICOM 导入时生成并保存详细信息缓存，详情接口优先读取缓存。
- 项目库逆向分割页导出按钮移到顶部操作区。
## 涉及路径
- `WebSite/src/components/ReverseWorkspace.tsx`
- `WebSite/src/components/ProjectLibrary.tsx`
- `WebSite/src/index.css`
- `WebSite/server.ts`
- `工程分析/经验记录.md`
## 技术路线
1. `VoxelizationMappingView` 新增 Overlay 统计回调和 `overlayPlacement='none'`，项目库使用外置浅色 Overlay 面板。
2. 在项目库 mask 视图顶部操作区渲染“导出项目及结果”按钮和下拉菜单，删除下方旧导出入口。
3. 调整竖向 range input CSS，使可点击层覆盖轨道但 thumb 视觉中心与轨道中心对齐。
4. 为位姿微调按钮增加 `onMouseDown preventDefault`，并在位姿更新时保持工具栏滚动位置。
5. 导入入口根据项目现有数据量弹出覆盖确认，再唤起文件选择。
6. 后端 DICOM 导入后调用现有 DICOM 信息解析逻辑，将结果写入上传目录缓存文件；`/dicom-info` 优先读取缓存。
## 执行步骤
1. 写入本次需求、实现、测试方案。
2. 定位映射视图、项目库 mask 页、位姿控件、CSS range 样式和导入接口。
3. 修改前端组件结构与样式。
4. 修改后端 DICOM 信息缓存逻辑。
5. 执行 `npm run lint`、`npm run build`。
6. 重启 `revoxelseg-dicom` tmux 服务并验证 `/api/health` 与首页。
7. 追加经验记录，提交并推送 Gitea。
## 兼容性与回滚方案
- 若外置 Overlay 面板出现异常，可将项目库 `overlayPlacement` 改回 `side`。
- DICOM 信息缓存失败时不阻断默认详情接口解析，可回退到实时解析。
- 导入覆盖确认只在前端增加，后端接口仍保持原有覆盖写入能力。
## 预计文件变更
- 前端组件 2 个，样式 1 个，后端 1 个，工程分析文档 4 个。
## 提交与部署策略
- 只暂存本次相关文件，忽略历史删除和软著未跟踪文件。
- commit message 包含 `2026-05-20-23-28-51` 与简要描述。
- 推送 Gitea 后重启 4000 服务。

57
工程分析/实现方案-2026-05-21-00-05-04.md
View File

@@ -1,57 +0,0 @@
# 实现方案-2026-05-21-00-05-04
## 实现方案文档路径
`工程分析/实现方案-2026-05-21-00-05-04.md`
## 修改目标
- 项目库导入 DICOM/STL 时显示上传进度、文件数量和体积。
- 将项目资产导入从 base64 JSON 改为 multipart 表单上传，降低浏览器内存占用。
- 后端接收普通文件和压缩包，并在服务端展开 ZIP/TAR/TAR.GZ/TGZ/GZ。
- 导入完成后继续刷新项目状态、清理缓存、保留覆盖确认逻辑。
- 对 3D 模型导入崩溃原因给出技术修复：避免 `Promise.all(fileToBase64)` 和巨型 JSON body。
## 涉及路径
- `WebSite/src/lib/api.ts`
- `WebSite/src/components/ProjectLibrary.tsx`
- `WebSite/server.ts`
- `WebSite/package.json`
- `WebSite/package-lock.json`
- `工程分析/经验记录.md`
## 技术路线
1. 引入 `multer` 接收 multipart 文件，使用内存上传缓冲后统一写入项目资产目录。
2. 引入 `adm-zip` 解压 ZIP；TAR/TAR.GZ/TGZ 使用 Node `zlib` 与简单 tar header 解析；单文件 GZ 解压为原文件。
3. 后端新增导入文件展开函数，统一过滤 DICOM/STL 目标扩展名，并防止路径穿越。
4. 前端新增 `uploadProjectAssets`，使用 `XMLHttpRequest.upload.onprogress` 返回上传百分比。
5. 项目库增加导入进度状态和紧凑进度条，上传完成后显示服务器解析/解压阶段。
6. 文件选择器 accept 增加 `.zip,.tar,.tar.gz,.tgz,.gz`。
## 执行步骤
1. 写入需求、实现、测试方案。
2. 安装 multipart 和 zip 解析依赖。
3. 修改后端导入接口，兼容新的 multipart 上传。
4. 修改前端 API 封装和项目库导入 UI。
5. 执行 `npm run lint`、`npm run build`。
6. 验证健康检查、首页响应和示例项目状态。
7. 追加经验记录，提交推送 Gitea，重新部署服务。
## 兼容性与回滚方案
- 若 multipart 上传出现问题，可临时保留 JSON body 解析分支作为兼容回退。
- 若压缩包解析失败，应返回明确错误，不写入半成品项目状态。
- 如新增依赖不可用，可回退为仅支持普通文件和 TAR.GZ，ZIP 支持后续补齐。
## 预计文件变更
- 前端 API 1 个、项目库组件 1 个、后端服务 1 个、依赖清单 2 个、工程分析文档 4 个。
## 提交与部署策略
- 只暂存本次相关代码和工程分析文档。
- commit message 包含 `2026-05-21-00-05-04` 与“导入进度与压缩包支持”。
- 重新构建并使用 `tmux` 会话 `revoxelseg-dicom` 运行 4000 服务。

51
工程分析/实现方案-2026-05-21-00-43-44.md
View File

@@ -1,51 +0,0 @@
# 实现方案-2026-05-21-00-43-44
## 实现方案文档路径
`工程分析/实现方案-2026-05-21-00-43-44.md`
## 修改目标
- 复现 `3279-STL.zip` 导入时的 422 错误，获取具体失败原因。
- 修复 ZIP 内 STL 解压/筛选/写入逻辑，使该压缩包可导入。
- 优化导入失败 UI，将错误状态和原因显示在顶部导入进度区域。
- 补充测试记录和经验记录。
## 涉及路径
- `WebSite/server.ts`
- `WebSite/src/components/ProjectLibrary.tsx`
- `工程分析/经验记录.md`
## 技术路线
1. 使用 `curl -F files=@3279-STL.zip` 对现有接口复现错误，查看响应体。
2. 检查 `AdmZip` 解包结果、ZIP 条目大小和写入逻辑。
3. 如果问题来自大 ZIP 一次性 `entry.getData()` 导致内存或写入失败，则改为按条目流式/逐条写入目标目录，减少内存峰值。
4. 如果问题来自文件名扩展名、编码或路径处理，则修正筛选和安全文件名逻辑。
5. 前端导入状态增加 `failed` phase，错误时保留进度卡并展示错误文案。
## 执行步骤
1. 创建本次工程分析文档。
2. 本地复现 422，记录响应。
3. 修改后端 ZIP 导入逻辑和前端错误反馈。
4. 执行 `npm run lint`、`npm run build`。
5. 用 `3279-STL.zip` 对临时项目实际导入验证。
6. 追加经验记录，提交推送 Gitea，重新部署。
## 兼容性与回滚方案
- 若 `AdmZip` 对该 ZIP 仍不稳定，可增加系统 `unzip` fallback 或改用更适合流式解压的库。
- 前端错误卡只影响导入反馈，不影响其他页面。
- 导入失败时不更新项目状态，避免半成品资产进入项目库。
## 预计文件变更
- 后端 1 个、前端组件 1 个、工程分析文档 4 个。
## 提交与部署策略
- 不提交 `3279-STL.zip` 和解压资产。
- commit message 包含 `2026-05-21-00-43-44` 与“修复 ZIP STL 导入失败”。
- 部署后验证 `/api/health`、首页以及 ZIP 导入结果。

53
工程分析/实现方案-2026-05-21-00-58-25.md
View File

@@ -1,53 +0,0 @@
# 实现方案-2026-05-21-00-58-25
实现方案文档路径：`工程分析/实现方案-2026-05-21-00-58-25.md`
## 修改目标
- 对系统进行静态、构建、API 与浏览器交互测试。
- 根据测试结果修复真实影响使用的问题。
- 更新软著说明书、登记表、代码汇总、素材清单，并重新生成说明书截图和 Word 文档。
- 按项目工作流提交代码与工程分析文档，软著材料不提交。
## 涉及路径
- 可能涉及：`WebSite/server.ts`、`WebSite/src/components/*`、`WebSite/src/lib/*`、`WebSite/src/types.ts`。
- 工程分析：`工程分析/需求分析-2026-05-21-00-58-25.md`、`工程分析/实现方案-2026-05-21-00-58-25.md`、`工程分析/测试方案-2026-05-21-00-58-25.md`、`工程分析/经验记录.md`。
- 软著材料：`新撰写软著文档/`，仅本地更新，不纳入 Gitea。
## 技术路线
1. 运行 `npm run lint`、`npm run build`、API 健康检查与关键接口抽查。
2. 使用浏览器自动化访问登录、总体概况、项目库、逆向工作区、系统管理等核心路径，观察控制台错误与页面状态。
3. 对发现的问题做小范围修复，避免引入新的数据结构风险。
4. 重新运行测试并部署。
5. 使用最新界面重新截取说明书图片，更新 Markdown 与 docx。
## 执行步骤
- 确认服务、依赖、脚本和软著材料现状。
- 执行静态与构建测试。
- 执行浏览器回归测试和页面截图。
- 修复测试中发现的缺陷。
- 重新生成软著文档和图片。
- 追加经验记录，精确暂存并提交代码/工程文档。
- 重新部署并验证服务。
## 兼容性与回滚方案
- 只修改明确发现的问题和文档内容，不改变默认医学数据。
- 如某项修复造成构建失败，回退该小范围 patch 并记录原因。
- 软著材料不提交，必要时可从本地历史文件恢复。
## 预计文件变更
- 新增本次工程分析三件套。
- 追加 `工程分析/经验记录.md`。
- 视测试结果修改少量前后端文件。
- 本地更新 `新撰写软著文档/` 下 Markdown、docx 和图片。
## 提交与部署策略
- Gitea commit 只包含本次代码修复和工程分析文档。
- Commit message 包含 `2026-05-21-00-58-25` 与简要描述。
- 使用 `tmux` 会话 `revoxelseg-dicom` 重启 `npm run serve -- --host 0.0.0.0 --port 4000`。

54
工程分析/实现方案-2026-05-21-09-29-47.md
View File

@@ -1,54 +0,0 @@
# 实现方案-2026-05-21-09-29-47
实现方案文档路径：`工程分析/实现方案-2026-05-21-09-29-47.md`
## 修改目标
- 定位并修复自动拉伸按钮的尺度计算逻辑。
- 将缩放控件的展示精度和按钮调整步长统一为三位小数、`0.005`。
- 完成静态检查、构建和部署验证。
## 涉及路径
- `WebSite/src/components/ReverseWorkspace.tsx`
- `WebSite/src/components/ProjectLibrary.tsx`
- `工程分析/需求分析-2026-05-21-09-29-47.md`
- `工程分析/实现方案-2026-05-21-09-29-47.md`
- `工程分析/测试方案-2026-05-21-09-29-47.md`
- `工程分析/经验记录.md`
## 技术路线
1. 查找 `Z拉伸`、`Y拉伸`、`stretch`、`poseStepConfig`、`scale` 相关实现。
2. 对齐自动拉伸与三维融合视图的模型包围盒基准，避免可见构件和全局构件混用导致重复点击结果不同。
3. 将自动拉伸改为基于原始模型全局包围盒和 DICOM 物理尺寸计算目标缩放，使操作幂等。
4. 对单轴贴合增加 DICOM 体范围保护，避免 Y 等短轴贴合时把整体模型放大到超出视场。
5. 将 `scale` 的步长改为 `0.005`，数值输入/展示统一三位小数。
6. 运行 `npm run lint`、`npm run build`，并通过接口/页面验证部署。
## 执行步骤
- 阅读相关源码和当前状态。
- 修改自动拉伸计算函数与缩放格式化函数。
- 确认保存快照和导出仍使用数值型 `scale`。
- 构建并部署。
- 追加经验记录，提交并尝试推送 Gitea。
## 兼容性与回滚方案
- 修改仅限前端位姿计算与展示，不改变后端数据结构。
- 若自动拉伸回归失败，可回退本次 `ReverseWorkspace.tsx` 改动。
- 旧保存位姿仍可按数值读取，界面展示会统一为三位小数。
## 预计文件变更
- 修改 `WebSite/src/components/ReverseWorkspace.tsx`。
- 修改 `WebSite/src/components/ProjectLibrary.tsx`。
- 新增本次工程分析三件套。
- 追加 `工程分析/经验记录.md`。
## 提交与部署策略
- 暂存本次代码与工程分析文档，避免历史删除、软著目录和压缩包进入提交。
- Commit message 包含 `2026-05-21-09-29-47` 与简要说明。
- 使用 `tmux` 会话 `revoxelseg-dicom` 重新部署端口 `4000`。

57
工程分析/实现方案-2026-05-21-10-05-51.md
View File

@@ -1,57 +0,0 @@
# 实现方案-2026-05-21-10-05-51
实现方案文档路径：`工程分析/实现方案-2026-05-21-10-05-51.md`
## 修改目标
- 根据当前系统功能更新软著说明书、登记表、代码汇总与素材清单。
- 重新拍摄说明书章节图片，确保每个主要功能说明有对应真实界面图。
- 重新生成可编辑 Word 文档。
- 完成文档引用、图片存在性、Word 文件有效性和服务验证。
## 涉及路径
- `新撰写软著文档/1. 软著说明书.md`
- `新撰写软著文档/2. 软著登记表.md`
- `新撰写软著文档/3. 代码汇总.md`
- `新撰写软著文档/images/`
- `新撰写软著文档/功能验证与素材清单.md`
- `新撰写软著文档/*.docx`
- `工程分析/经验记录.md`
## 技术路线
1. 学习 `※撰写Agent.md` 与参考模板要求。
2. 读取现有软著说明书、登记表、代码汇总和素材清单，找出与当前功能不一致之处。
3. 使用当前运行系统重新拍摄登录、概况、项目库、导入、三维模型、逆向分割结果、逆向工作区、导出、系统管理等图片。
4. 重写或增补说明书章节，保证功能说明更细化、图片引用更新且无重复引用。
5. 更新登记表中的功能概述、技术特点、运行环境和源程序量。
6. 更新代码汇总，确保核心代码摘抄覆盖当前导入、导出、分割映射、用户管理和位姿逻辑。
7. 生成 docx，并校验图片引用、docx 压缩包结构与行数。
## 执行步骤
- 检查当前服务状态并确认可访问。
- 准备或更新截图自动化脚本，输出到 `新撰写软著文档/images/`。
- 更新 Markdown 正文和素材清单。
- 使用 Pandoc 或 `python-docx` 生成 Word。
- 校验所有图片引用存在、说明书每个章节都有图片、代码汇总行数满足要求。
- 按工作流追加经验记录、提交工程分析文档并重新部署验证。
## 兼容性与回滚方案
- 本次不修改系统业务代码，回滚时只需恢复 `新撰写软著文档/` 的文档和图片。
- 软著材料不入 Gitea，避免影响项目代码版本。
- 若自动截图失败，可保留已有图片并记录失败原因，但优先重拍成功截图。
## 预计文件变更
- 更新 `新撰写软著文档/` 下 Markdown、Word、图片和素材清单。
- 新增当次工程分析三件套。
- 追加 `工程分析/经验记录.md`。
## 提交与部署策略
- Gitea 提交只包含本次工程分析记录，不包含软著材料。
- Commit message 包含 `2026-05-21-10-05-51` 与简要描述。
- 按工作流重新部署并验证服务。

63
工程分析/实现方案-2026-05-21-10-38-49.md
View File

@@ -1,63 +0,0 @@
# 实现方案：Docker 双环境部署与 FRPC 公网映射
实现方案文档路径：`工程分析/实现方案-2026-05-21-10-38-49.md`
## 修改目标
新增完整容器化部署方案，使项目可通过 Docker Compose 在本机和威联通 NAS Container Station 中运行，并通过内置 frpc 服务映射到 `82.157.255.195:10008`，配合 `revoxel.huijutec.cn` 访问。
## 涉及路径
- `.dockerignore`
- `Docker部署/Dockerfile`
- `Docker部署/README.md`
- `Docker部署/本机/docker_compose.yaml`
- `Docker部署/威联通NAS/docker_compose.yaml`
- `工程分析/需求分析-2026-05-21-10-38-49.md`
- `工程分析/实现方案-2026-05-21-10-38-49.md`
- `工程分析/测试方案-2026-05-21-10-38-49.md`
- `工程分析/经验记录.md`
## 技术路线
1. 停止现有 `tmux` 会话中的 `npm run serve` 服务。
2. 新增 Dockerfile：
- 使用 Node 官方镜像。
- 复制 `WebSite/package*.json` 并执行 `npm ci`。
- 复制 WebSite 源码、默认 DICOM 数据和默认 STL 数据。
- 执行 `npm run build`。
- 使用 `NODE_ENV=production` 通过 `npm run serve -- --host 0.0.0.0 --port 4000` 启动。
3. 新增本机 Compose：
- `revoxelseg_web` 暴露 `4000:4000`。
- 挂载本机部署目录下的 `data/`、`exports/`。
- `revoxelseg_frpc` 使用 `snowdreamtech/frpc:latest`，启动时写入 `/tmp/frpc.toml`。
4. 新增 QNAP Compose：
- build context 使用 `/share/Container/revoxelseg_dicom` 绝对路径。
- 运行态目录挂载到 `/share/Container/revoxelseg_dicom/data` 与 `exports`。
- frpc 直接内嵌同样的远端映射配置。
5. 新增 README 说明部署、访问、停止、日志查看和路径修改方式。
## 执行步骤
1. 创建 `Docker部署/`、`Docker部署/本机/`、`Docker部署/威联通NAS/`。
2. 写入 Dockerfile、两份 Compose 与 README。
3. 执行 `npm run lint` 与 `npm run build`。
4. 执行 `docker compose -f Docker部署/本机/docker_compose.yaml config` 校验语法。
5. 构建并启动本机 Docker 部署。
6. 验证 `http://127.0.0.1:4000/api/health` 与 `http://127.0.0.1:4000/`。
7. 检查 frpc 容器日志是否启动并尝试连接服务端。
8. 更新经验记录并提交本次相关文件。
## 兼容性与回滚方案
- 回滚到旧部署：执行 `docker compose -f Docker部署/本机/docker_compose.yaml down` 后，按旧方式进入 `WebSite` 执行 `npm run serve -- --host 0.0.0.0 --port 4000`。
- 如果 QNAP 路径不同，只需修改 NAS Compose 中的 `build.context` 和 volume 宿主机路径。
- 如果远端端口冲突，修改 frpc `remotePort` 和 NPM 反向代理目标端口即可。
## 预计文件变更
新增 Docker 部署文件，不修改业务源码。
## 提交与部署策略
提交包含 Docker 部署文件与工程分析文档；部署以本机 Docker Compose 作为验证环境。软著材料和无关工作区变化不纳入提交。

70
工程分析/实现方案-2026-05-21-11-13-49.md
View File

@@ -1,70 +0,0 @@
# 实现方案：独立 Docker 程序目录与 Gitea 分支存储
实现方案文档路径：`工程分析/实现方案-2026-05-21-11-13-49.md`
## 修改目标
在 `~/Desktop/ReVoxelSeg_DICOM_Docker` 生成可独立运行的 Docker 程序包，并将其作为 Gitea 新分支 `docker-standalone-20260521` 推送。
## 涉及路径
主项目：
- `工程分析/需求分析-2026-05-21-11-13-49.md`
- `工程分析/实现方案-2026-05-21-11-13-49.md`
- `工程分析/测试方案-2026-05-21-11-13-49.md`
- `工程分析/经验记录.md`
独立 Docker 程序目录：
- `~/Desktop/ReVoxelSeg_DICOM_Docker/WebSite/`
- `~/Desktop/ReVoxelSeg_DICOM_Docker/Head_CT_DICOM/`
- `~/Desktop/ReVoxelSeg_DICOM_Docker/Head_CT_ReConstruct/`
- `~/Desktop/ReVoxelSeg_DICOM_Docker/Dockerfile`
- `~/Desktop/ReVoxelSeg_DICOM_Docker/.dockerignore`
- `~/Desktop/ReVoxelSeg_DICOM_Docker/.gitignore`
- `~/Desktop/ReVoxelSeg_DICOM_Docker/docker_compose.yaml`
- `~/Desktop/ReVoxelSeg_DICOM_Docker/docker_compose.nas.yaml`
- `~/Desktop/ReVoxelSeg_DICOM_Docker/README.md`
## 技术路线
1. 从主项目复制必要运行内容到独立目录：
- 复制 `WebSite/`，排除 `node_modules`、`dist`、`data`、`exports` 和本地环境文件。
- 复制默认演示数据 `Head_CT_DICOM/`、`Head_CT_ReConstruct/`。
2. 将 Dockerfile 调整为独立目录根构建：
- `COPY WebSite/package*.json ./WebSite/`
- `COPY WebSite ./WebSite`
- `COPY Head_CT_DICOM ./Head_CT_DICOM`
- `COPY Head_CT_ReConstruct ./Head_CT_ReConstruct`
3. 根目录放置两份 Compose：
- `docker_compose.yaml`：本机部署，挂载 `./data` 与 `./exports`。
- `docker_compose.nas.yaml`：NAS 部署，默认绝对路径 `/share/Container/revoxelseg_dicom`。
4. 在独立目录初始化 Git 仓库并推送到 Gitea 新分支。
5. 对独立目录执行 Compose 配置校验和构建验证。
## 执行步骤
1. 清理并重建 `~/Desktop/ReVoxelSeg_DICOM_Docker`。
2. 使用 `rsync` 复制必要目录并排除运行态产物。
3. 写入根目录 Docker 部署文件。
4. 执行 `docker compose -f docker_compose.yaml config` 与 `docker compose -f docker_compose.nas.yaml config`。
5. 执行 `docker compose -f docker_compose.yaml build` 或 `up -d --build` 验证独立目录可用。
6. 验证本机端口与健康接口。
7. 初始化独立目录 Git 仓库，创建 `docker-standalone-20260521` 分支并推送。
8. 主项目提交工程分析记录。
## 兼容性与回滚方案
- 若独立 Docker 目录构建失败，不影响当前主项目目录和已运行的 Docker 服务。
- 若 Gitea 分支推送失败，可保留本地独立目录，并重新执行 `git push origin docker-standalone-20260521`。
- 若 NAS 路径不同，修改 `docker_compose.nas.yaml` 中的 `build.context` 和 volume 宿主机路径。
## 预计文件变更
主项目仅新增/更新工程分析文档；独立目录为新建自包含 Docker 程序包。
## 提交与部署策略
- 独立 Docker 程序包在新分支 `docker-standalone-20260521` 中存储。
- 主项目 `main` 分支仅提交工程分析记录，避免把独立运行包重复放进主项目。

65
工程分析/实现方案-2026-05-21-14-19-12.md
View File

@@ -1,65 +0,0 @@
# 实现方案：Gitea Releases 发布三种 Docker 部署版本
实现方案文档路径：`工程分析/实现方案-2026-05-21-14-19-12.md`
## 修改目标
在 Gitea Releases 页面发布三种可下载 Docker 部署版本，并保证三种版本的根目录部署入口一致。
## 涉及路径
主项目：
- `工程分析/需求分析-2026-05-21-14-19-12.md`
- `工程分析/实现方案-2026-05-21-14-19-12.md`
- `工程分析/测试方案-2026-05-21-14-19-12.md`
- `工程分析/经验记录.md`
独立 Docker 程序包：
- `~/Desktop/ReVoxelSeg_DICOM_Docker/docker_compose.yaml`
- `~/Desktop/ReVoxelSeg_DICOM_Docker/docker_compose.nas.yaml`
- `~/Desktop/ReVoxelSeg_DICOM_Docker/.env.example`
- `~/Desktop/ReVoxelSeg_DICOM_Docker/README.md`
## 技术路线
1. 在独立 Docker 程序包仓库中基于 `docker-standalone-20260521` 创建三个发布分支。
2. 机器版：
- 使用当前本机 `docker_compose.yaml`。
- 创建 tag `revoxelseg-docker-machine-v2026.05.21`。
3. NAS 版：
- 将 `docker_compose.nas.yaml` 内容复制为根目录 `docker_compose.yaml`。
- 更新 README 为 NAS 直接部署入口。
- 创建 tag `revoxelseg-docker-nas-v2026.05.21`。
4. 通用版：
- 改写 `docker_compose.yaml`，使用环境变量占位 FRPC 配置。
- 添加 `.env.example`。
- README 说明用户需自行填写 `.env`。
- 创建 tag `revoxelseg-docker-generic-v2026.05.21`。
5. 推送三个分支和三个 tag 到 Gitea。
6. 通过 Gitea API 创建三个 Release。
## 执行步骤
1. 检查独立 Docker 目录 Git 状态。
2. 创建发布分支和 tag。
3. 对三种版本分别运行 `docker compose -f docker_compose.yaml config`。
4. 推送分支和 tag。
5. 使用 Gitea API `POST /api/v1/repos/admin/REVOXELSEG_DICOM/releases` 创建 Release。
6. 使用 Gitea API 查询 Release 列表，确认三个版本存在。
7. 更新测试方案和经验记录。
## 兼容性与回滚方案
- 若 Release 创建失败，可以保留已推送 tag，重新调用 API 创建 Release。
- 若某个版本配置错误，可新建修订 tag，而不是强推覆盖旧 tag。
- 当前正在运行的独立 Docker 容器不依赖工作树后续分支切换，不会因创建发布分支中断服务。
## 预计文件变更
独立 Docker 仓库新增发布分支/tag；主项目新增工程分析文档和经验记录。
## 提交与部署策略
本次不改业务源码，不需要重新构建前端。发布验证以 Compose config、健康接口和 Gitea Release 查询为主。主项目 `main` 只提交工程分析文档。

58
工程分析/实现方案-2026-05-21-14-35-20.md
View File

@@ -1,58 +0,0 @@
# 实现方案：合并 Docker 三版本 Gitea Release
实现方案文档路径：`工程分析/实现方案-2026-05-21-14-35-20.md`
## 修改目标
将 Gitea 上三个 Docker 部署 Release 合并为一个整合 Release，并在该 Release 中挂载三个命名清晰的部署附件。
## 涉及路径
- `/home/wkmgc/Desktop/ReVoxelSeg_DICOM_Docker`
- `工程分析/需求分析-2026-05-21-14-35-20.md`
- `工程分析/实现方案-2026-05-21-14-35-20.md`
- `工程分析/测试方案-2026-05-21-14-35-20.md`
- `工程分析/经验记录.md`
## 技术路线
1. 使用独立 Docker 仓库中已有三个 release tag，通过 `git archive` 生成三个部署压缩包。
2. 对通用版 tag 做固定环境信息搜索，确认没有泄露当前 FRPC 与域名配置。
3. 创建整合 tag `revoxelseg-docker-all-v2026.05.21` 并推送到 Gitea。
4. 通过 Gitea API 创建单个整合 Release。
5. 上传三个附件：
- 本机直接部署包
- 威联通 NAS 直接部署包
- 通用部署包
6. 确认整合 Release 附件完整后，再删除旧三个 Release 记录。
## 执行步骤
- 生成 `release-assets/` 临时附件目录。
- 从三个 tag 归档生成 `.tar.gz` 文件。
- 校验压缩包目录结构与关键文件。
- 创建并推送整合 tag。
- 调用 Gitea Releases API 创建整合发布。
- 逐个上传附件并检查资产列表。
- 删除旧 release id 或通过 tag 查询后删除。
- 验证本地与公网服务。
- 更新测试方案与经验记录。
- 仅提交本次工程分析文档。
## 兼容性与回滚方案
- 原三个 tag 与分支不删除，若整合 Release 出现问题，可基于 tag 重新生成附件或恢复旧 Release。
- 删除旧 Release 记录只影响 Gitea 页面展示，不影响 git 历史。
- 若附件上传失败，不删除旧 Release，待上传成功后再清理。
## 预计文件变更
- 新增三份本次工程分析文档。
- 追加 `工程分析/经验记录.md`。
- 独立 Docker 仓库仅可能新增未跟踪临时附件目录，不纳入提交。
## 提交与部署策略
- 主工程提交信息包含时间戳：`2026-05-21-14-35-20 合并Docker部署Release记录`。
- 独立 Docker 仓库只推送整合 tag，不提交临时附件。
- 发布后验证 `http://127.0.0.1:4000/api/health` 与 `https://revoxel.huijutec.cn/`。

55
工程分析/实现方案-2026-05-21-15-50-21.md
View File

@@ -1,55 +0,0 @@
# 实现方案：系统使用视频配音版生成
实现方案文档路径：`工程分析/实现方案-2026-05-21-15-50-21.md`
## 修改目标
生成 5 分钟版和 10 分钟版系统使用视频的中文配音成片，并保证音视频最终时长一致。
## 涉及路径
- `视频配音/基于模型逆向体素化及DICOM分割标注系统-使用视频-5min版.mp4`
- `视频配音/基于模型逆向体素化及DICOM分割标注系统-使用视频-10min版.mp4`
- `视频配音/配音生成工作流-Ubuntu-Agent.md`
- `视频配音/Tools_scripts_XunFei-Ubuntu/`
- `视频配音/01_scripts/`
- `视频配音/02_audio/`
- `视频配音/04_intermediate/`
- `视频配音/05_outputs/`
## 技术路线
1. 使用 `ffprobe` 获取两个视频的准确时长、分辨率、帧率和音轨信息。
2. 抽样生成 contact sheet，快速阅览视频内容与操作流程。
3. 根据画面内容分别撰写 5 分钟和 10 分钟配音稿。
4. 优先检查讯飞 TTS 环境变量；当前环境缺少讯飞凭证时，使用已安装的 `edge-tts` 生成中文 MP3。
5. 将 TTS 音频规范化为 48kHz stereo WAV。
6. 使用 `ffmpeg` 通过 `apad` 与 `atrim` 将旁白音频严格对齐视频时长。
7. 将原视频静音并合入新旁白，输出 H.264/AAC MP4。
8. 使用 `ffprobe` 校验最终视频格式、音轨和时长差。
## 执行步骤
- 创建配音工作子目录。
- 写入 `配音稿-5min.md` 与 `配音稿-10min.md`。
- 对配音稿做 TTS 干跑或等效段落检查。
- 使用 `edge-tts` 分别生成原始旁白音频。
- 根据视频时长生成对齐后的 WAV 音轨。
- 用 `ffmpeg -map 0:v:0 -map 1:a:0 -shortest` 合成配音版视频。
- 对原始视频、旁白音频、对齐音频和最终视频做时长比对。
## 兼容性与回滚方案
- 原始视频不修改，输出文件单独放在 `05_outputs/`。
- 如后续提供讯飞凭证，可复用配音稿重新运行 `Tools_scripts_XunFei-Ubuntu` 的讯飞脚本生成更接近指定工作流的音色。
- 若用户希望调整语气或文案，只需改 `01_scripts/` 下对应配音稿并重新生成音频与合成视频。
## 预计文件变更
- 新增视频配音脚本、音频、最终视频和校验记录。
- 新增三份工程分析文档并追加 `经验记录.md`。
## 提交与部署策略
- 本次不需要重新部署 WebSite，因为不修改程序服务。
- 按工作流提交工程分析文档备份，避免把大体积视频产物混入 Git 提交。

45
工程分析/实现方案-2026-05-21-16-34-09.md
View File

@@ -1,45 +0,0 @@
# 实现方案：暂停当前系统服务
实现方案文档路径：`工程分析/实现方案-2026-05-21-16-34-09.md`
## 修改目标
停止当前 ReVoxelSeg DICOM 系统运行服务，并验证 `4000` 端口释放。
## 涉及路径
- `/home/wkmgc/Desktop/ReVoxelSeg_DICOM_Docker/docker_compose.yaml`
- `工程分析/需求分析-2026-05-21-16-34-09.md`
- `工程分析/实现方案-2026-05-21-16-34-09.md`
- `工程分析/测试方案-2026-05-21-16-34-09.md`
- `工程分析/经验记录.md`
## 技术路线
1. 检查 Docker Compose、Docker 容器、`tmux` 会话和 `4000` 端口占用。
2. 确认当前服务来自独立 Docker 部署。
3. 在 `/home/wkmgc/Desktop/ReVoxelSeg_DICOM_Docker` 执行 `docker compose -f docker_compose.yaml down`。
4. 再次检查容器状态、`4000` 端口和健康接口。
## 执行步骤
- 写入本次工程分析文档。
- 停止 Docker Compose 服务。
- 验证 `docker compose ps` 无运行服务。
- 验证 `ss -ltnp sport = :4000` 无监听。
- 验证 `http://127.0.0.1:4000/api/health` 不再返回服务响应。
## 兼容性与回滚方案
- 若需恢复服务，可回到 `/home/wkmgc/Desktop/ReVoxelSeg_DICOM_Docker` 执行 `docker compose -f docker_compose.yaml up -d`。
- 本次不删除镜像、数据卷或运行态数据。
## 预计文件变更
- 新增三份工程分析文档。
- 追加 `工程分析/经验记录.md`。
## 提交与部署策略
- 按工作流提交本次文档备份。
- 不重新部署系统，因为本次目标是暂停服务。

49
工程分析/实现方案-2026-05-23-00-32-26.md
View File

@@ -1,49 +0,0 @@
# 实现方案
实现方案文档路径：`工程分析/实现方案-2026-05-23-00-32-26.md`
## 修改目标
撰写一段准确、完整、可直接复用的系统功能文字描述，并完成工程分析流程留痕、备份提交、构建与部署验证。
## 涉及路径
- `工程分析/需求分析-2026-05-23-00-32-26.md`
- `工程分析/实现方案-2026-05-23-00-32-26.md`
- `工程分析/测试方案-2026-05-23-00-32-26.md`
- `工程分析/系统功能描述-2026-05-23-00-32-26.md`
- `工程分析/经验记录.md`
## 技术路线
1. 阅读工程工作流、整体分析、经验记录、README 与核心前端页面。
2. 提炼系统定位、用户登录、项目库、DICOM 预览、STL 预览、三维融合、位姿调整、构件样式、Mask/NIfTI 导出、系统管理和部署能力。
3. 将描述控制在 800-1300 字，并避免宣称当前尚未接入的真实医学级体素化能力。
4. 写入文档后执行字数检查、构建检查、部署验证和 Git 备份提交。
## 执行步骤
- 记录开始时间并阅读核心工程分析资料。
- 创建本次需求分析、实现方案、测试方案。
- 最终执行前再次阅读 `工程分析/经验记录.md`。
- 新增系统功能描述文档。
- 追加经验记录 A/B/C/D。
- 执行 `npm run build`。
- 使用项目约定的 `tmux` 会话重新部署，并验证 `/api/health` 与首页。
- 精确暂存本次文档并提交，commit message 包含时间戳和简要描述。
## 兼容性与回滚方案
- 本次不修改源码和配置，不影响系统运行兼容性。
- 如需回滚，可删除本次新增文档并回退经验记录追加段落；业务系统无需回滚。
## 预计文件变更
- 新增 4 个工程分析文档。
- 修改 1 个经验记录文档。
## 提交与部署策略
- Git 提交只包含本次相关文档。
- 部署沿用 `WebSite` 下 `npm run build` 与 `npm run serve -- --host 0.0.0.0 --port 4000`，优先使用 `tmux` 会话 `revoxelseg-dicom`。
- 若 4000 端口已由现有 Docker 正式服务占用，则不强行叠加 tmux 服务；记录占用来源，并对当前实际对外服务执行重建、重启和健康验证。

74
工程分析/实现方案-2026-05-24-09-58-56.md
View File

@@ -1,74 +0,0 @@
# 实现方案-2026-05-24-09-58-56
## 实现方案文档路径
`工程分析/实现方案-2026-05-24-09-58-56.md`
## 修改目标
- 阅读并梳理当前项目结构、技术栈、运行方式和 Docker 发布历史。
- 恢复误删的 `Docker部署/` 文件夹。
- 核查 Gitea 远端分支、tag 与 Release/附件关系；确认发布物仍由 tag/附件承载后，删除四个不再需要的发布辅助分支。
- 构建并重新部署 `WebSite` 服务，验证本机与公网访问。
- 完成工程分析记录、经验记录追加、Git/Gitea 备份提交。
## 涉及路径
- `Docker部署/`
- `工程分析/需求分析-2026-05-24-09-58-56.md`
- `工程分析/实现方案-2026-05-24-09-58-56.md`
- `工程分析/测试方案-2026-05-24-09-58-56.md`
- `工程分析/经验记录.md`
- `WebSite/`
## 技术路线
1. 使用 `git status`、`README.md`、`WebSite/package.json`、历史工程分析文档了解项目现状。
2. 通过 Git 历史或远端 `main` 恢复 `Docker部署/`，再核对恢复文件内容。
3. 使用 `git ls-remote` 与 Gitea API 检查远端分支、tag、Release 和附件；发布项和附件确认存在后，删除仅用于固化发布配置的辅助分支。
4. 执行 `npm run build` 验证前端生产构建。
5. 使用 `tmux` 会话 `revoxelseg-dicom` 启动 `npm run serve -- --host 0.0.0.0 --port 4000`。
6. 用健康接口、首页和公网域名做部署验证。
7. 追加经验记录，暂存本次相关文件并提交，推送到 Gitea。
## 执行步骤
1. 记录开始时间并阅读 `代码编纂工作流.md`、`工程整体分析.md`、`经验记录.md`。
2. 创建本次需求分析、实现方案、测试方案文档。
3. 再次读取 `经验记录.md`，满足执行前确认要求。
4. 恢复 `Docker部署/` 并检查 `Dockerfile`、`README.md`、本机 Compose、NAS Compose。
5. 查询远端分支与发布 tag；若 Release 附件存在且 tag 可追溯，删除四个辅助分支。
6. 执行构建和部署，检查端口与 tmux 会话状态。
7. 验证 `http://127.0.0.1:4000/api/health`、`http://127.0.0.1:4000/`、`https://revoxel.huijutec.cn/`。
8. 更新 `工程分析/经验记录.md`。
9. `git add` 仅暂存本次相关文件，提交并推送到 Gitea。
10. 最终汇报恢复文件、分支清理、部署验证与 commit 状态。
## 兼容性与回滚方案
- `Docker部署/` 若恢复异常，可从远端 `main` 或历史提交重新取回。
- 远端分支删除后仍保留 tag、Release 和附件；如确需恢复，可从对应 tag 重新创建分支。
- 部署失败时保留构建日志和 tmux 输出，必要时回退到此前可用的 Docker Compose 或旧 tmux 会话。
- 不提交既有无关删除，避免扩大回滚范围。
## 预计文件变更
- 新增三份本次工程分析文档。
- 恢复 `Docker部署/` 下 4 个文件。
- 追加 `工程分析/经验记录.md`。
- `WebSite/dist/` 可能因构建产生本地变化，但不作为本次备份提交重点。
## 提交与部署策略
- 提交信息使用：`2026-05-24-09-58-56 恢复Docker部署并清理发布分支`。
- 暂存范围限定为本次工程分析文档、经验记录和恢复的 `Docker部署/` 文件。
- 推送到用户提供的 Gitea 备份仓库对应 `main` 分支。
- 部署使用 `tmux` 会话 `revoxelseg-dicom` 长期运行 `NODE_ENV=production npm run serve -- --host 0.0.0.0 --port 4000`，避免公网 Host 被 Vite 开发中间件拦截。
- 公网访问另起 `revoxelseg-dicom-frpc` 容器，使用 host 网络把本机 `127.0.0.1:4000` 映射到 FRP 服务端 `10008`。
## 执行补充记录
- 初次按普通 `npm run serve` 启动后，本机 `/api/health`、`/` 与公网 API 正常，但公网根路径返回 `403 Blocked request. This host ("revoxel.huijutec.cn") is not allowed.`。
- 原因是非生产模式会进入 Vite 中间件，Vite 对公网 Host 做 allowedHosts 校验。
- 已改为 `NODE_ENV=production` 启动，服务直接返回 `WebSite/dist/` 生产构建产物。
- 当前公网链路由 `tmux` Web 服务加独立 `revoxelseg-dicom-frpc` 容器组成。

61
工程分析/实现方案-2026-05-24-10-09-37.md Normal file
View File

@@ -0,0 +1,61 @@
# 实现方案-2026-05-24-10-09-37
## 实现方案文档路径
`工程分析/实现方案-2026-05-24-10-09-37.md`
## 修改目标
- 精简 `工程分析/` 中历史 `需求分析-*`、`实现方案-*`、`测试方案-*` 等流水文档。
- 保留核心工程约束、整体分析、经验记录和本次流程记录。
- 更新工作流，明确历史三件套不再作为长期堆积物，长期经验以 `经验记录.md` 为准。
## 涉及路径
- `工程分析/代码编纂工作流.md`
- `工程分析/需求分析-2026-05-24-10-09-37.md`
- `工程分析/实现方案-2026-05-24-10-09-37.md`
- `工程分析/测试方案-2026-05-24-10-09-37.md`
- `工程分析/经验记录.md`
- 历史 `工程分析/需求分析-*.md`
- 历史 `工程分析/实现方案-*.md`
- 历史 `工程分析/测试方案-*.md`
- `工程分析/系统功能描述-2026-05-23-00-32-26.md`
## 技术路线
1. 按既有工作流创建本次三件套文档。
2. 更新 `代码编纂工作流.md`，加入工程分析目录精简策略。
3. 删除历史三件套和一次性说明文档，保留核心文档、本次三件套和经验记录。
4. 追加经验记录，记录本次目录治理策略。
5. 做静态检查、构建检查和部署验证。
## 执行步骤
1. 记录开始时间并阅读工作流、整体分析、经验记录。
2. 写入本次需求分析、实现方案和测试方案。
3. 再次确认已读 `经验记录.md`。
4. 执行历史文档删除，只保留核心文件与本次三件套。
5. 更新工作流中的精简策略。
6. 执行 `npm run lint` 和 `npm run build`。
7. 沿用或重启 `tmux` 服务并验证本机与公网入口。
8. 暂存本次文档治理变更，提交并推送 Gitea。
## 兼容性与回滚方案
- 删除的历史文档仍可通过 Git 历史恢复。
- 若后续需要某次详细需求，可按 commit 或文件名从历史版本查找。
- 本次不修改业务源码，程序回滚风险低。
## 预计文件变更
- 删除大量历史 `需求分析-*`、`实现方案-*`、`测试方案-*` 文档。
- 删除一次性的 `系统功能描述-2026-05-23-00-32-26.md`。
- 新增本次三件套。
- 更新 `代码编纂工作流.md` 与 `经验记录.md`。
## 提交与部署策略
- 提交信息：`2026-05-24-10-09-37 精简工程分析文档`。
- 提交范围限定为 `工程分析/` 文档治理变更。
- 部署验证沿用项目约定：`npm run build` 后确认当前 `tmux`/frpc 服务可访问。

64
工程分析/测试方案-2026-05-04-02-38-48.md
View File

@@ -1,64 +0,0 @@
# 测试方案
时间戳：2026-05-04-02-38-48
## 测试目标
验证本次工作流文档和项目基线是否可用，并确认前端项目仍可构建。
## 静态检查
- 检查 `工程分析/` 目录是否存在。
- 检查本次需求分析、实现方案、测试方案和经验记录是否存在。
- 检查工作流是否包含人工审核确认节点。
- 检查 `.gitignore` 是否排除医学影像数据、重建模型、依赖目录和构建产物。
## 构建验证
在 `WebSite/` 下执行：
```bash
npm run build
```
预期结果：
- TypeScript/Vite 构建通过。
- 生成 `WebSite/dist/`。
## 部署验证
在 `WebSite/` 下执行：
```bash
npm run dev
```
预期结果：
- Vite 开发服务器启动。
- 默认端口为 `3000`。
- 若端口占用，则记录实际端口或改用可用端口。
## Gitea 备份验证
- 初始化 Git 仓库或复用现有仓库。
- 提交文档备份 commit。
- 添加远程仓库 `origin`。
- 推送到 Gitea。
## 执行结果
- `npm ci` 执行成功，未发现 npm audit 漏洞。
- `npm run build` 执行成功。
- 构建出现 Vite 大 chunk 警告，当前不影响本次文档基线。
- `3000` 端口已被 `/home/wkmgc/Desktop/Seg_Server` 的 node 服务占用。
- 本项目改用 `3001` 端口部署。
- 使用 `tmux` 会话 `revoxelseg-dicom` 托管 Vite 开发服务。
- `curl -I http://127.0.0.1:3001/` 返回 `HTTP/1.1 200 OK`。
- 文档已推送到 Gitea `main` 分支。
## 人工审核状态
- 本文档用于建立工作流基线。
- 后续业务代码修改时，必须在测试方案完成后等待用户二次确认。

102
工程分析/测试方案-2026-05-04-03-08-20.md
View File

@@ -1,102 +0,0 @@
# 测试方案
时间戳：2026-05-04-03-08-20
## 测试目标
验证 title、favicon、登录页 logo、左侧栏 logo 修改生效，并确认项目部署到 `http://192.168.3.11:4000/`。
## 静态检查
- 检查 `WebSite/public/logo.png` 是否存在。
- 检查 `WebSite/index.html`：
- `<title>` 为 `模型逆向系统`。
- favicon 指向 `/logo.png`。
- 检查 `WebSite/src/components/Login.tsx`：
- 登录页顶部使用 `/logo.png`。
- 登录页主标题为 `模型逆向系统`。
- 检查 `WebSite/src/components/Sidebar.tsx`：
- 左上角使用 `/logo.png`。
- 左上角文字为 `模型逆向系统`。
## 构建验证
在 `WebSite/` 下执行：
```bash
npm run build
```
预期结果：
- Vite 构建成功。
- 不出现 TypeScript 编译错误。
## 部署验证
执行端口检查：
```bash
ss -ltnp | rg ':4000\b' || true
```
使用 `tmux` 启动服务：
```bash
tmux new-session -d -s revoxelseg-dicom 'cd /home/wkmgc/Desktop/ReVoxelSeg_DICOM/WebSite && node ./node_modules/vite/bin/vite.js --host 0.0.0.0 --port 4000 --strictPort'
```
验证 HTTP 响应：
```bash
curl -I http://127.0.0.1:4000/
curl -I http://192.168.3.11:4000/
```
预期结果：
- 两个地址均返回 `HTTP/1.1 200 OK`。
## 页面验证
- 打开 `http://192.168.3.11:4000/`。
- 浏览器标签标题显示 `模型逆向系统`。
- 标签页图标显示用户提供的 logo。
- 登录页顶部显示用户提供的 logo。
- 登录后左上角显示用户提供的 logo。
- 折叠侧边栏后 logo 不变形、不溢出。
## 回归风险
- logo 图片尺寸较大时可能影响布局，需要通过固定容器尺寸和 `object-contain` 控制。
- favicon 可能受浏览器缓存影响，需要强制刷新或无痕窗口验证。
- 端口切换可能导致旧 `3001` 地址不再访问当前项目。
## 人工审核状态
已确认并执行。
确认记录：
- 用户已回复 `确认执行`。
## 执行结果
- `WebSite/public/logo.png` 已创建，图片为用户提供的 logo，格式为 PNG RGBA，尺寸 `429 x 429`。
- `WebSite/index.html` 已更新：
- favicon 指向 `/logo.png`。
- title 为 `模型逆向系统`。
- `WebSite/src/components/Login.tsx` 已更新：
- 登录页顶部使用 `/logo.png`。
- 登录页主标题为 `模型逆向系统`。
- `WebSite/src/components/Sidebar.tsx` 已更新：
- 左上角使用 `/logo.png`。
- 左上角文字保持为 `模型逆向系统`。
- `npm run build` 执行成功。
- `npm run lint` 执行成功。
- Vite 构建仍有大 chunk 警告，当前不影响本次 logo/title 修改。
- 已关闭旧的 `revoxelseg-dicom` 部署会话，并使用同名 `tmux` 会话部署到 `4000`。
- `curl -I http://127.0.0.1:4000/` 返回 `HTTP/1.1 200 OK`。
- `curl -I http://192.168.3.11:4000/` 返回 `HTTP/1.1 200 OK`。
- `curl -I http://127.0.0.1:4000/logo.png` 返回 `HTTP/1.1 200 OK` 且 `Content-Type: image/png`。
- 当前监听端口确认：`0.0.0.0:4000`。

132
工程分析/测试方案-2026-05-04-03-21-40.md
View File

@@ -1,132 +0,0 @@
# 测试方案
时间戳：2026-05-04-03-21-40
## 测试目标
验证系统已经从纯前端静态演示升级为前后端协调系统，并确认登录同步、默认项目、恢复出厂设置、NIfTI 导出和部署均可用。
## 静态检查
- 检查 `server.ts` 是否提供 API 和前端页面服务。
- 检查 `src/lib/api.ts` 是否统一封装 API 请求。
- 检查项目列表、系统管理、逆向工作区是否不再依赖硬编码假数据。
- 检查 `.gitignore` 是否排除 `WebSite/data/`、`WebSite/exports/`、DICOM、STL、依赖和构建产物。
## 构建与类型检查
在 `WebSite/` 下执行：
```bash
npm run lint
npm run build
```
预期结果：
- TypeScript 类型检查通过。
- Vite 构建通过。
## API 验证
启动后端服务后验证：
```bash
curl -s http://127.0.0.1:4000/api/health
curl -s http://127.0.0.1:4000/api/session
curl -s http://127.0.0.1:4000/api/projects
curl -s http://127.0.0.1:4000/api/users
curl -s -X POST http://127.0.0.1:4000/api/demo/reset
```
预期结果：
- health 返回 `ok`。
- projects 包含默认项目 `head-ct-demo`。
- 默认项目 `dicomCount` 为 `300`。
- 默认项目 STL 模块包含 `Head_CT_ReConstruct` 下的 `.stl` 文件。
- reset 后默认项目仍存在。
## 登录同步验证
- 浏览器 A 登录 `admin / 123456`。
- 浏览器 B 刷新或等待轮询后读取到已登录状态。
- 浏览器 A 或 B 登出后，另一个浏览器轮询后同步到未登录状态。
命令级验证：
```bash
curl -s -X POST http://127.0.0.1:4000/api/login -H 'Content-Type: application/json' -d '{"account":"admin","password":"123456"}'
curl -s http://127.0.0.1:4000/api/session
curl -s -X POST http://127.0.0.1:4000/api/logout
curl -s http://127.0.0.1:4000/api/session
```
## NIfTI 导出验证
执行：
```bash
curl -L -o /tmp/revoxelseg-mask.nii.gz -X POST http://127.0.0.1:4000/api/projects/head-ct-demo/export-mask
file /tmp/revoxelseg-mask.nii.gz
gzip -t /tmp/revoxelseg-mask.nii.gz
```
预期结果：
- 下载文件存在。
- 文件为 gzip 压缩数据。
- `gzip -t` 校验通过。
- 响应文件名后缀为 `.nii.gz`。
## 页面验证
- 打开 `http://192.168.3.11:4000/`。
- 登录页可正常登录。
- 总体概况显示后端统计数据。
- 项目库默认显示头部 CT 演示项目。
- 项目详情展示 `Head_CT_DICOM` 和 `Head_CT_ReConstruct` 相关信息。
- 系统管理页点击“恢复演示环境出厂设置”后，项目仍恢复为默认 DICOM/STL。
- 逆向工作区可导出 `nii.gz` mask。
## 回归风险
- 引入后端后部署方式从纯 Vite 改为 Express + Vite 中间件，需要确认 `4000` 服务由 `server.ts` 托管。
- 后端共享登录状态是演示同步方案，不等同生产级多用户 session。
- NIfTI 文件当前为演示 mask，非医学级真实 STL 体素化结果。
## 人工审核状态
本次用户明确要求无需人工二次确认。
状态：自动确认，继续执行。
## 执行结果
- `npm run lint` 执行成功。
- `npm run build` 执行成功。
- Vite 仍有大 chunk 警告，当前不影响本次功能。
- 已新增 Express 后端 `server.ts`，并通过 `npm run serve -- --host 0.0.0.0 --port 4000` 托管前后端。
- `GET /api/health` 返回 `ok: true`。
- `GET /api/projects` 返回默认项目 `head-ct-demo`。
- 默认项目载入结果：
- `dicomCount: 300`
- `modelCount: 9`
- `dicomPath: Head_CT_DICOM`
- `modelPath: Head_CT_ReConstruct`
- `POST /api/demo/reset` 执行成功，重置后默认项目仍载入 `Head_CT_DICOM` 与 `Head_CT_ReConstruct`。
- `POST /api/login` 使用 `admin / 123456` 登录成功。
- `GET /api/session` 登录后返回 `authenticated: true`。
- `POST /api/logout` 登出成功。
- `GET /api/session` 登出后返回 `authenticated: false`。
- `POST /api/projects/head-ct-demo/export-mask?format=nii.gz` 执行成功。
- `/tmp/revoxelseg-mask.nii.gz` 通过 `gzip -t` 校验。
- 解压后 NIfTI magic 为 `n+1\0`。
- `POST /api/projects/head-ct-demo/export-mask?format=nii` 执行成功，生成未压缩 `.nii`。
- `http://192.168.3.11:4000/` 返回 `HTTP/1.1 200 OK`。
- 当前部署由 `tmux` 会话 `revoxelseg-dicom` 托管。
## 剩余说明
- 当前导出的 NIfTI mask 是可下载、格式有效的演示分割体数据。
- 真实医学级 STL 反向体素化仍需后续加入 DICOM 空间解析、STL 坐标配准、网格体素填充和标签体系。

97
工程分析/测试方案-2026-05-04-03-50-07.md
View File

@@ -1,97 +0,0 @@
# 测试方案
时间戳：2026-05-04-03-50-07
## 测试目标
验证概况统计、图表、真实 DICOM 预览、真实 STL 渲染、分割结果视图、项目创建/重命名、README 和部署均正常。
## 静态检查
- 检查 `Overview.tsx` 图表容器是否有稳定尺寸。
- 检查 `ProjectLibrary.tsx` 是否包含三个 tab：`DICOM 影像`、`3D 模型`、`分割结果`。
- 检查 STL 模块列表不再对首个模块默认蓝色高亮。
- 检查 README 是否包含项目构建和运行方案。
## 构建与类型检查
```bash
cd WebSite
npm run lint
npm run build
```
预期结果：
- TypeScript 检查通过。
- Vite 构建通过。
## API 验证
```bash
curl -s http://127.0.0.1:4000/api/overview
curl -s 'http://127.0.0.1:4000/api/projects/head-ct-demo/dicom-preview?slice=0'
curl -I 'http://127.0.0.1:4000/api/projects/head-ct-demo/models/会厌.stl'
curl -s -X POST http://127.0.0.1:4000/api/projects -H 'Content-Type: application/json' -d '{"name":"测试创建项目"}'
curl -s -X PATCH http://127.0.0.1:4000/api/projects/head-ct-demo -H 'Content-Type: application/json' -d '{"name":"头部 CT 模型逆向体素化演示"}'
```
预期结果：
- overview 返回平稳趋势和 `exportedMaskProjects`。
- DICOM preview 返回 `width`、`height`、`pixels`。
- STL 文件返回 200。
- 创建项目返回新项目。
- 重命名项目成功。
## 页面验证
- 总体概况不再显示“已处理项目总数 = 1”的误导文案。
- 控制台不再出现 Recharts 宽高 -1 警告。
- 项目库 DICOM 影像显示真实灰度切片。
- 项目库 3D 模型显示真实 STL。
- 项目库新增分割结果页，可下载 NII/NII.GZ。
- 项目列表可创建项目。
- 项目列表已有项目可点击编辑图标重命名。
- STL 模块列表所有项目同等样式，没有“会厌”特殊蓝色突出。
## 回归风险
- DICOM 解析兼容性有限，当前先针对本项目 Little Endian CT 数据。
- STL 文件较大时首次加载可能需要等待。
- 新建项目默认无 DICOM/STL 数据，作为项目管理演示项。
## 人工审核状态
本次用户明确要求无需人工二次确认。
状态：自动确认，继续执行。
## 执行结果
- `npm run lint` 执行成功。
- `npm run build` 执行成功。
- Vite 仍有大 chunk 警告，当前不影响本次功能。
- `GET /api/overview` 返回：
- `totalProjects: 1`
- `exportedMaskProjects: 0`
- `dicomCount: 300`
- `modelCount: 9`
- 已将“已处理项目”语义改为“已导出 Mask 项目”，避免项目总数为 1 时误导为已处理 1。
- `GET /api/projects/head-ct-demo/dicom-preview?slice=0` 返回：
- `width: 512`
- `height: 512`
- `total: 300`
- `fileName: 1.dcm`
- `pixels` base64 数据。
- `GET /api/projects/head-ct-demo/models/会厌.stl` 返回 `HTTP/1.1 200 OK`。
- `POST /api/projects` 创建项目成功。
- `PATCH /api/projects/:id` 重命名项目成功。
- `POST /api/demo/reset` 执行成功，测试创建项目已清理，默认项目恢复。
- headless Chrome 打开页面后未捕获 `width(-1)`、`height(-1)` 或 Recharts 相关警告。
- `http://192.168.3.11:4000/` 返回 `HTTP/1.1 200 OK`。
- 当前服务由 `tmux` 会话 `revoxelseg-dicom` 托管。
## 本次未创建 Python/conda 环境原因
本次 DICOM 预览、STL 渲染和 NIfTI 演示导出均可由现有 Node/React/Three.js 技术栈完成。为了避免引入不必要的运行环境复杂度，本次不创建 conda 环境；README 已说明后续真实体素化算法阶段再引入 Python/conda。

108
工程分析/测试方案-2026-05-04-04-12-34.md
View File

@@ -1,108 +0,0 @@
# 测试方案
时间戳：2026-05-04-04-12-34
## 测试目标
验证项目库导入按钮语义、DICOM 三方向切片、STL 颜色透明度控制、项目创建弹窗、编辑自动保存和删除确认能力。
## 静态检查
- 检查 `ProjectLibrary.tsx`：
- DICOM/3D 顶部第二按钮为“导入”。
- 分割结果页无顶部第二按钮。
- 创建项目通过弹窗触发。
- 删除项目通过确认弹窗触发。
- 编辑项目名称无保存按钮，失焦自动保存。
- STL 模块包含颜色输入和透明度滑块。
- 删除无意义状态点。
- 检查 `server.ts`：
- DICOM preview 支持 `plane`。
- 项目支持 `DELETE`。
## 构建与类型检查
```bash
cd WebSite
npm run lint
npm run build
```
预期：
- TypeScript 检查通过。
- Vite 构建通过。
## API 验证
```bash
curl -s 'http://127.0.0.1:4000/api/projects/head-ct-demo/dicom-preview?plane=axial&slice=0'
curl -s 'http://127.0.0.1:4000/api/projects/head-ct-demo/dicom-preview?plane=sagittal&slice=256'
curl -s 'http://127.0.0.1:4000/api/projects/head-ct-demo/dicom-preview?plane=coronal&slice=256'
curl -s -X POST http://127.0.0.1:4000/api/projects -H 'Content-Type: application/json' -d '{"name":"删除测试项目"}'
curl -s -X DELETE http://127.0.0.1:4000/api/projects/<id>'
```
预期：
- 三方向 DICOM preview 均返回 `width`、`height`、`pixels`、`plane`。
- 创建项目成功。
- 删除项目成功。
## 页面验证
- DICOM 页右侧控制条圆点与轨道对齐。
- DICOM 页显示 `第 n / 总数`。
- 可切换横断面、矢状面、冠状面。
- 3D 页整体眼睛可控制所有 STL 显示/隐藏。
- 单个 STL 的颜色和透明度控制影响模型渲染。
- 项目创建由弹窗完成。
- 项目编辑失焦自动保存。
- 项目删除需要二次确认。
## 回归风险
- 矢状面/冠状面每次请求会读取多张 DICOM，可能有延迟。
- 多 STL 同时显示时首屏加载可能较慢。
## 人工审核状态
本次用户明确要求无需人工二次确认。
状态：自动确认，继续执行。
## 执行结果
- `npm run lint` 执行成功。
- `npm run build` 执行成功。
- Vite 仍有大 chunk 警告，当前不影响本次功能。
- `GET /api/projects/head-ct-demo/dicom-preview?plane=axial&slice=0` 返回：
- `plane: axial`
- `width: 512`
- `height: 512`
- `total: 300`
- `GET /api/projects/head-ct-demo/dicom-preview?plane=sagittal&slice=0` 返回：
- `plane: sagittal`
- `width: 300`
- `height: 512`
- `total: 512`
- `GET /api/projects/head-ct-demo/dicom-preview?plane=coronal&slice=0` 返回：
- `plane: coronal`
- `width: 300`
- `height: 512`
- `total: 512`
- `POST /api/projects` 创建删除测试项目成功。
- `DELETE /api/projects/:id` 删除测试项目成功。
- `POST /api/demo/reset` 执行成功，演示环境已恢复默认项目。
- headless Chrome 打开页面后未捕获 Recharts 宽高警告、`Uncaught` 或页面错误。
- `http://192.168.3.11:4000/` 返回 `HTTP/1.1 200 OK`。
- 当前服务由 `tmux` 会话 `revoxelseg-dicom` 托管。
## 页面侧验证点
- 顶部第二按钮在 `DICOM 影像` 和 `3D 模型` 视图显示为“导入”。
- `分割结果` 视图顶部不显示额外导出按钮，只保留下方 NII/NII.GZ 下载按钮。
- 项目创建入口改为点击 `+` 后弹窗。
- 项目删除通过确认弹窗执行。
- 项目编辑输入框失焦或回车自动保存。
- 3D 模型侧栏每个 STL 提供颜色和透明度控制，整体眼睛控制所有 STL 可见性。

78
工程分析/测试方案-2026-05-04-04-58-36.md
View File

@@ -1,78 +0,0 @@
# 测试方案
时间戳：2026-05-04-04-58-36
## 测试目标
验证项目列表按钮不重叠、DICOM 三方向和显示模式可用、3D 模型有加载进度并可见、逆向工作区显示当前项目和融合视图，以及控制台不再出现 `THREE.Clock` 警告。
## 静态检查
- 检查项目列表标题区 `+` 与收缩按钮布局。
- 检查 DICOM preview API 是否支持 `mode`。
- 检查项目库是否使用原生 Three.js renderer 并显示加载进度。
- 检查逆向工作区是否显示当前项目。
## 构建与类型检查
```bash
cd WebSite
npm run lint
npm run build
```
预期：
- TypeScript 检查通过。
- Vite 构建通过。
## API 验证
```bash
curl -s 'http://127.0.0.1:4000/api/projects/head-ct-demo/dicom-preview?plane=axial&slice=0&mode=default'
curl -s 'http://127.0.0.1:4000/api/projects/head-ct-demo/dicom-preview?plane=sagittal&slice=128&mode=bone'
curl -s 'http://127.0.0.1:4000/api/projects/head-ct-demo/dicom-preview?plane=coronal&slice=128&mode=contrast'
curl -s 'http://127.0.0.1:4000/api/projects/head-ct-demo/models/头部.stl/preview?limit=2000'
```
预期：
- DICOM 均返回 `width`、`height`、`pixels`、`mode`。
- STL 预览返回 `triangleCount`、`sampledTriangles`、`vertices`。
## 页面验证
- 项目列表标题区按钮不重叠。
- DICOM 视图可切换多种显示模式。
- 矢状面/冠状面滑动有图像变化。
- 3D 视图显示加载进度条，加载后模型可见。
- 逆向工作区显示当前项目，融合视图显示 DICOM 与模型中心对齐叠加效果。
## 控制台验证
- headless Chrome 打开页面后不捕获 `THREE.Clock`。
- 不捕获 `Uncaught`、`Error`。
## 实际执行结果
执行时间：2026-05-04
- `npm run lint`：通过。
- `npm run build`：通过，仅保留 Vite chunk size 提示。
- DICOM API：
- axial default：`512x512 150/300 WW=360 WL=60`
- sagittal bone：`300x512 128/512 WW=2000 WL=500`
- coronal contrast：`300x512 256/512 WW=180 WL=80`
- axial soft：`512x512 150/300 WW=400 WL=40`
- STL 预览 API：`头部.stl 2571248 2000 18000`。
- Headless Chrome 自动化：
- 项目库进入成功。
- 3D 模型页进入成功，模型加载/二维兜底状态可见。
- 逆向工作区进入成功，当前项目与融合说明可见。
- `THREE.Clock`、`non-passive`、`Uncaught` 捕获数为 0。
## 人工审核状态
本次用户明确要求无需人工二次确认。
状态：自动确认，继续执行。

62
工程分析/测试方案-2026-05-04-05-20-16.md
View File

@@ -1,62 +0,0 @@
# 测试方案 - 2026-05-04-05-20-16
## 静态检查
- 执行 `npm run lint`，确认 TypeScript 类型检查通过。
- 执行 `npm run build`，确认生产构建通过。
## 集成验证
- 调用 `/api/projects/head-ct-demo/dicom-preview` 验证：
- `plane=axial`
- `plane=sagittal`
- `plane=coronal`
- `mode=bone`
- 调用 `/api/projects/head-ct-demo/dicom-archive` 验证压缩包响应头和文件名。
- 调用 `/api/projects/head-ct-demo/models/:fileName/preview` 验证 STL 预览顶点数据非空。
## 关键业务场景验证
- 项目库 DICOM 视图：
- 长按上下箭头能连续改变切片。
- 三个面切换后图像显示完整。
- 左/右旋转 90 度后画布方向变化。
- 下载当前 PNG 命名包含项目、平面、切片、模式、旋转角度。
- 下载 DICOM 压缩包可触发。
- 项目库 3D 模型视图：
- 模型加载进度可见。
- 加载完成后模型可见，而不是空白画布。
- 颜色、透明度、显示/隐藏状态仍可影响渲染。
- 逆向工作区：
- 顶部不再显示 `Head_CT_DICOM ↔ Head_CT_ReConstruct`。
- 当前项目上下文仍可见。
## 医学影像数据相关边界验证
- DICOM 序列按文件名自然排序。
- 矢状面/冠状面重建裁切保留边距，避免把真实人体区域裁掉。
- 显示模式与三平面组合时返回的 `total`、`slice`、`width`、`height` 合理。
## 回归风险
- DICOM 预览缓存键应包含平面、模式和切片，避免错图。
- PNG 下载应和当前旋转状态一致。
- 3D 模型抽样数量不能过高导致页面阻塞。
## 人工审核状态
用户已明确本次测试方案无需二次确认，记录后直接执行。
## 执行结果
- `npm run lint`：通过。
- `npm run build`：通过；Vite 提示 bundle 超过 500 kB，为 Three.js/Recharts 等现有依赖带来的体积警告，不阻断构建。
- `GET /api/projects/head-ct-demo/dicom-preview?plane=axial&slice=150&mode=default`：通过，返回 `512x512`，`total=300`，文件名 `151.dcm`。
- `GET /api/projects/head-ct-demo/dicom-preview?plane=sagittal&slice=256&mode=bone`：通过，返回 `300x421`，`total=512`。
- `GET /api/projects/head-ct-demo/dicom-preview?plane=coronal&slice=256&mode=soft`：通过，返回 `300x512`，`total=512`。
- `HEAD /api/projects/head-ct-demo/dicom-archive`：通过，返回 `Content-Type: application/gzip`，文件名 `head-ct-demo-Head_CT_DICOM-300-files.tar.gz`。
- `GET /api/projects/head-ct-demo/models/会厌.stl/preview?limit=1200`：通过，返回 `1159` 个抽样三角面、`10431` 个顶点数值。
- 无头 Chrome 前端验证：登录后进入项目库 3D 模型页，在 WebGL 不可用场景自动生成二维兜底预览，canvas 尺寸 `1236x567`，像素采样 `nonBackground=67`，确认不是空白画布。
- 已重启部署到 `http://192.168.3.11:4000/`，tmux 会话：`revoxelseg-dicom`。

73
工程分析/测试方案-2026-05-04-05-41-22.md
View File

@@ -1,73 +0,0 @@
# 测试方案 - 2026-05-04-05-41-22
## 静态检查
- 执行 `npm run lint`，确认 TypeScript 类型检查通过。
- 执行 `npm run build`，确认生产构建通过。
## 集成测试
- 调用 STL preview API：
- `limit=6000`
- `limit=16000`
- `limit=36000`
- 确认返回顶点数量随实体化程度增加，且响应不报错。
- 调用 DICOM preview API，确认连续请求不同 slice 时均可返回合理 `slice/total/width/height`。
## 关键业务场景验证
### 3D 模型页
- 默认进入后模型可见。
- 实体化程度从“预览”切换到“标准/精细”后，模型表面更连续，而不是纯点云感。
- 开启“整体白色实体”后，显示效果接近参考图的灰白实体模型。
- 调整旋转 X/Y/Z、平移 X/Y/Z、缩放后，模型位姿即时变化。
- 点击重置后，位姿恢复默认。
- 隐藏/显示单个 STL、调整颜色、透明度仍正常。
- WebGL 不可用时二维兜底仍可见，不出现空白画布。
### DICOM 切片页
- 长按上箭头时，切片编号连续增加，图像连续变化。
- 长按下箭头时，切片编号连续减少，图像连续变化。
- 快速连续切换时，不出现旧请求覆盖新切片的错帧。
- 到达首帧/末帧时不越界。
### 逆向工作区
- 顶部全局 header 仍显示“逆向工作区”。
- 页面内容区不再重复显示第二个“逆向工作区”。
- 页面内容区不再出现上方重复“当前项目：xxx”副标题。
- 项目标签行字号变大，且显示当前项目、DICOM 数量、STL 数量。
## 医学影像数据相关边界验证
- DICOM 连续切片时保留当前 plane、mode、rotation 状态。
- STL 实体化程度不改变各构件的原始相对空间关系，只改变抽样密度和显示材质。
- 位姿控制作用于整体模型 group，不改变单个 STL 的相对拼装位置。
## 回归风险
- 高实体化程度可能提升渲染压力，需要在 UI 中保留“预览”档位。
- DICOM 连续请求可能造成响应乱序，需要请求序号保护。
- 逆向工作区删除标题后仍需保证用户知道当前处于哪个页面，依赖全局 header。
## 人工审核状态
用户已回复“确认方案”，按本测试方案执行验证。
## 执行结果
- `npm run lint`：通过。
- `npm run build`：通过；Vite 仍提示 bundle 超过 500 kB，为现有 Three.js/Recharts 依赖带来的非阻断警告。
- STL preview API 验证：
- `limit=6000`：返回 `5795` 个抽样三角面、`52155` 个顶点数值。
- `limit=16000`：返回 `8692` 个抽样三角面、`78228` 个顶点数值。
- `limit=36000`：返回 `17384` 个抽样三角面、`156456` 个顶点数值。
- DICOM 连续切片 API 验证：`slice=120~124` 均返回 `512x512`、`total=300`，文件名按 `121.dcm` 到 `125.dcm` 连续变化。
- 无头 Chrome 前端验证：
- 3D 模型页存在“模型显示、预览、标准、精细、白色实体、整体位姿、旋转 X、平移 Z、缩放”等控件。
- WebGL 不可用场景仍生成二维预览 canvas，尺寸 `1172x567`。
- 逆向工作区正文不再重复页面标题：`逆向工作区` 只出现 1 次。
- `当前项目：头部 CT 模型逆向体素化演示` 只出现 1 次，并保留 `DICOM 300`、`STL 9`。
- 已重新部署到 `http://192.168.3.11:4000/`，tmux 会话：`revoxelseg-dicom`。

68
工程分析/测试方案-2026-05-04-05-56-34.md
View File

@@ -1,68 +0,0 @@
# 测试方案 - 2026-05-04-05-56-34
## 静态检查
- 执行 `npm run lint`，确认 TypeScript 类型检查通过。
- 执行 `npm run build`，确认生产构建通过。
## 集成测试
- DICOM preview API：
- 验证 axial/sagittal/coronal 均返回。
- 验证 sagittal/coronal 返回的 `spacing`、`physicalSize`、`width/height` 合理。
- DICOM info API：
- 验证返回 patient/study/series/image/window/spacing/sequence/source 分组。
- 验证 Pixel Spacing、Slice Spacing、Rows、Columns、文件数量等信息存在。
- STL preview API：
- 验证 `limit=6000/16000/36000/72000` 返回不报错。
## 关键业务场景验证
- DICOM 影像页：
- 矢状面/冠状面不再异常扁平。
- 点击信息按钮弹出详情面板。
- 详情面板展示像素间距、切片间距、切片厚度、矩阵、物理尺寸。
- 3D 模型页：
- 不再显示白色实体和自动旋转开关。
- 实体化档位包含“超精细”。
- 默认正向静止摆放。
- 重置位姿按钮位于“整体位姿”标题右侧。
- 左键拖拽旋转，右键/Shift 拖拽平移，滚轮缩放。
- 画布交互后右侧整体位姿滑块数值同步变化。
## 医学影像数据相关边界验证
- DICOM tag 缺失时使用 fallback，不导致接口 500。
- 切片间距优先 Image Position Patient 差值，再 fallback 到 Spacing Between Slices、Slice Thickness、1mm。
- 多平面物理比例不改变切片总数和当前切片编号逻辑。
## 回归风险
- 物理比例重采样可能增大图像尺寸，需要限制最大输出尺寸。
- 超精细 STL 预览可能变慢，需要保留低档位。
- 鼠标交互需避免页面滚动和右键菜单干扰。
## 人工审核状态
用户已明确本次无需人工二次确认，按本方案执行验证。
## 执行结果
- `npm run lint`：通过。
- `npm run build`：通过；Vite 仍提示 bundle 超过 500 kB，为现有 Three.js/Recharts 依赖导致的非阻断警告。
- DICOM preview API 验证：
- `sagittal` 返回 `384x421`，`spacing.slice=1mm`、`displayY=0.78125mm`，物理尺寸约 `300mm x 328.906mm`。
- `coronal` 返回 `384x512`，`spacing.slice=1mm`、`displayY=0.78125mm`，物理尺寸约 `300mm x 400mm`。
- DICOM info API 验证：
- 返回患者 `WANG FANG`、`CT`、文件数 `300`、矩阵 `512x512`。
- 返回 `row/column spacing=0.781mm`、`slice=1mm`，来源 `ImagePositionPatient`。
- 返回物理尺寸 `400mm x 400mm x 299mm`。
- STL preview API 验证：
- `limit=6000/16000/36000/72000` 均返回，首个 STL 在超精细档达到原始 `17384` 个三角面。
- 无头 Chrome 前端验证：
- DICOM 信息按钮存在。
- DICOM 信息弹窗存在，并展示像素行间距、切片间距、物理尺寸。
- 3D 页存在“超精细”，已移除“白色实体”和“自动旋转”。
- 默认位姿滑块为 `0,0,0 / 0,0,0 / 1`。
- 页面包含“左键旋转”和“滚轮缩放”提示。
- 已重新部署到 `http://192.168.3.11:4000/`，tmux 会话：`revoxelseg-dicom`。

45
工程分析/测试方案-2026-05-07-16-20-46.md
View File

@@ -1,45 +0,0 @@
# 测试方案 - 2026-05-07-16-20-46
## 静态检查
- 执行 `npm run lint`。
- 执行 `npm run build`。
## 集成测试
- 验证 STL preview API 在 `6000/16000/36000/72000` 档位下可返回。
- 验证 DICOM preview 与 DICOM info API 仍可返回，确保上一轮相关改动未受影响。
## 前端验证
- 无头 Chrome 登录后进入项目库 3D 模型页：
- 控件包含“超精细”，不包含“白色实体/自动旋转”。
- 默认位姿滑块为旋转 0、平移 0、缩放 1。
- canvas 非空。
- 模拟拖拽/滚轮后检查位姿数值变化。
- 点击重置位姿后检查数值恢复默认。
## 回归风险
- 无头 Chrome 可能走二维兜底预览，但仍可验证控件和位姿状态。
- 真实 WebGL 视角需要用户目视确认参考图匹配度；本次以默认俯视相机为工程修正。
## 人工审核状态
用户已明确本次无需人工二次确认，按本方案执行验证。
## 执行结果
- `npm run lint`：通过。
- `npm run build`：通过；Vite 大 chunk 体积提示为非阻断警告。
- 已将 3D 默认相机从斜向等距视角改为俯视相机：`camera.position=(0,0,6)`，`lookAt(0,0,0)`。
- 无头 Chrome 前端验证：
- 3D 页 canvas 非空，尺寸 `1172x567`。
- 默认位姿滑块为 `0,0,0 / 0,0,0 / 1`。
- “超精细”存在，“白色实体/自动旋转”不存在。
- DICOM 信息面板仍可打开。
- 关联 API 回归验证：
- DICOM 多平面物理比例接口正常。
- DICOM 信息接口正常。
- STL 四档预览接口正常。
- 已重新部署到 `http://192.168.3.11:4000/`，tmux 会话：`revoxelseg-dicom`。

71
工程分析/测试方案-2026-05-07-16-35-52.md
View File

@@ -1,71 +0,0 @@
# 测试方案 - 2026-05-07-16-35-52
## 静态检查
1. 执行前确认工作区状态：
- `git status --short --branch`
2. 前端类型和构建检查：
- `cd WebSite && npm run build`
3. 如项目存在 lint 脚本，执行：
- `cd WebSite && npm run lint`
## 单元或集成测试
当前项目未发现独立单元测试体系，本次以构建检查、运行时 API 检查和浏览器人工/截图验证为主。
## 关键业务场景验证
1. 打开 `http://192.168.3.11:4000/`。
2. 进入 `项目库 - 3D 模型`。
3. 验证 `整体位姿` 标题右侧出现：
- `重置旋转位姿`
- `重置平移缩放位姿`
4. 验证旋转 X/Y/Z：
- 点击 `-90°` 后角度减少 90。
- 点击 `+90°` 后角度增加 90。
- 数值不会超过 `[-180, 180]`。
5. 验证平移 X/Y/Z：
- 点击负向按钮后对应轴负向移动。
- 点击正向按钮后对应轴正向移动。
- 数值不会超过 `[-2, 2]`。
6. 验证缩放：
- 快捷按钮可放大/缩小。
- 数值不会超过 `[0.5, 2.5]`。
7. 验证两个重置按钮：
- `重置旋转位姿` 只影响旋转值。
- `重置平移缩放位姿` 只影响平移和缩放值。
8. 验证鼠标交互：
- 左键拖拽旋转模型。
- 右键或 Shift 拖拽平移模型。
- 滚轮缩放模型。
- 控件数值与鼠标操作同步变化。
9. 验证旋转中心：
- 旋转时模型围绕整体几何中心转动。
- STL 构件相对拼装关系不被破坏。
10. 验证右下角方位提示：
- 显示 X/Y/Z 三轴。
- 显示当前旋转角度。
- 不遮挡模型状态信息和右侧控制面板。
## 医学影像数据相关边界验证
- 本次不修改 DICOM 数据解析、空间 spacing、mask 导出等医学影像数据链路。
- 回归确认项目列表、DICOM 影像页、分割结果页仍可进入。
## 回归风险
- Three.js group 层级调整可能影响模型初始视野。
- 旋转中心修正可能暴露部分 STL 原始坐标异常，需要通过默认项目 `Head_CT_ReConstruct` 验证。
- 快捷按钮布局可能在窄屏右侧面板中换行，需要确保不遮挡滑块和值。
## 人工审核状态
- 测试方案：用户已确认。
- 确认信息：用户回复“都确认，后续直接搞”。
## 执行记录
- `npm run build`：通过。
- `npm run lint`：通过，实际执行 `tsc --noEmit`。
- `curl -I http://127.0.0.1:4000/`：返回 `HTTP/1.1 200 OK`。
- `curl -s http://127.0.0.1:4000/api/projects`：返回默认项目 `头部 CT 模型逆向体素化演示`，DICOM 300、STL 9。

51
工程分析/测试方案-2026-05-07-16-53-23.md
View File

@@ -1,51 +0,0 @@
# 测试方案 - 2026-05-07-16-53-23
## 静态检查
1. `git status --short --branch`
2. `cd WebSite && npm run build`
3. `cd WebSite && npm run lint`
## 单元或集成测试
当前项目没有独立单元测试体系，本次采用构建、类型检查、API 冒烟和浏览器人工验证。
## 关键业务场景验证
1. 打开 `http://192.168.3.11:4000/`。
2. 进入 `项目库 - 3D 模型`。
3. 验证模型正常加载，且右下角坐标系可见。
4. 用滑块或 `±90°` 按钮旋转 X/Y/Z：
- 模型围绕自身中心旋转。
- 右下角坐标系同步改变方向。
5. 用鼠标左键拖拽旋转：
- 控件数值同步变化。
- 旋转中心保持在模型内部几何中心。
6. 在旋转后切换 `预览/标准/精细/超精细`：
- 模型不发生离谱偏移。
- 当前旋转位姿继续保留。
7. 检查两个重置按钮：
- `重置旋转位姿` 和 `重置平移缩放位姿` 字体颜色一致。
- 重置逻辑仍分别只影响对应位姿维度。
## 医学影像数据相关边界验证
- 本次不修改 DICOM 解析、切片显示、分割结果导出。
- 回归确认 `/api/projects` 能正常返回默认项目。
## 回归风险
- Three.js canvas 挂载容器变更可能导致尺寸计算或 resize 失效。
- SVG 坐标轴投影使用当前欧拉角，需保证与模型旋转顺序一致。
- 切换细节档时仍需重新请求 STL preview，加载中的短暂进度变化是预期行为。
## 人工审核状态
- 本次免二次确认。
## 执行记录
- `npm run build`：通过。
- `npm run lint`：通过，实际执行 `tsc --noEmit`。
- 重新部署后 `curl -I http://127.0.0.1:4000/`：返回 `HTTP/1.1 200 OK`。
- 重新部署后请求 `会厌.stl` preview：返回 `bounds.min/max`，确认后端已提供稳定全量包围盒。

44
工程分析/测试方案-2026-05-07-17-05-43.md
View File

@@ -1,44 +0,0 @@
# 测试方案 - 2026-05-07-17-05-43
## 静态检查
1. `git status --short --branch`
2. `cd WebSite && npm run build`
3. `cd WebSite && npm run lint`
## 单元或集成测试
当前项目没有独立单元测试体系，本次采用构建、类型检查、API 冒烟和页面人工验证。
## 关键业务场景验证
1. 打开 `http://192.168.3.11:4000/`。
2. 进入 `项目库 - 3D 模型`。
3. 验证 `模型显示` 中不再出现 `预览`。
4. 验证 `模型显示` 中出现 `实体`。
5. 点击 `标准 / 精细 / 超精细 / 实体`：
- 模型都可以加载完成。
- 当前位姿不丢失。
- 实体档位视觉上更接近面片实体，而不是稀疏预览。
6. 验证右侧构件透明度、颜色、眼睛显示控制仍可用。
## 医学影像数据相关边界验证
- 本次不修改 DICOM 解析、切片显示、分割结果导出。
- 回归确认 `/api/projects` 正常返回默认项目。
## 回归风险
- 实体档位请求更多 STL 顶点，首次加载可能更慢。
- 若浏览器 WebGL 性能不足，实体档位可能出现卡顿。
## 人工审核状态
- 本次免二次确认。
## 执行记录
- `npm run build`：通过。
- `npm run lint`：通过，实际执行 `tsc --noEmit`。
- 重新部署后 `curl -I http://127.0.0.1:4000/`：返回 `HTTP/1.1 200 OK`。
- 重新部署后请求 `会厌.stl` preview 且 `limit=200000`：返回 `triangleCount=17384`、`sampledTriangles=17384`，确认实体档位可返回完整三角面。

51
工程分析/测试方案-2026-05-07-17-28-34.md
View File

@@ -1,51 +0,0 @@
# 测试方案 - 2026-05-07-17-28-34
## 静态检查
1. `git status --short --branch`
2. `cd WebSite && npm run build`
3. `cd WebSite && npm run lint`
## 单元或集成测试
当前项目没有独立单元测试体系，本次采用构建、类型检查、API 冒烟和页面运行时验证。
## 关键业务场景验证
1. 打开 `http://192.168.3.11:4000/`。
2. 进入 `逆向工作区`。
3. 验证 `影像与模型融合视角` 出现三维融合场景。
4. 验证 DICOM 体是黑色长方体，体表面显示当前范围最后一张切片。
5. 调整切片起点/终点：
- 显示范围变化。
- 范围文本同步变化。
- 场景重新加载后仍可交互。
6. 验证 STL 模型叠加在 CT 体上。
7. 鼠标拖拽整体场景：
- DICOM 体和 STL 模型一起旋转。
8. 调整模型位姿：
- 只有 STL 模型相对 DICOM 体移动或旋转。
9. 验证 `开始自动配准`、`导出 NII.GZ` 按钮仍可操作。
## 医学影像数据相关边界验证
- 融合接口最多返回 64 张切片，避免过量纹理。
- 切片起止范围需要 clamp 到 `[0, dicomCount - 1]`。
- DICOM spacing 与 physicalSize 需要从现有体数据缓存中输出。
## 回归风险
- Three.js 纹理和 STL 共同渲染会增加 GPU 压力。
- 逆向工作区布局变更可能影响 Mask 选择和导出信息。
- 当前融合为归一化同场景叠加，不是最终医学空间刚性配准矩阵。
## 人工审核状态
- 本次免二次确认。
## 执行记录
- `npm run lint`：通过，实际执行 `tsc --noEmit`。
- `npm run build`：通过。
- 重新部署后 `curl -I http://127.0.0.1:4000/`：返回 `HTTP/1.1 200 OK`。
- 重新部署后请求 `GET /api/projects/head-ct-demo/dicom-fusion-volume?start=0&end=49&mode=soft`：返回 `width=256`、`height=256`、`start=0`、`end=49`、`total=300`、50 个切片索引、spacing 和 physicalSize。

51
工程分析/测试方案-2026-05-07-18-11-12.md
View File

@@ -1,51 +0,0 @@
# 测试方案 - 2026-05-07-18-11-12
## 静态检查
1. `git status --short --branch`
2. `cd WebSite && npm run build`
3. `cd WebSite && npm run lint`
## 单元或集成测试
当前项目没有独立单元测试体系，本次采用构建、类型检查、API 冒烟和页面运行验证。
## 关键业务场景验证
1. 左侧导航显示 `模型库`。
2. 点击 `模型库` 默认进入项目库 3D 模型页。
3. 项目库构件层级：
- 点击单个构件眼睛，模型可隐藏/显示。
- 顶部眼睛可全隐藏/全显示。
- 每个构件显示 `ID`。
- ID 可修改为 1 到 255。
- ID 修改为 0 时应被限制为 1。
4. 逆向工作区：
- `分割 Mask` 文案变为 `可视化工具栏`。
- 工具栏包含模型显示、整体位姿保存/选择、构件层级。
- 模型显示档位切换后场景仍可加载。
- 保存位姿后可在选择框中切回。
- 构件眼睛、颜色、透明度可影响融合视角中的模型显示。
## 医学影像数据相关边界验证
- 本次不修改 DICOM 解析和融合体接口。
- 回归确认 `/api/projects` 和 `/api/projects/head-ct-demo/dicom-fusion-volume` 可访问。
## 回归风险
- 逆向工作区模型样式状态变化会触发 Three.js 重建，可能带来短暂加载。
- 左侧新增导航项可能影响当前 header 文案和 activeView 判断。
- 项目库构件 ID 目前未持久化，刷新页面后回到默认 1 到 N。
## 人工审核状态
- 本次免二次确认。
## 执行记录
- `npm run lint`：通过，实际执行 `tsc --noEmit`。
- `npm run build`：通过。
- 重新部署后 `curl -I http://127.0.0.1:4000/`：返回 `HTTP/1.1 200 OK`。
- `GET /api/projects`：正常返回默认项目，包含 9 个 STL 文件。
- `GET /api/projects/head-ct-demo/dicom-fusion-volume?start=0&end=10&mode=soft`：正常返回 DICOM 融合体数据。

46
工程分析/测试方案-2026-05-07-18-42-53.md
View File

@@ -1,46 +0,0 @@
# 测试方案 - 2026-05-07-18-42-53
## 静态检查
- 执行 `npm run lint`，确认 TypeScript 类型检查通过。
- 执行 `npm run build`，确认生产构建通过。
## 单元或集成测试
- 使用现有 API 和页面构建流程做集成验证：
- `GET /api/projects` 返回项目数据且包含共享 `moduleStyles`。
- `PATCH /api/projects/:projectId/module-styles` 可保存构件 ID。
- 重新读取项目后构件 ID 保持一致。
## 关键业务场景验证
1. 项目库 3D 模型构件层级修改 ID 后，进入逆向工作区可视化工具栏显示同一 ID。
2. 逆向工作区修改 ID 后，返回项目库 3D 模型显示同一 ID。
3. 可视化工具栏不再显示 Metadata。
4. 融合视角下方只有一个 DICOM 切片范围滑条，不再暴露起点/终点输入。
5. 位姿控制区域标题显示“模型位姿”。
## 医学影像数据相关边界验证
- 切片范围滑条最小值不小于 1，最大值不超过 DICOM 总切片数。
- API 请求仍使用合理 `start/end`，避免空体数据。
- 构件 ID 限定为 `1~255`，防止与背景 `0` 冲突。
## 回归风险
- 共享 moduleStyles 可能影响已有颜色、透明度、显示隐藏控制。
- 融合体请求频繁变化可能导致加载状态更新较频繁。
## 人工审核状态
用户已声明本次不需要二次人工确认，按默认执行确认规则直接执行。
## 执行结果
- `npm run lint`：通过。
- `npm run build`：通过，仅保留 Vite 大 chunk 体积提醒。
- 重新部署：已通过 `tmux` 重启 `revoxelseg-dicom` 服务，运行在 `http://0.0.0.0:4000/`。
- `curl -I http://127.0.0.1:4000/`：返回 `HTTP/1.1 200 OK`。
- `GET /api/projects/head-ct-demo`：返回默认项目，包含 9 个 STL 构件的 `moduleStyles`。
- `PATCH /api/projects/head-ct-demo/module-styles`：可修改构件 ID 和可见性。
- 构件 ID 边界：提交 `partId=0` 后服务端返回 `partId=1`，符合不可修改为 0 的约束。

58
工程分析/测试方案-2026-05-08-01-19-42.md
View File

@@ -1,58 +0,0 @@
# 测试方案 - 2026-05-08-01-19-42
## 静态检查
- 执行 `npm run lint`，确认 TypeScript 类型检查通过。
- 执行 `npm run build`，确认生产构建通过。
- 执行 `git diff --check`，确认无空白错误。
## 集成验证
- `GET /api/projects/head-ct-demo` 正常返回项目与构件样式。
- `GET /api/projects/head-ct-demo/dicom-fusion-volume?start=0&end=<n>&mode=soft` 正常返回体数据。
- 本地服务重新部署后 `curl -I http://127.0.0.1:4000/` 返回 200。
## 关键业务场景验证
1. 模型库在放大或小高度场景下，右侧构件层级仍可滚动查看。
2. 左侧逆向工作区图标与模型库图标不同。
3. 逆向工作区模型位姿支持：
- 重置旋转位姿。
- 重置平移缩放位姿。
- X/Y/Z ±90° 快捷旋转。
- 非默认位姿重命名。
- 单击最低刻度移动，长按连续移动。
4. DICOM 切片范围提供五个预存点位，并能触发缓存加载。
5. 融合视角中可看到 DICOM 边界框、模型边界框。
6. 模型旋转中心围绕 DICOM 体中心。
7. DICOM 透明度三档切换可见。
8. 模型切分开关、帧选择和切割面显示可用。
## 医学影像数据相关边界验证
- 切片范围点位不超过 DICOM 总帧数。
- 切割帧范围限制在 `1~dicomCount`。
- DICOM 体数据缓存只缓存当前项目和当前模式下的数据，避免混用其他项目数据。
## 回归风险
- Three.js clipping plane 和边界框可能影响渲染性能。
- 预存五点会产生多次融合体请求，需要确认不会阻塞主界面交互。
- 模型旋转中心改为 DICOM 中心后，旧的模型位姿视觉效果会发生变化。
## 人工审核状态
用户已声明本次不需要二次人工确认，按默认执行确认规则直接执行。
## 执行结果
- `npm run lint`：通过。
- `npm run build`：通过，仅保留 Vite 大 chunk 体积提醒。
- `git diff --check`：通过。
- 重新部署：已通过 `tmux` 重启 `revoxelseg-dicom` 服务，运行在 `http://0.0.0.0:4000/`。
- `curl -I http://127.0.0.1:4000/`：返回 `HTTP/1.1 200 OK`。
- `GET /api/projects/head-ct-demo/dicom-fusion-volume?start=0&end=59&mode=soft`：正常返回 DICOM 融合体数据。
- 代码静态检索确认：
- `重置默认位姿` 已移除。
- `Workflow` 已用于逆向工作区侧栏图标。
- `预存五点`、`模型切分`、`dicomOpacity`、`showBounds` 相关控制已写入逆向工作区。

48
工程分析/测试方案-2026-05-08-01-53-07.md
View File

@@ -1,48 +0,0 @@
# 测试方案 - 2026-05-08-01-53-07
## 静态检查
- 执行 `npm run lint`，确认 TypeScript 类型检查通过。
- 执行 `npm run build`，确认生产构建通过。
- 执行 `git diff --check`，确认无空白错误。
## 集成验证
- `GET /api/projects/head-ct-demo/dicom-fusion-volume?start=299&end=299&mode=soft` 正常返回最高切片。
- `GET /api/projects/head-ct-demo/dicom-fusion-volume?start=120&end=180&mode=soft` 正常返回 `start=120/end=180`，并保持完整 physical depth。
- 重新部署后 `curl -I http://127.0.0.1:4000/` 返回 200。
## 关键业务场景验证
1. 逆向工作区初始 DICOM 切片范围显示最高切片。
2. DICOM 切片范围支持 `M-N`，两个端点可分别调整。
3. 改变切片范围后模型不重新居中、不改变原始配准位置。
4. 浏览器放大时可滚动看到 DICOM 切片范围。
5. 项目库加载项目后后台预加载不会阻塞页面。
6. 启用模型切分后，DICOM 帧上可看到切割 Mask 叠加。
## 医学影像数据相关边界验证
- 任意 `dicomCount` 下 `maxSlice=dicomCount-1`，不写死 300。
- 当 `sliceStart > sliceEnd` 时前端仍按 `M-N` 排序请求。
- 当项目没有 DICOM 文件时，预加载和范围控制不报错。
## 回归风险
- 后端 physical depth 改为全序列基准后，旧截图中的 DICOM box 深度可能不同，但空间关系更符合配准。
- 切割 Mask 目前是可视化辅助层，不代表真实分割算法输出。
## 人工审核状态
用户已声明本次不需要二次人工确认，按默认执行确认规则直接执行。
## 执行结果
- `npm run lint`：通过。
- `npm run build`：通过，仅保留 Vite 大 chunk 体积提醒。
- `git diff --check`：通过。
- 重新部署：已通过 `tmux` 重启 `revoxelseg-dicom` 服务，运行在 `http://0.0.0.0:4000/`。
- `curl -I http://127.0.0.1:4000/`：返回 `HTTP/1.1 200 OK`。
- `GET /api/projects/head-ct-demo/dicom-fusion-volume?start=299&end=299&mode=soft`：返回 `start=299/end=299/total=300/frames=1/depth=300`。
- `GET /api/projects/head-ct-demo/dicom-fusion-volume?start=120&end=180&mode=soft`：返回 `start=120/end=180/total=300/frames=61/depth=300`。
- 静态检索确认已移除固定 `displayStart=0`，切片范围使用 `sliceStart/sliceEnd` 双端点。

45
工程分析/测试方案-2026-05-08-03-03-52.md
View File

@@ -1,45 +0,0 @@
# 测试方案：DICOM 单范围条修复
时间戳：2026-05-08-03-03-52
## 静态检查
- 执行 `npm run lint`，验证 TypeScript 类型检查通过。
- 执行 `npm run build`，验证 Vite 生产构建通过。
## 关键业务场景验证
- 打开逆向体素化工作区，查看“DICOM 切片范围”只显示一条范围轨道。
- 默认 `300 - 300 / 300` 状态下，拖动起点端点可向左形成 `M - 300 / 300`。
- 拖动终点端点可更新终点，起点和终点允许交叉，显示值仍自动按小到大输出。
- 变化范围后，三维融合视角仍加载对应 DICOM 切片范围。
## 医学影像数据边界验证
- DICOM 总数为 1 时，范围条不除以 0，端点显示 `1 - 1 / 1`。
- DICOM 总数为 300 时，最大端点仍为第 300 张。
## 回归风险
- 本次只改 UI 控件，不改 DICOM 数据读取和 STL 叠加逻辑。
- 需要确认自定义 range 样式不会影响同页面其它原生滑块。
## 验收标准
- 页面不再出现上下两条“起点/终点”蓝色进度条。
- `ReverseWorkspace.tsx` 中不再保留旧的两个 label range 结构。
- 构建和重新部署成功。
## 无法测试的风险
- 当前无法在用户浏览器中直接确认缓存是否清除；部署后若仍看到旧界面，需要强制刷新浏览器缓存。
## 人工审核状态
用户已在项目工作流历史中确认后续直接执行，本次不等待二次人工审核。
## 执行结果
- `npm run lint`：通过。
- `npm run build`：通过；仅出现 Vite chunk 大小提示，不影响运行。
- `rg` 验证：`ReverseWorkspace.tsx` 中旧的 `grid grid-cols-[76px_1fr_64px]` 双 range 结构已移除，构建产物包含新的 `dicom-range-input` 单范围条结构。

47
工程分析/测试方案-2026-05-08-03-13-20.md
View File

@@ -1,47 +0,0 @@
# 测试方案：DICOM 范围驱动模型切分
时间戳：2026-05-08-03-13-20
## 静态检查
- 执行 `npm run lint`。
- 执行 `npm run build`。
## 关键业务场景验证
- 进入逆向工作区，DICOM 切片范围默认显示 `1 - 300 / 300`。
- 模型切分区域只保留“启用”开关，不再显示“帧”进度条。
- 调整 DICOM 切片范围后启用模型切分，模型范围外区域被隐藏，保留起点与终点之间的中间区域。
- 页面不再显示 `CUT MASK` 贴图或文字。
## 医学影像数据边界验证
- 起止范围相同，如 `300 - 300 / 300`，启用切分时模型只保留该切片附近的薄层。
- 起止范围反向拖动时，仍按较小值到较大值裁切。
- 完整范围 `1 - 300 / 300` 下启用切分应基本保留完整模型。
## 回归风险
- 模型材质 clipping plane 可能受场景旋转影响，需要确认切面跟随 DICOM 体一起旋转。
- DICOM 范围请求数量较大时仍受后端最大返回帧数限制，但物理空间基准不应变化。
## 验收标准
- 源码不再包含 `createCutMaskTexture` 和 `CUT MASK`。
- 源码不再包含 `cutSlice` 状态和模型切分“帧”滑块。
- 构建与部署成功。
## 无法测试的风险
- 当前无法在用户浏览器中直接观察 WebGL 裁切结果，需要用户刷新页面后确认视觉效果。
## 人工审核状态
用户已在项目工作流历史中确认后续直接执行，本次不等待二次人工审核。
## 执行结果
- `npm run lint`：通过。
- `npm run build`：通过；仅保留 Vite chunk 大小提示。
- `rg` 验证：源码与最新构建产物不再包含 `cutSlice`、`createCutMaskTexture`、`CUT MASK`、模型切分帧滑块结构。
- `rg` 验证：项目加载时已执行 `setSliceStart(0)` 和 `setSliceEnd(maxIndex)`，初始范围为完整 DICOM 序列。

41
工程分析/测试方案-2026-05-08-03-23-51.md
View File

@@ -1,41 +0,0 @@
# 测试方案：精简导航与切分显示
时间戳：2026-05-08-03-23-51
## 静态检查
- 执行 `npm run lint`。
- 执行 `npm run build`。
## 关键业务场景验证
- 侧边栏不再显示“模型库”。
- 顶部标题不再出现“模型库”分支。
- “项目库”仍能进入项目浏览，并可查看模型相关内容。
- 逆向工作区 DICOM 范围卡片不再显示说明文案和预存五点按钮。
- 启用模型切分后不再出现红色平面，但模型仍按 DICOM 范围裁切。
## 回归风险
- 删除 `MODELS` 枚举可能影响路由分支，需要通过 TypeScript 检查覆盖。
- 删除红色平面只应影响显示，不应影响 clipping plane。
## 验收标准
- `rg` 不再命中 `ViewType.MODELS`、侧边栏 `模型库`、`预存五点`、`lowerCutPlane`、`upperCutPlane`。
- `npm run lint` 和 `npm run build` 均通过。
- 重新部署后访问 `http://192.168.3.11:4000/` 返回 200。
## 无法测试的风险
- 当前无法直接在用户浏览器里观察红色平面是否消失，需要用户刷新页面后确认 WebGL 视觉效果。
## 人工审核状态
用户已在项目工作流历史中确认后续直接执行，本次不等待二次人工审核。
## 执行结果
- `npm run lint`：首次发现删除预存状态后残留 `setPreloadMessage` 调用；清理后通过。
- `npm run build`：通过；仅保留 Vite chunk 大小提示。
- `rg` 验证：源码和最新构建产物不再包含 `ViewType.MODELS`、`模型库`、`预存五点`、`preloadMessage`、`lowerCutPlane`、`upperCutPlane`、`显示范围支持`。

42
工程分析/测试方案-2026-05-08-03-35-22.md
View File

@@ -1,42 +0,0 @@
# 测试方案：右侧 STL 实体切面预览
时间戳：2026-05-08-03-35-22
## 静态检查
- 执行 `npm run lint`。
- 执行 `npm run build`。
## 关键业务场景验证
- 逆向工作区右侧 `Mask 展示` 不再出现旧的二维彩色假 Mask。
- 右侧区域显示 STL 实体模型。
- 启用模型切分并调整 DICOM 范围后，右侧实体预览按同一范围裁切。
- 构件隐藏、颜色、模型位姿调整后，右侧实体预览同步更新。
- 底部“导出进度”栏不再显示。
## 回归风险
- 右侧新增 Three.js 渲染可能增加 GPU/CPU 占用。
- 当前无法自动截图确认 WebGL 视觉结果，需要人工刷新页面观察。
## 验收标准
- 源码不再包含 `导出进度`、旧 `mappings.map` 假 Mask 结构。
- `npm run lint` 和 `npm run build` 均通过。
- 重新部署后 `http://192.168.3.11:4000/` 返回 200。
## 无法测试的风险
- 无法在当前命令行直接确认 STL 切面视觉是否符合用户预期，需要用户浏览器中观察。
## 人工审核状态
用户已在项目工作流历史中确认后续直接执行，本次不等待二次人工审核。
## 执行结果
- `npm run lint`：通过。
- `npm run build`：通过；仅保留 Vite chunk 大小提示。
- `rg` 验证：`ReverseWorkspace.tsx` 不再包含 `mappings`、`exportMessage`、`导出进度`、`Maximize2`、`Inferred Mask`、`Verified` 等旧示意 Mask 和导出进度栏结构。
- `rg` 验证：`ReverseWorkspace.tsx` 已新增 `CutSectionPreview` 并挂载到右侧 `Mask 展示` 区域。

54
工程分析/测试方案-2026-05-19-22-59-07.md
View File

@@ -1,54 +0,0 @@
# 测试方案-2026-05-19-22-59-07
## 测试方案文档路径
`工程分析/测试方案-2026-05-19-22-59-07.md`
## 静态检查
- 在 `WebSite/` 下执行 `npm run lint`，确认 TypeScript 类型检查通过。
## 构建检查
- 在 `WebSite/` 下执行 `npm run build`，确认生产构建成功生成 `dist/`。
## 文档验证
- 确认 `工程分析/` 存在。
- 确认本次需求分析、实现方案、测试方案均按时间戳命名。
- 确认 `工程分析/代码编纂工作流.md` 覆盖用户要求的 0 到 7 步。
- 确认 `工程分析/经验记录.md` 保留旧经验并追加本次四段式记录。
- 确认 `AGENTS.md` 包含后续项目修改必须执行该流程的约束。
## 部署验证
- 检查已有 `tmux` 会话和 `4000` 端口占用。
- 使用 `tmux` 重新启动 `revoxelseg-dicom` 会话。
- 验证：
- `curl http://127.0.0.1:4000/api/health`
- `curl -I http://127.0.0.1:4000/`
## Git/Gitea 备份验证
- 使用 `git status --short` 检查工作区。
- 仅暂存本次相关文件。
- 创建 commit：`2026-05-19-22-59-07 建立代码编纂工作流`。
- 尝试 `git push origin main`。
- 完成后提醒用户文档备份 commit 已完成；若推送失败，说明本地 commit 和失败原因。
## 回归关注点
- 本次不改业务代码，主要回归风险来自重新部署。
- 注意不要把历史 `工程分析/需求分析-*`、`实现方案-*`、`测试方案-*` 的既有删除状态一起提交。
- 注意不要提交 `WebSite/data/`、`WebSite/exports/`、医学影像数据或 STL 模型数据。
## 实际执行结果
- `npm run lint`：通过。
- `npm run build`：通过；Vite 提示存在大 chunk 警告，但构建成功。
- `tmux` 部署：已创建会话 `revoxelseg-dicom`。
- 监听端口：`0.0.0.0:4000`，HMR 端口 `24679`。
- 健康检查：`curl http://127.0.0.1:4000/api/health` 返回 `ok: true`。
- 首页验证：`curl -I http://127.0.0.1:4000/` 返回 `HTTP/1.1 200 OK`。
- Git 本地备份 commit：已创建本次工作流文档备份 commit，提交信息为 `2026-05-19-22-59-07 建立代码编纂工作流`。
- Gitea 远端推送：执行 `git push origin main` 时失败，原因是 HTTP 远端 `http://192.168.31.5:5002` 无法读取用户名；未在命令行拼接或保存凭据。

63
工程分析/测试方案-2026-05-19-23-47-31.md
View File

@@ -1,63 +0,0 @@
# 测试方案-2026-05-19-23-47-31
## 测试方案文档路径
`工程分析/测试方案-2026-05-19-23-47-31.md`
## 静态检查
- 在 `WebSite/` 下执行 `npm run lint`。
## 构建检查
- 在 `WebSite/` 下执行 `npm run build`。
## 关键业务场景验证
- 打开逆向工作区，确认右侧标题为“逆向分割映射视图”。
- 确认右侧视图显示 DICOM Base Layer，而不是纯 STL 三维实体切面。
- 确认 Overlay Layer 会显示与 STL 构件对应的彩色 Label Map。
- 在中间“构件层级”面板修改构件颜色，右侧 Overlay 即时变色。
- 修改构件透明度，右侧 Overlay 透明度即时变化。
- 隐藏某个构件，右侧 Overlay 中对应构件消失。
- 调整构件 `ID` 后，右侧图例中的 Label ID 与构件层级保持一致。
- 拖动右侧 Slice Navigator，DICOM 切片和 Overlay 逐层切换。
- 确认右侧 Slice Navigator 不改变左侧 DICOM 切片范围。
## 医学影像数据相关边界验证
- DICOM 切片总数为 0 或项目加载中时，右侧应显示加载/空状态。
- STL preview 加载失败时，DICOM Base Layer 仍可显示。
- 切片序号必须 clamp 到 `1 ~ dicomCount`。
- Canvas Base Layer 与 Overlay Layer 必须尺寸一致。
## 部署验证
- 重新部署后验证：
- `curl http://127.0.0.1:4000/api/health`
- `curl -I http://127.0.0.1:4000/`
## Git/Gitea 备份验证
- 显式暂存本次相关代码和文档，避免提交历史删除状态。
- 创建包含时间戳和描述的 commit。
- 尝试推送到 `origin/main`；若仍因 Gitea HTTP 凭据失败，则记录本地 commit 已完成、远端推送未完成。
## 回归关注点
- 右侧视图改为 2D Canvas 后，不能影响左侧 `FusionThreeView`。
- 构件层级状态仍通过 `api.updateProjectModuleStyles` 持久化。
- 不引入新的后端依赖。
## 实际执行结果
- `npm run lint`：通过。
- `npm run build`：通过；Vite 仍提示大 chunk 警告，但构建成功。
- DICOM preview 接口验证：`/api/projects/head-ct-demo/dicom-preview?slice=0&plane=axial&mode=soft` 返回 `200`。
- STL preview 接口验证：`/api/projects/head-ct-demo/models/%E5%A4%B4%E9%83%A8.stl/preview?limit=72000` 返回 `200`。
- 健康检查：`/api/health` 返回 `ok: true`。
- 重新部署：已重启 `tmux` 会话 `revoxelseg-dicom`，服务日志显示 `ReVoxelSeg DICOM server ready at http://0.0.0.0:4000/`。
- 部署后健康检查：`curl http://127.0.0.1:4000/api/health` 返回 `ok: true`。
- 部署后首页验证：`curl -I http://127.0.0.1:4000/` 返回 `HTTP/1.1 200 OK`。
- Git 本地备份 commit：已创建本次修改备份 commit，提交信息为 `2026-05-19-23-47-31 优化逆向分割映射视图`。
- Gitea 远端推送：执行 `git push origin main` 仍失败，原因是 HTTP 远端 `http://192.168.31.5:5002` 无法读取用户名；未在命令行拼接或保存凭据。

59
工程分析/测试方案-2026-05-20-00-19-47.md
View File

@@ -1,59 +0,0 @@
# 测试方案-2026-05-20-00-19-47
## 测试方案文档路径
`工程分析/测试方案-2026-05-20-00-19-47.md`
## 静态检查
- 在 `WebSite/` 下执行 `npm run lint`。
## 构建检查
- 在 `WebSite/` 下执行 `npm run build`。
## 关键业务场景验证
- 打开逆向工作区，确认右侧仍为“逆向分割映射视图”。
- 拖动中部模型位姿的 X/Y/Z 平移滑条，右侧 Overlay 位置即时变化。
- 拖动 X/Y/Z 旋转滑条，右侧 Overlay 截面形态即时变化。
- 拖动缩放滑条，右侧 Overlay 大小即时变化。
- 右侧 Overlay 应显示连续实心色块，而不是零散表面三角面/点云。
- 调整构件颜色、透明度、显示隐藏后，右侧实心 Mask 即时联动。
- 拖动右侧 Slice Navigator，DICOM Base Layer 与实心 Mask 共同切换。
## 医学影像数据相关边界验证
- STL preview 不可用时，Base Layer 仍显示 DICOM。
- 构件交线无法闭合时，不应导致页面报错。
- 切片序号需要 clamp 到合法范围。
- 位姿拖动时不应重新请求 STL preview，只应重绘 Overlay。
## 部署验证
- 重启 `tmux` 会话 `revoxelseg-dicom`。
- 验证：
- `curl http://127.0.0.1:4000/api/health`
- `curl -I http://127.0.0.1:4000/`
## Git/Gitea 备份验证
- 显式暂存本次相关代码和文档。
- 创建包含时间戳和描述的 commit。
- 推送到 Gitea `origin/main`。
## 回归关注点
- 不影响左侧三维融合视图。
- 不影响中部构件层级保存。
- 不影响 `.nii` / `.nii.gz` 导出按钮。
## 实际执行结果
- `npm run lint`：通过。
- `npm run build`：通过；Vite 保留既有 chunk 体积提示，不影响构建产物生成。
- 部署：已重启 `tmux` 会话 `revoxelseg-dicom`，服务日志显示 `ReVoxelSeg DICOM server ready at http://0.0.0.0:4000/`。
- `curl http://127.0.0.1:4000/api/health`：通过，返回 `{"ok":true,"service":"revoxelseg-dicom"}`。
- `curl -I http://127.0.0.1:4000/`：通过，返回 `HTTP/1.1 200 OK`。
- `curl http://127.0.0.1:4000/api/projects/head-ct-demo`：通过，确认示例项目含 300 张 DICOM 与 9 个 STL 构件。
- `curl` 验证 DICOM preview 与 STL preview 接口：通过，右侧 Base/Overlay 所需数据可正常返回。

61
工程分析/测试方案-2026-05-20-00-38-39.md
View File

@@ -1,61 +0,0 @@
# 测试方案-2026-05-20-00-38-39
## 测试方案文档路径
`工程分析/测试方案-2026-05-20-00-38-39.md`
## 静态检查
- 在 `WebSite/` 下执行 `npm run lint`。
## 构建检查
- 在 `WebSite/` 下执行 `npm run build`。
## 关键业务场景验证
- 打开逆向工作区，确认右侧仍为“逆向分割映射视图”。
- 右侧 Base Layer 与 Overlay 使用同一画布尺寸，不出现拉伸错位。
- 拖动右侧 Slice Navigator，Overlay 的 Z 截面按 DICOM 物理深度变化。
- 拖动中部 X/Y/Z 平移、旋转和缩放，右侧 Overlay 与左侧三维模型位姿同步变化。
- 调整构件颜色、透明度、显示隐藏后，右侧实体 Mask 实时联动。
## 医学影像数据相关边界验证
- DICOM spacing 缺失时使用合理默认值，不导致页面报错。
- STL preview 不可用时，DICOM Base Layer 仍显示。
- STL 截面没有形成闭合区域时不应导致页面崩溃。
- 多构件同时显示时，不应因透明 ImageData 覆盖导致已绘制构件消失。
- 内部小孔洞应被补齐为实体 Mask，减少漏隙。
## 部署验证
- 重启 `tmux` 会话 `revoxelseg-dicom`。
- 验证：
- `curl http://127.0.0.1:4000/api/health`
- `curl -I http://127.0.0.1:4000/`
- DICOM preview 接口。
- STL preview 接口。
## Git/Gitea 备份验证
- 显式暂存本次相关代码和文档。
- 创建包含时间戳和描述的 commit。
- 推送到 Gitea `origin/main`。
## 回归关注点
- 不影响左侧三维融合视图本身的加载和交互。
- 不影响 DICOM 切片范围控件。
- 不影响 Mask 导出按钮。
## 实际执行结果
- `npm run lint`：通过。
- `npm run build`：通过；Vite 保留既有 chunk 体积提示，不影响构建产物生成。
- 部署：已重启 `tmux` 会话 `revoxelseg-dicom`，服务日志显示 `ReVoxelSeg DICOM server ready at http://0.0.0.0:4000/`。
- `curl http://127.0.0.1:4000/api/health`：通过，返回 `{"ok":true,"service":"revoxelseg-dicom"}`。
- `curl -I http://127.0.0.1:4000/`：通过，返回 `HTTP/1.1 200 OK`。
- `curl` 验证项目接口：通过，返回示例项目。
- `curl` 验证 DICOM preview：通过，返回 `physicalSize.width=400`、`physicalSize.height=400`。
- `curl` 验证 STL preview `limit=200000`：通过，`气管上段.stl` 返回 `triangleCount=136500`、`sampledTriangles=136500`，说明该构件已使用完整三角网格。

50
工程分析/测试方案-2026-05-20-01-08-38.md
View File

@@ -1,50 +0,0 @@
# 测试方案-2026-05-20-01-08-38
## 测试方案文档路径
`工程分析/测试方案-2026-05-20-01-08-38.md`
## 静态检查
- 在 `WebSite/` 下执行 `npm run lint`。
## 构建检查
- 在 `WebSite/` 下执行 `npm run build`。
## 关键业务场景验证
- 桌面端逆向工作区三栏布局应变为左侧 6 栅格、中部 3 栅格、右侧 3 栅格。
- 中部“可视化工具栏”宽度应明显变宽。
- 左侧“影像与模型融合视角”宽度应相应收窄，但仍可正常渲染。
- 平移 X/Y/Z 的滑条、加减按钮和长按连续移动均应使用 `0.005` 步长。
- 平移数值显示应保留三位小数。
## 回归关注点
- 旋转步长仍为 `1` 度。
- 缩放步长仍为 `0.05`。
- 右侧映射视图宽度与功能不变。
- 不影响 DICOM/STL 数据加载与导出按钮。
## 部署验证
- 重启 `tmux` 会话 `revoxelseg-dicom`。
- 验证：
- `curl http://127.0.0.1:4000/api/health`
- `curl -I http://127.0.0.1:4000/`
## Git/Gitea 备份验证
- 显式暂存本次相关代码和文档。
- 创建包含时间戳和描述的 commit。
- 推送到 Gitea `origin/main`。
## 实际执行结果
- `npm run lint`：通过。
- `npm run build`：通过；Vite 保留既有 chunk 体积提示，不影响构建产物生成。
- 部署：已重启 `tmux` 会话 `revoxelseg-dicom`，服务日志显示 `ReVoxelSeg DICOM server ready at http://0.0.0.0:4000/`。
- `curl http://127.0.0.1:4000/api/health`：通过，返回 `{"ok":true,"service":"revoxelseg-dicom"}`。
- `curl -I http://127.0.0.1:4000/`：通过，返回 `HTTP/1.1 200 OK`。
- 代码检查确认：桌面端布局已改为左侧 `lg:col-span-6`、中部 `lg:col-span-3`、右侧 `lg:col-span-3`；平移 X/Y/Z 的 step 已改为 `0.005`；数值显示已按 step 自动保留小数位。

59
工程分析/测试方案-2026-05-20-01-38-33.md
View File

@@ -1,59 +0,0 @@
# 测试方案-2026-05-20-01-38-33
## 测试方案文档路径
`工程分析/测试方案-2026-05-20-01-38-33.md`
## 静态检查
- 在 `WebSite/` 下执行 `npm run lint`。
## 构建检查
- 在 `WebSite/` 下执行 `npm run build`。
## 关键业务场景验证
- 顶部不再显示“开始自动配准”。
- 顶部显示“导出全部 NII.GZ”，并能展开 DICOM 原始影像、分割影像、位姿数据选项。
- 三维融合视角右下角显示小型 XYZ 坐标轴。
- 保存自定义位姿后重新进入项目，位姿仍存在。
- 重命名自定义位姿后刷新项目，名称仍保留。
## 导出验证
- `curl` 验证 DICOM 原始影像导出接口返回 `.nii.gz`。
- `curl` 验证分割影像导出接口返回 `.nii.gz`。
- `curl` 验证位姿数据导出接口返回 JSON。
- 使用 gzip 文件头或响应大小确认导出不是旧 `64x64x64` 演示 Mask。
- 确认前端下载不再使用 `URL.createObjectURL(blob)`。
## 部署验证
- 重启 `tmux` 会话 `revoxelseg-dicom`。
- 验证：
- `curl http://127.0.0.1:4000/api/health`
- `curl -I http://127.0.0.1:4000/`
## Git/Gitea 备份验证
- 显式暂存本次相关代码和文档。
- 创建包含时间戳和描述的 commit。
- 推送到 Gitea `origin/main`。
## 实测结果
- `npm run lint`：通过。
- `npm run build`：通过；仅保留 Vite chunk size 提醒。
- 临时服务 `127.0.0.1:4100` 导出 DICOM 原始影像：HTTP 200，`.nii.gz` 约 75.76 MB。
- DICOM NIfTI 头验证：`512x512x300`，datatype `4`，bitpix `16`，vox_offset `352`。
- 临时服务导出 STL 分割影像：HTTP 200，`.nii.gz` 约 146 KB。
- STL 分割 NIfTI 头验证：`512x512x300`，datatype `2`，bitpix `8`，非零体素 `1131842`，最大标签 `9`。
- 临时服务导出位姿数据：HTTP 200，JSON 内包含 `project=head-ct-demo`、当前 `activePose` 和 3 个默认/保存位姿。
- 前端下载实现已确认不再使用 `URL.createObjectURL(blob)`，改为后端直链附件下载。
## 回归关注点
- 右侧分割 NII/NII.GZ 导出按钮仍可工作。
- 项目库中的 Mask 下载入口仍可工作。
- DICOM/STL 预览与三维融合视图不受导出改动影响。

53
工程分析/测试方案-2026-05-20-02-02-37.md
View File

@@ -1,53 +0,0 @@
# 测试方案-2026-05-20-02-02-37
## 测试方案文档路径
`工程分析/测试方案-2026-05-20-02-02-37.md`
## 静态检查
- 在 `WebSite/` 下执行 `npm run lint`。
## 构建检查
- 在 `WebSite/` 下执行 `npm run build`。
## 关键业务场景验证
- 模型位姿的旋转 X/Y/Z、平移 X/Y/Z、缩放均出现可编辑数字输入框。
- 输入合法数值后，滑条、三维融合视图和右侧逆向分割映射视图使用同一当前位姿。
- 输入越界数值时被 clamp 到配置范围。
- 导入导出的 `pose-data.json` 后，当前位姿恢复为 `activePose`。
- 导入包含 `modelPoses` 的 JSON 后，保存位姿列表刷新并持久化。
- 导入非法 JSON 或不含位姿字段的 JSON 时显示错误，当前位姿不被破坏。
## 医学影像数据相关边界验证
- 导入位姿后，右侧 Overlay 和分割导出仍读取当前位姿。
- 只调整位姿输入不改变 DICOM spacing、FOV、slice navigator 和构件层级样式。
## 部署验证
- 重启 `tmux` 会话 `revoxelseg-dicom`。
- 验证：
- `curl http://127.0.0.1:4000/api/health`
- `curl -I http://127.0.0.1:4000/`
## Git/Gitea 备份验证
- 显式暂存本次相关代码和文档。
- 创建包含时间戳和描述的 commit。
- 推送到 Gitea `origin/main`。
## 实测结果
- `npm run lint`：通过。
- `npm run build`：通过；仅保留 Vite chunk size 提醒。
- 代码检查确认模型位姿 7 个字段均使用现有 `poseStepConfig` 的 `min/max/step` 作为数字输入约束。
- 代码检查确认导入位姿支持 `activePose`、`modelPoses`、`pose` 和直接 pose 对象四类 JSON 来源。
## 风险与回归关注点
- 不要把运行态导出文件或历史工程文档删除混入提交。
- 导入位姿不能破坏默认/俯视/侧视三组基础位姿。
- 数字输入不能产生 `NaN` 或空字符串写入 `modelPose`。

52
工程分析/测试方案-2026-05-20-02-15-10.md
View File

@@ -1,52 +0,0 @@
# 测试方案-2026-05-20-02-15-10
## 测试方案文档路径
`工程分析/测试方案-2026-05-20-02-15-10.md`
## 静态检查
- 在 `WebSite/` 下执行 `npm run lint`。
## 构建检查
- 在 `WebSite/` 下执行 `npm run build`。
## 关键业务场景验证
- “影像与模型融合视角”右下角 XYZ 标识尺寸比旧版更小。
- 调整模型旋转 X/Y/Z 后，右下角 XYZ 方向随模型世界方向变化。
- 拖拽旋转三维融合视角后，右下角 XYZ 方向随场景旋转变化。
- 右下角标识不阻挡画布拖拽、滚轮缩放、右键/Shift 平移。
## 医学影像数据相关边界验证
- 该改动不改变 DICOM 体数据、STL 模型加载、FOV、右侧映射视图和 NIfTI 导出逻辑。
- 模型位姿状态仍是右侧映射和分割导出的权威输入。
## 部署验证
- 重启 `tmux` 会话 `revoxelseg-dicom`。
- 验证：
- `curl http://127.0.0.1:4000/api/health`
- `curl -I http://127.0.0.1:4000/`
## Git/Gitea 备份验证
- 显式暂存本次相关代码和文档。
- 创建包含时间戳和描述的 commit。
- 推送到 Gitea `origin/main`。
## 实测结果
- `npm run lint`：通过。
- `npm run build`：通过；仅保留 Vite chunk size 提醒。
- 代码检查确认右下角方向标识尺寸从 72px 缩小为 54px。
- 代码检查确认方向标识由 `modelPoseGroup.getWorldPosition()` 和 `getWorldQuaternion()` 投影生成，会包含模型位姿和 `fusionRoot` 场景旋转。
- 代码检查确认方向投影使用签名去重，避免每帧无条件触发 React 状态更新。
## 风险与回归关注点
- 避免每帧无条件触发 React 状态更新。
- 避免提交历史工程文档删除状态。
- 保持右下角标识在 DICOM 未加载时也有默认可见状态。

62
工程分析/测试方案-2026-05-20-02-32-47.md
View File

@@ -1,62 +0,0 @@
# 测试方案-2026-05-20-02-32-47
## 测试方案文档路径
`工程分析/测试方案-2026-05-20-02-32-47.md`
## 静态检查
- 在 `WebSite/` 下执行 `npm run lint`。
## 构建检查
- 在 `WebSite/` 下执行 `npm run build`。
## 关键业务场景验证
- 顶部“导出全部 NII.GZ”选择多个内容后只触发一个压缩包下载。
- 选中分割影像时，菜单显示“导出可见类别/导出所有类别”选项。
- bundle 中包含所选 DICOM NIfTI、分割 NIfTI、位姿 JSON。
- 若包含分割影像，bundle 中同时包含 `segmentation-labels.json`。
- 类别 JSON 中 label/partId/name/fileName/color/opacity/visible 与项目构件层级一致。
## 医学影像数据相关边界验证
- DICOM NIfTI 仍为真实 DICOM 体数据同维同距。
- 分割 NIfTI 仍使用当前模型位姿。
- visible scope 下隐藏构件不进入分割图和类别 JSON。
- all scope 下隐藏构件仍进入分割图和类别 JSON。
## 部署验证
- 重启 `tmux` 会话 `revoxelseg-dicom`。
- 验证：
- `curl http://127.0.0.1:4000/api/health`
- `curl -I http://127.0.0.1:4000/`
## Git/Gitea 备份验证
- 显式暂存本次相关代码和文档。
- 创建包含时间戳和描述的 commit。
- 推送到 Gitea `origin/main`。
## 实测结果
- `npm run lint`：通过。
- `npm run build`：通过；仅保留 Vite chunk size 提醒。
- 临时服务 `127.0.0.1:4100` 验证 `targets=segmentation,pose&segmentationScope=visible`：HTTP 200，返回 `.tar.gz`。
- visible bundle 包内包含：
- `head-ct-demo-segmentation-label.nii.gz`
- `head-ct-demo-segmentation-labels.json`
- `head-ct-demo-pose-data.json`
- `segmentation-labels.json` 验证包含 `segmentationScope=visible`、`label/partId/name/categoryName/className/fileName/color/opacity/visible` 字段。
- 临时服务验证 `targets=dicom,segmentation,pose&segmentationScope=all`：HTTP 200，返回约 75.90 MB `.tar.gz`。
- all bundle 包内包含 DICOM NIfTI、分割 NIfTI、分割 labels JSON、位姿 JSON。
- all labels JSON 验证包含隐藏构件，隐藏项 `visible=false` 仍保留。
- bundle 内分割 NIfTI 头验证：`512x512x300`，datatype `2`，bitpix `8`，最大标签 `9`。
## 风险与回归关注点
- 避免重新引入 `URL.createObjectURL(blob)` 下载。
- 避免提交历史工程文档删除状态。
- 大体数据打包接口要捕获异常并返回明确错误。

65
工程分析/测试方案-2026-05-20-02-55-11.md
View File

@@ -1,65 +0,0 @@
# 测试方案：头部 STL 实体导出验证
测试方案文档路径：`工程分析/测试方案-2026-05-20-02-55-11.md`
## 静态检查
- 运行 `npm run lint`，确认 TypeScript 类型检查通过。
- 运行 `git diff --check`，确认无空白错误。
结果：已通过。
## 构建检查
- 在 `WebSite/` 执行 `npm run build`，确认生产构建通过。
结果：已通过。Vite 仍提示单个 bundle 超过 500 kB，此为既有体积提示，不影响本次导出修复。
## 关键业务场景验证
- 启动临时服务或复用部署服务。
- 请求分割导出包：
- `targets=segmentation,pose`
- `format=nii.gz`
- `segmentationScope=visible`
- 解包并检查包含：
- `*-segmentation-label.nii.gz`
- `*-segmentation-labels.json`
- `*-pose-data.json`
结果：已通过。临时服务 `127.0.0.1:4100` 下：
- `segmentationScope=visible`：HTTP 200，约 431802 bytes，用时约 6.56 s。
- `segmentationScope=all`：HTTP 200，约 667690 bytes，用时约 8.51 s。
- 压缩包内包含分割 NIfTI、labels JSON 与 pose JSON。
## 医学影像数据相关边界验证
- 读取导出的 NIfTI header，确认维度仍为 DICOM 同维度。
- 统计 label 体素分布，重点检查 `头部` 对应 label 的体素数量和 slice 分布不再表现为极少量散点。
- 检查导出包内 labels JSON 中 `头部.stl` 的 label 对应关系。
结果：已通过。
- NIfTI 维度：`512 x 512 x 300`，`vox_offset=352`。
- `visible` 范围下 `头部.stl` 对应 label 7，体素数 `11742597`，覆盖 slice `13-287`，共 `275` 层，最大单层 `83903` 体素。
- `all` 范围下 label 7 体素数 `9845171`，label 8 `头颅.stl` 体素数 `1930290`，二者均覆盖 `275` 层。
- labels JSON 中 `头部.stl` 的 label/partId 为 `7`。
## 部署验证
- 重新部署后验证：
- `http://127.0.0.1:4000/api/health`
- `http://127.0.0.1:4000/`
- 对部署后的导出包端点再做一次小样本验证。
## Git/Gitea 备份验证
- 提交信息包含 `2026-05-20-02-55-11` 和本次修复摘要。
- 推送到 Gitea 成功。
## 风险与回归关注点
- 完整 STL 导出比预览抽样更耗时，需要观察请求耗时。
- 多构件重叠时仍按现有顺序写入 label，后写构件会覆盖先写构件。
- 旧的未暂存历史删除状态不应混入提交。

79
工程分析/测试方案-2026-05-20-03-19-25.md
View File

@@ -1,79 +0,0 @@
# 测试方案：导出 STL、保存分割结果与项目库复核
测试方案文档路径：`工程分析/测试方案-2026-05-20-03-19-25.md`
## 静态检查
- 运行 `npm run lint`，确认 TypeScript 类型检查通过。
- 运行 `git diff --check`，确认无空白错误。
结果：已通过。
## 构建检查
- 在 `WebSite/` 执行 `npm run build`，确认生产构建通过。
结果：已通过。Vite 仍有单 bundle 超过 500 kB 的既有提示，不影响本次功能。
## 关键业务场景验证
- 调用 `POST /api/projects/head-ct-demo/segmentation-results`，确认返回项目包含保存记录。
- 调用 `/api/projects/head-ct-demo/export-bundle?targets=stl`，确认压缩包内包含原始 STL 文件。
- 调用 `/api/projects/head-ct-demo/export-bundle?targets=segmentation,pose,stl`，确认分割、位姿与 STL 可共包导出。
- 验证项目库 `分割结果` 右侧导出菜单参数与逆向工作区一致。
结果：已通过。
- 临时服务 `127.0.0.1:4100` 下保存接口返回 `segmentationResults`，并可看到默认 `最佳位姿`。
- `targets=stl` 返回 HTTP 200，压缩包约 `116M`，目录包含 9 个原始 STL：会厌、气管上段、气管狭窄段、气管下段、气管整体、声门、头部、头颅、肿瘤。
- `targets=segmentation,pose,stl` 返回 HTTP 200，约 `121433464` bytes，用时约 `7.58s`，包内包含分割 NIfTI、labels JSON、pose JSON 和 STL 原始模型。
## 医学影像数据相关边界验证
- 分割导出仍保持 DICOM 同维度 NIfTI。
- 保存的分割结果导出时使用保存时位姿。
- `visible/all` 分割范围继续影响 Label Map 与 labels JSON。
结果：已覆盖导出包结构验证；分割 NIfTI 生成逻辑未改变，继续复用上一轮完整 STL 网格实体导出链路。
## UI 验证
- 逆向工作区顶部出现 `保存至项目库`。
- 三栏布局中左侧融合视角变窄，中部工具栏和右侧映射视图变宽。
- 右侧图例只显示当前 slice 中有边或填充像素的构件；无构件时显示空状态。
- 项目库分割结果区域显示保存记录和导出入口。
## 文档验证
- `Agent.md` 存在。
- `Agent.md` 包含当前系统使用方式。
- `主要功能` 说明在 500~1300 字范围内。
结果：已通过。`Agent.md` 总字数约 `1105` 字符，主要功能段落在 500~1300 字范围内。
## 部署验证
- 重新部署后验证：
- `http://127.0.0.1:4000/api/health`
- `http://127.0.0.1:4000/`
- 部署后验证导出包接口。
结果：已通过。
- `tmux` 会话 `revoxelseg-dicom` 已重启，服务输出 `ReVoxelSeg DICOM server ready at http://0.0.0.0:4000/`。
- `/api/health` 返回 `{"ok":true,"service":"revoxelseg-dicom"}`。
- 首页 HTTP 200。
- 部署后 `targets=stl` 导出返回 HTTP 200，约 `121372189` bytes，压缩包内包含 9 个 STL 原始模型。
## Git/Gitea 备份验证
- 提交信息包含 `2026-05-20-03-19-25` 和本次修改摘要。
- 推送到 Gitea 成功。
结果：本地 Git commit 已完成；Gitea 推送重试 2 次均失败，错误为 `No route to host`，说明当前环境到 `192.168.31.5:5002` 网络不可达。待网络恢复后执行 `git push origin main` 即可补推。
## 风险与回归关注点
- STL 原始模型打包体积较大，接口验证可先用 `targets=stl` 查看目录，不反复下载全量组合。
- 临时保存接口测试会修改 `WebSite/data/state.json`，该运行态文件不纳入提交。
- 旧的未暂存历史删除状态不应混入提交。

60
工程分析/测试方案-2026-05-20-11-07-27.md
View File

@@ -1,60 +0,0 @@
# 测试方案：取消最佳位姿与软著交付检查
测试方案文档路径：`工程分析/测试方案-2026-05-20-11-07-27.md`
## 静态检查
- 运行 `npm run lint`，确认 TypeScript 类型检查通过。
- 运行 `git diff --check`，确认无空白错误。
## 构建检查
- 在 `WebSite/` 执行 `npm run build`，确认生产构建通过。
## 关键业务场景验证
- 检查 `/api/projects/head-ct-demo` 返回的 `modelPoses` 中不再包含 `best` 或 `最佳位姿` 默认项。
- 检查逆向工作区加载逻辑不再优先选用 `head-ct-demo-pose-data.json` 或 `位姿2`。
- 保留位姿导入功能，确保 JSON 仍可作为用户手动导入素材。
## 软著材料验证
- 确认 `新撰写软著文档/` 存在。
- 确认包含：
- `1. 软著说明书.md`
- `2. 软著登记表.md`
- `3. 代码汇总.md`
- `系统使用视频/`
- `功能验证与素材清单.md`
- 若生成 docx，使用 `unzip -t` 验证 docx 文件结构。
- 确认登记表中不确定的主体/联系人/日期字段写“待确认”。
- 确认软著目录未被 Git 暂存。
## 部署验证
- 重新部署后验证：
- `http://127.0.0.1:4000/api/health`
- `http://127.0.0.1:4000/`
## Git/Gitea 备份验证
- 本次代码和工程分析文档 commit message 包含 `2026-05-20-11-07-27`。
- 尝试推送 Gitea；如仍网络不可达，记录错误。
## 风险与回归关注点
- 软著材料不进入 Gitea，不应被 `git add`。
- 不应删除用户本地 `head-ct-demo-pose-data.json`。
- 不应提交已有历史文档删除状态或其它无关未跟踪文件。
## 实际验证记录
- `npm run lint`：通过，TypeScript 类型检查无错误。
- `git diff --check`：通过，无空白错误。
- `npm run build`：通过，Vite 生产构建完成；仍存在单 chunk 大小提示，不影响本次功能。
- docx 结构校验：`1. 软著说明书.docx`、`2. 软著登记表.docx`、`3. 代码汇总.docx` 均通过 `unzip -t`。
- 重新部署：已重启 `tmux` 会话 `revoxelseg-dicom`，服务监听 `http://0.0.0.0:4000/`。
- 服务健康检查：`http://127.0.0.1:4000/api/health` 返回 `{"ok":true,"service":"revoxelseg-dicom"}`。
- 首页检查：`http://127.0.0.1:4000/` 返回 `HTTP/1.1 200 OK`。
- 项目位姿检查：`/api/projects/head-ct-demo` 返回 `modelPoses` 共 5 条，`ids=["default","top","side","pose-1779215077341","pose-1779215304943"]`，`hasBest=false`。
- 软著目录检查：`新撰写软著文档/` 保持未暂存、未纳入 Git/Gitea。

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

@@ -1,63 +0,0 @@
# 测试方案：软著说明书截图与代码汇总行数检查
测试方案文档路径：`工程分析/测试方案-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。

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

@@ -1,64 +0,0 @@
# 测试方案：默认 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`。
- Git/Gitea：数据入库 commit `9611695 2026-05-20-11-51-05 默认医学数据入库` 已成功推送到 `origin/main`，新增 pack 写入约 190.05 MiB。
- 重新部署：已重启 `tmux` 会话 `revoxelseg-dicom`，服务输出 `ReVoxelSeg DICOM server ready at http://0.0.0.0:4000/`。
- 部署后复验：`/api/health` 正常，首页返回 `HTTP/1.1 200 OK`，默认项目仍返回 `dicomCount=300`、`modelCount=9`、`stlFiles=9`。

67
工程分析/测试方案-2026-05-20-12-09-47.md
View File

@@ -1,67 +0,0 @@
# 测试方案：章节配图与系统使用视频验证
测试方案文档路径：`工程分析/测试方案-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。

62
工程分析/测试方案-2026-05-20-12-29-06.md
View File

@@ -1,62 +0,0 @@
# 测试方案：完整截图与下载内容核查验证
测试方案文档路径：`工程分析/测试方案-2026-05-20-12-29-06.md`
## 静态检查
- 检查说明书 `## X.` 章节数量为 23。
- 检查每个章节均有图片引用。
- 检查 23 张 `chapter-*.png` 文件存在。
- 检查 23 张章节图尺寸为完整视口截图尺寸，不再是局部裁剪图。
- 使用全文搜索列出“下载”“导出”“保存”“NII.GZ”等相关表述。
## 构建检查
- 在 `WebSite/` 执行 `npm run build`。
## 关键业务场景验证
- 完整截图覆盖登录、总体概况、项目库、DICOM 浏览、DICOM 信息、STL 模型、构件层级、分割结果、逆向工作区、位姿导入、映射视图、导出选项、系统管理和退出。
- 逆向工作区截图使用软件 WebGL，避免三维视图空白。
## 医学影像数据相关边界验证
- DICOM 信息截图继续遮盖患者姓名和患者编号。
- 不执行删除项目、重置环境、真实导出下载等破坏性或大量下载操作。
## Word 与素材验证
- 重新生成 `1. 软著说明书.docx`。
- 使用 `unzip -t` 验证 Word 完整性。
- 使用 `unzip -l` 检查 Word 内嵌图片数量为 23。
- 更新 `功能验证与素材清单.md`。
## 部署验证
- 验证 `http://127.0.0.1:4000/api/health`。
- 验证 `http://127.0.0.1:4000/` 返回 200。
## Git/Gitea 备份验证
- commit message 包含 `2026-05-20-12-29-06`。
- 推送 Gitea 成功后记录 commit。
- 确认软著材料未被暂存或提交。
## 风险与回归关注点
- 不把软著图片和 Word 纳入 Gitea。
- 不处理已有历史工程分析文档删除状态。
## 实际验证记录
- 说明书章节检查：`新撰写软著文档/1. 软著说明书.md` 中共有 23 个 `## X.` 章节。
- 图片引用检查：23 个章节均存在图片引用，引用文件全部存在。
- 完整截图尺寸检查：23 张 `chapter-*.png` 均为 1680x1050，未再使用局部裁剪尺寸图片。
- DICOM 信息脱敏检查：`chapter-09-dicom-info.png` 保留完整页面截图，仅遮盖患者姓名和患者编号的值。
- Word 完整性检查：`unzip -t 新撰写软著文档/1. 软著说明书.docx` 通过。
- Word 图片位置检查：`word/document.xml` 中 `<wp:inline>` 数量为 23，说明 Word 正文中仍有 23 个图片位置；`word/media` 为 12 个，原因是 Word 对相同图片二进制做了内部复用。
- 下载/导出内容核查：说明书中存在下载/导出相关内容，主要命中位置包括第 1、2、3、6、8、9、11、12、16、18、19、20、22、23 节，其中直接“下载”表述位于第 8 节 DICOM 影像浏览，主要“导出”表述集中在第 18、19、20、23 节。
- 素材清单检查：`新撰写软著文档/功能验证与素材清单.md` 已更新为“完整视口截图”和 1680x1050 说明。
- 构建检查：`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。

Some files were not shown because too many files have changed in this diff Show More