2026-05-20-02-02-37 支持位姿输入与导入

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

@@ -0,0 +1,59 @@
+# 实现方案-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` 重新部署。

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

@@ -0,0 +1,53 @@
+# 测试方案-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`。

工程分析/经验记录.md

@@ -1045,3 +1045,39 @@ C. 解决问题方案
 D. 后续如何避免问题
 
 凡是用户明确“保存”的可视化参数都应进入项目级持久状态，不能只存在于组件 state。新增保存类交互时同时设计读取、写入、归一化和刷新后的回显验证。
+
+## 2026-05-20-02-02-37 位姿数字输入必须保留可编辑中间态
+
+A. 具体问题
+
+模型位姿从只读数值改为可编辑数值时，如果直接把 `<input type="number">` 完全绑定到 `modelPose`，用户输入负号、小数点或临时清空内容时会被 React 立即回填旧值，导致难以编辑。
+
+B. 产生问题原因
+
+数值输入存在合法提交值和编辑中间态两层语义；`modelPose` 只能存储有限数字，而输入框需要短暂容纳空字符串或尚未完整输入的文本。
+
+C. 解决问题方案
+
+新增 `poseValueDrafts` 保存输入框文本态，并用 `focusedPoseInput` 控制同步范围。输入内容能解析为数字时立即 clamp 后写入 `modelPose`；失焦时统一格式化回与 step 匹配的小数位，非法输入则恢复当前位姿值。
+
+D. 后续如何避免问题
+
+任何需要“可编辑数字 + 实时状态”的控件都应区分 draft value 和 committed value。不要把可能为空或临时非法的输入字符串直接写入业务状态，也不要让格式化逻辑打断用户正在输入的字段。
+
+## 2026-05-20-02-02-37 导入导出的位姿 JSON 要兼容多种入口
+
+A. 具体问题
+
+位姿导出 JSON 包含 `activePose`、`modelPoses` 和项目元信息；用户导入时也可能拿到单个 `{ pose }` 或直接 pose 对象。如果导入逻辑只认一种结构，会让“导出后再导入”的闭环不稳定。
+
+B. 产生问题原因
+
+导出文件是侧车数据，不是纯数组；同时调试和人工编辑时常会只保留一个 pose 对象。导入端如果没有 schema 容错，就会把可恢复数据误判为无效。
+
+C. 解决问题方案
+
+导入解析按优先级读取 `activePose`、`pose`、直接 pose 对象和 `modelPoses[0].pose`，并对每个字段使用 `poseStepConfig` 做 clamp。若包含 `modelPoses`，则补齐默认/俯视/侧视并通过现有 `PATCH /model-poses` 持久化。
+
+D. 后续如何避免问题
+
+成对设计导入/导出功能时，应把导出样例作为导入测试用例，同时兼容最小可用对象。导入端必须对字段缺失、字符串数字、越界数值和重复 id 做归一化处理。

工程分析/需求分析-2026-05-20-02-02-37.md

@@ -0,0 +1,50 @@
+# 需求分析-2026-05-20-02-02-37
+
+## 开始时间
+
+2026-05-20-02-02-37
+
+## 原始需求摘要
+
+用户要求将“可视化工具栏”中的“模型位姿”数值变成可编辑输入，允许直接输入数值调整模型；同时新增“导入位姿数据”选项，并与“导出全部 NII.GZ”中的位姿数据 JSON 格式匹配。
+
+## 业务目标
+
+- 提升模型位姿精调效率，支持滑条、按钮和数值输入三种方式共用同一位姿状态。
+- 支持把已导出的位姿 JSON 再导入当前项目，恢复 activePose、保存位姿列表，并继续驱动三维融合视图、右侧映射视图和分割导出。
+- 保持医疗影像工具栏界面紧凑、可读、可控。
+
+## 输入与输出
+
+- 输入：
+  - 用户在模型位姿数值框中输入旋转、平移、缩放数值。
+  - 用户选择位姿 JSON 文件导入。
+- 输出：
+  - 当前 `modelPose` 实时更新。
+  - 可选保存位姿列表 `modelPoses` 更新并写入后端。
+  - 右侧逆向分割映射视图和 NIfTI 分割导出继续使用当前位姿。
+
+## 影响范围
+
+- `WebSite/src/components/ReverseWorkspace.tsx`
+- `工程分析/经验记录.md`
+- 本次需求、实现、测试文档。
+
+## 关键约束
+
+- 位姿输入需要沿用现有 `poseStepConfig` 的最小值、最大值和精度。
+- 导入格式必须兼容当前导出的 `pose-data.json`，尤其是 `activePose` 与 `modelPoses`。
+- 导入失败需要给出明确错误，不破坏当前位姿。
+- 用户导入保存位姿列表后，要继续通过 `PATCH /model-poses` 持久化。
+
+## 风险点
+
+- 数字输入的中间态可能为空或非法，需要避免把 `NaN` 写入位姿状态。
+- 导入的 JSON 可能包含不完整或越界数值，需要归一化和 clamp。
+- 默认位姿不能丢失；导入外部 `modelPoses` 时应保留或补齐默认/俯视/侧视。
+
+## 默认假设
+
+- 导入位姿数据优先读取导出 JSON 中的 `activePose`；如果没有，则读取第一个可用的 `modelPoses[0].pose` 或对象自身作为单个位姿。
+- 如果导入文件包含 `modelPoses`，则将其作为保存位姿列表导入并持久化。
+- 如果只导入单个位姿，则仅更新当前位姿，不覆盖保存列表。