2026-05-24-15-55-48 增加项目锁定与切片控件修正

工程分析/实现方案-2026-05-24-15-55-48.md

@@ -0,0 +1,62 @@
+# 实现方案-2026-05-24-15-55-48
+
+## 实现方案文档路径
+
+`工程分析/实现方案-2026-05-24-15-55-48.md`
+
+## 修改目标
+
+- 在逆向工作区构件层级标题右侧增加全局显隐按钮。
+- 在项目库项目卡片中增加锁定/解锁能力，并将锁定位姿数据保存到 `项目数据/锁定结果/`。
+- 项目列表支持未锁定筛选，并按最后处理时间倒序排列。
+- 修正 DICOM 切片滚动条的方向与无进度色视觉。
+
+## 涉及路径
+
+- `WebSite/server.ts`
+- `WebSite/src/types.ts`
+- `WebSite/src/lib/api.ts`
+- `WebSite/src/components/ProjectLibrary.tsx`
+- `WebSite/src/components/ReverseWorkspace.tsx`
+- `WebSite/src/index.css`
+- `Docker部署/`
+- `工程分析/经验记录.md`
+
+## 技术路线
+
+- 后端为项目状态增加 `locked`、`lockedAt`、`lastProcessedAt`、`lockedPoseSnapshotPath` 等兼容字段，并提供锁定/解锁 API。
+- 锁定时读取当前项目位姿、构件样式和基础元数据，写入 `项目数据/锁定结果/{projectName或projectId}-{timestamp}.json`。
+- 前端项目库使用新增 API 切换锁定状态；项目卡片在进入逆向工作区前判断锁定状态并提示。
+- 逆向工作区构件层级右侧新增全局眼睛按钮，批量更新所有构件的 `visible` 字段。
+- 切片滑块保持顶部为 1、底部为 N，去掉滚动后轨道进度色。
+
+## 执行步骤
+
+1. 阅读现有项目类型、项目库、逆向工作区和后端项目 API。
+2. 扩展类型与 API 封装。
+3. 实现后端锁定状态归一化、锁定结果落盘和接口。
+4. 实现项目库锁定按钮、未锁定筛选、排序与锁定提示。
+5. 实现逆向工作区全局构件显隐按钮。
+6. 修正切片滚动条方向和 CSS。
+7. 同步 Docker 部署说明。
+8. 运行 lint/build，重新部署并验证。
+9. 提交并推送 Gitea。
+
+## 兼容性与回滚方案
+
+- 旧项目缺少锁定字段时默认 `locked=false`，缺少最后处理时间时回退到 `updatedAt`、`createdAt`。
+- 如锁定结果目录不存在则由后端自动创建。
+- 回滚时可移除新增 API 和前端按钮，已有锁定 JSON 文件不影响系统启动。
+
+## 预计文件变更
+
+- 新增本次三份工程分析文档。
+- 修改前后端项目状态、交互和样式文件。
+- 修改 Docker 部署说明，记录新增锁定结果目录和功能。
+- 追加经验记录。
+
+## 提交与部署策略
+
+- 仅暂存本次相关文档、前后端源码和 Docker 文档。
+- Commit message 包含 `2026-05-24-15-55-48` 与简要描述。
+- 使用 `tmux` 会话 `revoxelseg-dicom` 重新运行 `npm run serve -- --host 0.0.0.0 --port 4000`。

工程分析/测试方案-2026-05-24-15-55-48.md

@@ -0,0 +1,58 @@
+# 测试方案-2026-05-24-15-55-48
+
+## 测试方案文档路径
+
+`工程分析/测试方案-2026-05-24-15-55-48.md`
+
+## 静态检查
+
+- 在 `WebSite/` 执行 `npm run lint`，确认 TypeScript 类型检查通过。
+
+## 构建检查
+
+- 在 `WebSite/` 执行 `npm run build`，确认生产构建成功。
+
+## 关键业务场景验证
+
+- 项目库项目卡片可锁定和解锁。
+- 锁定项目后，“进入逆向工作区”给出需要解锁提示，不进入工作区。
+- 项目库左侧可筛选未锁定项目。
+- 项目列表按最后处理时间倒序显示。
+- 逆向工作区“构件层级”标题右侧全局眼睛可批量隐藏/显示构件。
+- DICOM 切片滚动条顶部对应第 1 张，向下拖动查看到更大序号，轨道无进度色。
+
+## 医学影像数据相关边界验证
+
+- 缺少锁定字段的旧项目仍可显示和进入。
+- 锁定时保存的位姿数据包含模型平移、旋转、缩放、镜像和构件样式快照。
+- DICOM 切片显示编号不回退到旧的倒序错误。
+
+## 部署验证
+
+- 重新构建后通过 `tmux` 会话 `revoxelseg-dicom` 启动服务。
+- 验证 `http://127.0.0.1:4000/api/health`。
+- 验证 `http://127.0.0.1:4000/`。
+- 验证 `https://revoxel.huijutec.cn/` 和 `/api/health`。
+
+## Git/Gitea 备份验证
+
+- 使用 `git status --short` 检查仅包含本次相关变化。
+- Commit message 包含 `2026-05-24-15-55-48`。
+- 推送到 Gitea `origin/main` 后确认本地分支与远程同步。
+
+## 风险与回归关注点
+
+- 锁定结果 JSON 不应把大型 DICOM/STL 原始数据写入 Git 跟踪。
+- 批量构件显隐不应覆盖颜色、透明度、Mask ID 等其他配置。
+- 切片滚动方向调整需同时覆盖项目库和逆向工作区相关控件。
+
+## 执行结果
+
+- `npm run lint`：通过。
+- `npm run build`：通过；仅保留 Vite chunk size 提示。
+- `tmux` 会话 `revoxelseg-dicom` 已重启，运行 `NODE_ENV=production npm run serve -- --host 0.0.0.0 --port 4000`。
+- `http://127.0.0.1:4000/api/health`：HTTP 200。
+- `http://127.0.0.1:4000/`：HTTP 200。
+- `https://revoxel.huijutec.cn/api/health`：HTTP 200。
+- `https://revoxel.huijutec.cn/`：HTTP 200。
+- 临时项目锁定 API 验证通过：锁定生成 `项目数据/锁定结果/*-pose-lock.json`，解锁与删除正常；临时快照文件已清理。

工程分析/经验记录.md

@@ -1693,3 +1693,21 @@ C. 解决问题方案
 D. 后续如何避免问题
 
 后续做 STL 到 Label Map 的切面填充时，不能只按全局行交点两两配对，必须先按轮廓连通性分组。遇到长线桥接，应同时检查源 STL 的边界边/非流形边和体素化配对策略；如果 STL 是真实中心线或开口片面，只能近似显示，不能承诺恢复真实医学实体。每次修改导出算法后，至少用包含中文构件名和复杂肝脏血管的项目执行一次 `separate + all` 导出，并用 `tar -tzf` 验证文件完整。
+
+## 2026-05-24-15-55-48 项目锁定状态与切片滑块方向要分开建模
+
+A. 具体问题
+
+用户要求项目库支持锁定/解锁项目，锁定时保存位姿快照到 `项目数据/锁定结果/`；已锁定项目进入逆向工作区时提示需要解锁；项目列表可筛选未上锁项目并按最后处理时间排序。同时，DICOM 切片位置滑条不应显示进度色，且第 1 张应位于滑条顶部，向下查看到第 N 张。
+
+B. 产生问题原因
+
+项目此前没有锁定字段、最后处理时间和锁定快照 API，项目列表只能按读取顺序展示。切片显示层号已经使用 `total - sliceIndex` 转换为用户可见顺序，但滑块值仍使用旧的反向映射和底部进度填充，导致第 1 张出现在滑条底部，并被误看成进度条。
+
+C. 解决问题方案
+
+为项目状态增加 `locked`、`lockedAt`、`unlockedAt`、`lastProcessedAt`、`lockedPoseSnapshotPath`，新增锁定 API；锁定时写入只包含项目元数据、模型位姿、构件样式和最新分割结果的 JSON 快照，不写入原始 DICOM/STL。项目库增加锁定/解锁按钮、未上锁筛选、锁定提示和最后处理时间排序；逆向工作区自身也拦截已锁定项目。切片滑块改用实际切片索引作为控件值，保留显示层号转换，并删除滑条上的彩色填充层。
+
+D. 后续如何避免问题
+
+凡是新增项目运行态数据，都要同时考虑后端状态归一化、前端类型、API、列表排序、Docker 持久化挂载和 `.gitignore`。锁定类快照属于运行态追溯数据，不应混入源码 commit。DICOM 切片控件要明确区分“数组索引”“用户显示层号”和“滑块位置”，不要用同一个变量同时表达三种语义。

工程分析/需求分析-2026-05-24-15-55-48.md

@@ -0,0 +1,49 @@
+# 需求分析-2026-05-24-15-55-48
+
+## 开始时间
+
+2026-05-24-15-55-48
+
+## 原始需求摘要
+
+1. 逆向工作区“构件层级”标题右侧增加全局小眼睛按钮，可一键显示或隐藏所有构件。
+2. 项目列表中增加项目锁定能力：在“进入逆向工作区”左侧增加“锁定按钮”；锁定时将位姿数据保存到 `项目数据/锁定结果/`；进入逆向工作区时若项目已锁定则提示需要解锁；项目列表左侧支持筛选未上锁项目；项目按最后处理时间排序。
+3. 修正 DICOM 切片位置滚动条：滚动后轨道不要出现进度色；显示顺序保持正确，但 `1` 应位于滚动条最上方，通过下拉从 `1` 到 `N` 查看切片。
+
+## 业务目标
+
+- 让批量构件显示控制更高效，便于快速观察 DICOM 与 STL 的融合效果。
+- 为项目处理状态增加可控的“锁定”机制，避免已确认位姿的项目被误进入/误编辑。
+- 将锁定时的关键位姿数据落盘，便于后续追溯和复核。
+- 让切片滚动控件语义与用户认知一致：顶部为第 1 张，向下逐步增加。
+
+## 输入与输出
+
+- 输入：项目列表操作、构件可见性操作、DICOM 切片滚动条操作。
+- 输出：项目锁定状态、锁定结果 JSON 文件、构件显示状态更新、正确方向的切片预览与无进度色滚动条。
+
+## 影响范围
+
+- 前端：项目库、逆向工作区、DICOM 切片控件、构件层级工具栏。
+- 后端：项目状态结构、锁定/解锁接口、锁定结果落盘、项目排序字段维护。
+- 文档：`Docker部署/` 部署说明与工程分析经验记录。
+
+## 关键约束
+
+- 必须沿用现有 `WebSite/server.ts` 的项目状态持久化方式。
+- 新增字段需要兼容既有 `state.json`，避免旧项目读取失败。
+- 锁定结果必须写入仓库根目录下的 `项目数据/锁定结果/`。
+- 不提交大型医学影像数据、运行态导出文件或无关工作区变化。
+
+## 风险点
+
+- 锁定后禁止进入工作区需要和项目卡片按钮状态、错误提示保持一致。
+- 位姿数据来源可能同时存在于项目级 `modelPose` 和后端当前状态，需要归一化保存。
+- DICOM 视图已经做过切片编号反转，滚动方向调整时不能再次破坏显示编号。
+- 一键隐藏所有构件会影响跨页面共享样式，需要调用既有构件样式 API。
+
+## 默认假设
+
+- “锁定按钮”需要支持再次点击解锁，解锁后允许进入逆向工作区。
+- “最后处理时间”使用项目最近更新时间、最后导出时间或最后锁定时间中的最新值排序。
+- 切片滚动条无需保留蓝色进度轨道，只保留中性轨道与滑块。