1998 lines
134 KiB
Markdown
1998 lines
134 KiB
Markdown
# 经验记录
|
||
|
||
本文件用于记录项目修改过程中的关键问题与解决方案。每条经验使用四段式结构。
|
||
|
||
## 2026-05-04-02-38-48 建立代码编纂工作流
|
||
|
||
A. 具体问题
|
||
|
||
当前项目尚无统一的需求分析、实现方案、测试方案、经验沉淀和备份提交流程，后续修改容易缺少可追溯记录。
|
||
|
||
B. 产生问题原因
|
||
|
||
项目仍处于早期建设阶段，已有前端工程和医学影像数据资产，但尚未建立工程治理文档与固定执行规范。
|
||
|
||
C. 解决问题方案
|
||
|
||
创建 `工程分析/` 目录，新增工程整体分析、代码编纂工作流、本次需求分析、实现方案、测试方案和经验记录文档。后续项目修改必须先写文档，并在实现方案和测试方案阶段等待用户二次人工审核确认。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
每次项目修改前先记录时间戳并阅读 `工程分析/工程整体分析.md` 与 `工程分析/经验记录.md`。修改前写入需求、实现和测试文档，确认后再执行，完成后追加经验记录并提交 Gitea 备份。
|
||
|
||
## 2026-05-04-02-38-48 Gitea 推送后的本地凭据清理
|
||
|
||
A. 具体问题
|
||
|
||
使用带账号信息的一次性推送地址完成 Gitea push 后，本地 `branch.main.remote` 曾记录为带账号信息的 URL。
|
||
|
||
B. 产生问题原因
|
||
|
||
`git push -u <url> main` 会把该 `<url>` 记录为当前分支上游，而不是只使用已配置的 `origin` 名称。
|
||
|
||
C. 解决问题方案
|
||
|
||
将 `origin` 保持为不含账号信息的仓库地址，并把 `branch.main.remote` 改回 `origin`、`branch.main.merge` 改为 `refs/heads/main`。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
后续推送时优先使用已配置好的 `origin`。如果必须临时带认证信息推送，推送后立即检查 `git config --get-regexp 'branch\\.main|remote\\.origin'`，确保本地配置中没有保存账号密码。
|
||
|
||
## 2026-05-04-02-38-48 开发服务端口占用
|
||
|
||
A. 具体问题
|
||
|
||
本项目默认 Vite 端口 `3000` 已被 `/home/wkmgc/Desktop/Seg_Server` 的 node 服务占用，无法直接作为本项目部署端口。
|
||
|
||
B. 产生问题原因
|
||
|
||
同一机器上已有其他项目服务监听 `0.0.0.0:3000`。
|
||
|
||
C. 解决问题方案
|
||
|
||
不停止既有服务，改用 `3001` 端口启动当前项目的 Vite 服务，并通过 `curl -I http://127.0.0.1:3001/` 验证返回 `HTTP/1.1 200 OK`。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
部署前先使用 `ss -ltnp` 检查目标端口。如果默认端口被占用，优先选择相邻可用端口并在测试方案执行结果中记录实际访问地址。
|
||
|
||
## 2026-05-04-02-38-48 后台部署进程托管
|
||
|
||
A. 具体问题
|
||
|
||
使用普通 `nohup` 后台启动 Vite 时进程会静默退出，无法稳定保留服务。
|
||
|
||
B. 产生问题原因
|
||
|
||
当前命令执行环境会回收普通后台子进程，导致 `nohup` 方式没有形成稳定部署。
|
||
|
||
C. 解决问题方案
|
||
|
||
使用 `tmux new-session -d -s revoxelseg-dicom` 托管 Vite 服务，使开发服务脱离当前命令执行会话独立运行。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
需要保留长时间运行的开发服务时，优先使用 `tmux` 会话托管，并用 `tmux capture-pane -pt <session>` 查看启动日志，用 `curl` 验证 HTTP 响应。
|
||
|
||
## 2026-05-04-03-08-20 附件 logo 落盘与静态资源引用
|
||
|
||
A. 具体问题
|
||
|
||
用户要求将 title 图标、登录页 logo 和左上角 logo 都替换为对话中提供的图片，需要把附件图片变为前端可稳定访问的静态资源。
|
||
|
||
B. 产生问题原因
|
||
|
||
前端组件不能直接引用对话附件，必须先将图片保存到项目静态资源目录，再通过固定 URL 引用。
|
||
|
||
C. 解决问题方案
|
||
|
||
确认 `/tmp/logo_check.png` 与用户提供的 logo 一致后，将其复制到 `WebSite/public/logo.png`。`index.html` favicon、登录页和侧边栏统一通过 `/logo.png` 引用。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
后续涉及用户上传图片替换项目资源时，先在本地确认附件是否已落盘；优先放入 `WebSite/public/` 并使用根路径引用，避免组件间重复存放资源。
|
||
|
||
## 2026-05-04-03-08-20 指定端口重新部署
|
||
|
||
A. 具体问题
|
||
|
||
用户要求将项目部署到 `http://192.168.3.11:4000/`，需要从原先 `3001` 端口切换到 `4000`。
|
||
|
||
B. 产生问题原因
|
||
|
||
项目早前使用 `tmux` 会话 `revoxelseg-dicom` 托管在 `3001`，本次需求指定了新的访问端口。
|
||
|
||
C. 解决问题方案
|
||
|
||
先检查 `4000` 端口是否空闲，然后关闭旧 `revoxelseg-dicom` 会话，使用同名 `tmux` 会话启动 Vite：`node ./node_modules/vite/bin/vite.js --host 0.0.0.0 --port 4000 --strictPort`。随后用本机地址和内网地址分别验证 HTTP 200。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
每次调整部署端口前先检查端口占用和现有 `tmux` 会话；部署后同时验证 `127.0.0.1` 与目标内网 IP，并把实际访问地址写入测试方案执行结果。
|
||
|
||
## 2026-05-04-03-21-40 从纯前端演示升级为前后端协调系统
|
||
|
||
A. 具体问题
|
||
|
||
原系统登录、项目列表、用户列表、出厂重置和导出都是前端静态假数据，不同浏览器之间无法共享状态。
|
||
|
||
B. 产生问题原因
|
||
|
||
项目初始形态是 Vite/React 前端演示，没有后端 API、共享状态存储和统一部署入口。
|
||
|
||
C. 解决问题方案
|
||
|
||
新增 Express 后端 `server.ts`，用同一 `4000` 端口服务 API 和前端页面。后端通过 `WebSite/data/state.json` 维护演示状态，前端通过 `/api/session` 轮询同步登录状态，并将项目、用户、概况、重置和导出功能全部接入 API。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
新增跨浏览器共享功能时，默认先判断状态是否必须由后端维护；涉及多浏览器一致性的功能不要放在组件静态数组或浏览器本地状态中。
|
||
|
||
## 2026-05-04-03-21-40 默认医学数据项目载入
|
||
|
||
A. 具体问题
|
||
|
||
项目列表需要默认载入 `Head_CT_DICOM` 和 `Head_CT_ReConstruct`，恢复演示环境出厂设置后也必须恢复这两个默认数据目录。
|
||
|
||
B. 产生问题原因
|
||
|
||
旧项目列表使用硬编码医疗项目示例，和当前仓库中的 DICOM/STL 数据资产没有建立关系。
|
||
|
||
C. 解决问题方案
|
||
|
||
后端启动和读取状态时扫描 `Head_CT_DICOM` 的 `.dcm` 数量与 `Head_CT_ReConstruct` 的 `.stl` 文件列表，生成默认项目 `head-ct-demo`。`POST /api/demo/reset` 使用同一逻辑重建默认项目。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
演示数据入口统一放在后端默认项目构建函数中，避免多个页面分别硬编码 DICOM/STL 路径或数量。
|
||
|
||
## 2026-05-04-03-21-40 NIfTI 导出闭环
|
||
|
||
A. 具体问题
|
||
|
||
逆向工作区需要最终生成 `nii` 或 `nii.gz` 格式的分割 mask，而旧界面只有导出按钮，没有后端文件生成能力。
|
||
|
||
B. 产生问题原因
|
||
|
||
项目尚未实现真实 STL 到 DICOM 空间的体素化算法，也没有文件导出 API。
|
||
|
||
C. 解决问题方案
|
||
|
||
新增 `POST /api/projects/:projectId/export-mask`，后端生成 NIfTI-1 单文件 mask，并按请求输出 `.nii` 或 `.nii.gz`。`.nii.gz` 使用 Node `zlib.gzipSync` 压缩，并通过 `Content-Disposition` 触发下载。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
导出类功能需要先定义后端接口、文件格式和校验命令。后续实现真实体素化时，可替换当前演示 mask 生成函数，但保留 API 和下载流程。
|
||
|
||
## 2026-05-04-03-21-40 Vite 中间件 HMR 端口冲突
|
||
|
||
A. 具体问题
|
||
|
||
Express + Vite 中间件启动时，默认 HMR WebSocket 端口 `24678` 被其他服务占用，日志出现端口冲突。
|
||
|
||
B. 产生问题原因
|
||
|
||
同一机器同时运行多个 Vite 服务，默认 HMR 端口可能重复。
|
||
|
||
C. 解决问题方案
|
||
|
||
在 `createViteServer` 中指定 `server.hmr.port = 24679`，使本项目后端服务使用独立 HMR 端口。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
多项目并行部署时，除了业务端口外，也检查 Vite HMR 端口；发现冲突时为每个项目分配独立 HMR 端口。
|
||
|
||
## 2026-05-04-03-50-07 概况统计语义误导
|
||
|
||
A. 具体问题
|
||
|
||
项目总数只有 1 时，“已处理项目总数”也显示 1，容易让用户误解为系统已经完成真实处理。
|
||
|
||
B. 产生问题原因
|
||
|
||
旧统计把 `status === completed` 直接当作已处理项目，而默认演示项目为了表示数据可用被标记为 `completed`。
|
||
|
||
C. 解决问题方案
|
||
|
||
将概况卡片语义改为“已导出 Mask 项目”，后端按 `exportedMaskCount > 0` 统计；默认项目初始为 0，只有实际触发 mask 导出后才计入。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
统计卡片必须反映明确业务事件，不要把演示数据可用状态和处理完成状态混在一起。
|
||
|
||
## 2026-05-04-03-50-07 DICOM 预览解析
|
||
|
||
A. 具体问题
|
||
|
||
项目库 DICOM 影像页看不到真实影像，只显示占位图形。
|
||
|
||
B. 产生问题原因
|
||
|
||
前端没有读取 DICOM 像素数据，后端也没有提供切片预览 API。
|
||
|
||
C. 解决问题方案
|
||
|
||
新增 `GET /api/projects/:projectId/dicom-preview`，后端解析当前 Little Endian DICOM 的 Rows、Columns、Window、Rescale 和 Pixel Data，返回 base64 灰度像素，前端用 canvas 绘制真实切片。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
医学影像可视化应优先验证真实像素是否进入浏览器。后续扩展更多 DICOM 传输语法时，应把解析器替换为成熟 DICOM 库或 Python 预处理服务。
|
||
|
||
## 2026-05-04-03-50-07 STL 模型真实渲染
|
||
|
||
A. 具体问题
|
||
|
||
项目库 3D 模型页显示的是占位立方体，不是 `Head_CT_ReConstruct` 中的真实 STL。
|
||
|
||
B. 产生问题原因
|
||
|
||
前端没有 STLLoader，后端也没有安全暴露 STL 文件。
|
||
|
||
C. 解决问题方案
|
||
|
||
新增 `GET /api/projects/:projectId/models/:fileName`，仅允许读取项目 STL 列表中的文件；前端使用 Three.js `STLLoader`、`Bounds` 和 `Center` 加载并自动居中显示模型。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
三维模型视图必须加载真实模型文件，不能长期使用占位几何体；后端文件服务要限制文件名和项目白名单，避免任意路径读取。
|
||
|
||
## 2026-05-04-03-50-07 Recharts 容器尺寸警告
|
||
|
||
A. 具体问题
|
||
|
||
控制台出现 Recharts 警告：图表宽高为 `-1`，需要检查容器尺寸。
|
||
|
||
B. 产生问题原因
|
||
|
||
图表在布局尚未稳定时渲染，`ResponsiveContainer` 从父容器拿到异常宽高。
|
||
|
||
C. 解决问题方案
|
||
|
||
为图表外层设置 `min-w-0`、固定高度和 `min-h`，并在 chartData 存在后再渲染 `ResponsiveContainer`，高度使用明确数值 `300`。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
使用 Recharts 时保证父容器有稳定尺寸；在异步数据未到达前不要提前渲染响应式图表。
|
||
|
||
## 2026-05-04-03-50-07 Python 环境引入边界
|
||
|
||
A. 具体问题
|
||
|
||
用户提出如果需要 Python 可新建 conda 环境，但本次需求可以在现有 Node/React/Three.js 技术栈中完成。
|
||
|
||
B. 产生问题原因
|
||
|
||
DICOM/STL/Mask 功能既可以由前端演示链路实现，也可能进入 Python 医学影像算法链路，需要判断当前阶段是否真的需要 Python。
|
||
|
||
C. 解决问题方案
|
||
|
||
本次不创建 conda 环境，避免增加不必要复杂度；README 中说明当前构建方式和后续真实体素化阶段的 conda 环境建议。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
只有当需要真实 DICOM 空间解析、STL 体素填充、NIfTI 精确写入或批处理算法时，再引入 Python/conda，并把环境文件纳入项目文档。
|
||
|
||
## 2026-05-04-04-12-34 DICOM 三方向预览
|
||
|
||
A. 具体问题
|
||
|
||
项目库 DICOM 影像只能看横断面，且右侧切片控制显示为 `NAV` 和 `#0`，不符合医学影像浏览习惯。
|
||
|
||
B. 产生问题原因
|
||
|
||
旧前端只把 DICOM 序列当成单一轴向切片数组浏览，后端 DICOM preview API 只返回单张横断面。
|
||
|
||
C. 解决问题方案
|
||
|
||
后端 DICOM preview API 增加 `plane=axial|sagittal|coronal` 参数。横断面读取单张 DICOM，矢状面和冠状面从 DICOM 序列逐张采样重建灰度平面。前端增加方向切换，并把右侧控制改为 `第 n / 总数` 的切片语义。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
医学影像浏览控件应按方向、当前切片和总切片数表达，不使用模糊的导航标签；多方向重建后续可加入缓存或 Python 预处理优化性能。
|
||
|
||
## 2026-05-04-04-12-34 STL 多模型样式控制
|
||
|
||
A. 具体问题
|
||
|
||
3D 模型视图只显示单个 STL，右侧状态点无实际意义，用户需要不同 STL 有独立颜色和透明度，并由整体眼睛统一控制显示。
|
||
|
||
B. 产生问题原因
|
||
|
||
旧实现把 STL 列表当成选择器，只加载当前选中的一个模型；侧栏状态点只是装饰，没有绑定模型材质。
|
||
|
||
C. 解决问题方案
|
||
|
||
前端为每个 STL 建立 `visible`、`color`、`opacity` 状态，同时加载所有可见 STL；每个模型材质绑定对应颜色和透明度，右侧整体眼睛统一切换所有 STL 可见性，删除无意义状态点。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
三维列表中的视觉控件必须和真实渲染状态绑定；颜色、透明度、可见性等控件不应只是静态装饰。
|
||
|
||
## 2026-05-04-04-12-34 项目管理交互
|
||
|
||
A. 具体问题
|
||
|
||
创建项目输入框常驻在项目列表中占空间；项目编辑需要手动保存按钮；项目缺少删除入口和二次确认。
|
||
|
||
B. 产生问题原因
|
||
|
||
项目管理功能初版偏向快速可用，没有区分高频浏览和低频管理操作。
|
||
|
||
C. 解决问题方案
|
||
|
||
创建项目改为点击 `+` 后弹窗输入；项目名编辑改为失焦或回车自动保存；项目右侧增加删除按钮，点击后必须在确认弹窗中再次确认。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
列表页面应减少常驻表单噪声；破坏性操作必须二次确认；轻量编辑可采用失焦保存，但需要避免空名称提交。
|
||
|
||
## 2026-05-04-04-58-36 项目列表按钮布局
|
||
|
||
A. 具体问题
|
||
|
||
项目列表标题旁的 `+` 创建按钮和侧栏收缩按钮靠得太近，视觉上发生重叠。
|
||
|
||
B. 产生问题原因
|
||
|
||
两个操作都放在项目列表标题区右侧，且侧栏宽度固定，未给低频收缩操作独立位置。
|
||
|
||
C. 解决问题方案
|
||
|
||
保留 `+` 在标题区，收缩按钮移动到项目列表侧栏中线外侧，并调整容器为 `overflow-visible`，避免按钮被卡片裁剪。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
同一区域的高频操作和布局控制应分区放置；绝对定位按钮如果超出容器，要同步检查父容器裁剪策略。
|
||
|
||
## 2026-05-04-04-58-36 DICOM 三方向缓存与显示模式
|
||
|
||
A. 具体问题
|
||
|
||
矢状面和冠状面切换后图像变化慢或不明显，且 DICOM 只能用单一窗宽窗位显示。
|
||
|
||
B. 产生问题原因
|
||
|
||
每次重建非横断面都要重新读取 DICOM 序列，前后端没有把显示模式作为预览参数，也没有复用已解析的体数据。
|
||
|
||
C. 解决问题方案
|
||
|
||
后端按显示模式缓存 DICOM 体数据和预览结果，API 增加 `mode=default|bone|soft|contrast`；前端切换方向时重置到对应方向中间层，并提供显示模式分段按钮。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
DICOM 多平面重建应优先设计缓存键和窗宽窗位参数；后续接入真实医学影像库时继续保留 plane、slice、mode 的稳定 API 契约。
|
||
|
||
## 2026-05-04-04-58-36 STL 大文件预览
|
||
|
||
A. 具体问题
|
||
|
||
3D 模型页容易空白，直接加载 9 个原始 STL 总量约 240MB，浏览器解析慢且缺少可靠进度反馈。
|
||
|
||
B. 产生问题原因
|
||
|
||
前端承担了原始 STL 解析和渲染的全部工作，大体积二进制模型会阻塞交互并放大 WebGL 环境差异。
|
||
|
||
C. 解决问题方案
|
||
|
||
后端新增 STL 二进制采样预览 API，只返回抽样三角面顶点；前端用原生 Three.js 按采样顶点生成 BufferGeometry，并显示加载进度。WebGL 不可用时改用二维 canvas 投影预览兜底。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
大模型浏览应区分“预览网格”和“原始精度文件”；列表/项目库优先加载轻量预览，进入精修或导出阶段再读取完整 STL。
|
||
|
||
## 2026-05-04-04-58-36 逆向工作区项目上下文与融合视图
|
||
|
||
A. 具体问题
|
||
|
||
逆向工作区没有明确显示当前项目，融合视图没有展示 DICOM 与 STL 归一化中心对齐的效果。
|
||
|
||
B. 产生问题原因
|
||
|
||
工作区初版更多是流程面板，缺少从项目库传入项目后继续呈现项目上下文和影像/模型叠加结果的状态。
|
||
|
||
C. 解决问题方案
|
||
|
||
工作区进入后读取当前项目详情，顶部显示项目名、DICOM 数量、STL 数量和路径；融合视图加载 DICOM 软组织窗切片，并叠加中心对齐的模型轮廓、十字参考线和切片滑块。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
跨页面工作流必须在目标页面重新显示当前操作对象；医学影像配准类视图至少应具备影像层、模型层、对齐标识和当前切片控制。
|
||
|
||
## 2026-05-04-05-20-16 DICOM 三平面预览与下载
|
||
|
||
A. 具体问题
|
||
|
||
DICOM 切片长按不能连续移动，三平面不能旋转，矢状面/冠状面存在大量黑边导致主体像只显示一半，同时缺少当前 PNG 和整套 DICOM 压缩包下载。
|
||
|
||
B. 产生问题原因
|
||
|
||
前端切片控制只有原生 range 输入，缺少连续步进逻辑；canvas 绘制没有旋转参数；后端重建平面直接输出完整矩阵，没有对非黑内容边界做裁切；下载链路只覆盖了分割 Mask。
|
||
|
||
C. 解决问题方案
|
||
|
||
前端新增上下箭头长按定时步进、左/右 90 度旋转和与显示一致的 PNG 导出；后端 DICOM 文件按自然文件名排序，对重建平面做内容裁切并做轻量边缘增强；新增 `dicom-archive` 接口生成 `tar.gz` 压缩包。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
医学影像预览的显示状态应统一由平面、切片、窗宽窗位、旋转角度组成；下载当前视图时复用同一套 canvas 绘制逻辑，避免屏幕显示和导出结果不一致。
|
||
|
||
## 2026-05-04-05-20-16 3D 模型加载完成但画布空白
|
||
|
||
A. 具体问题
|
||
|
||
项目库 3D 模型页提示加载完成，但用户界面仍可能看不到模型。
|
||
|
||
B. 产生问题原因
|
||
|
||
STL 抽样顶点仍保留原始模型坐标，先给 group 位置减中心再缩放时，模型可能被缩放后的坐标体系推离相机视野；WebGL 不可用时二维兜底 canvas 尺寸也依赖容器测量，可能拿到过小尺寸。
|
||
|
||
C. 解决问题方案
|
||
|
||
模型加载完成后先计算整体包围盒，将中心偏移直接平移到每个 mesh 的 geometry 顶点，再统一缩放 group 和设置相机；二维兜底 canvas 在容器尺寸不可用时使用父容器尺寸或默认尺寸，保证兜底预览可见。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
三维预览应在模型坐标归一化后再设置相机；验证时要覆盖 WebGL 正常路径和 WebGL 不可用兜底路径，并做 canvas 尺寸和非背景像素检查。
|
||
|
||
## 2026-05-04-05-20-16 逆向工作区路径信息噪声
|
||
|
||
A. 具体问题
|
||
|
||
逆向工作区标题中显示 `Head_CT_DICOM ↔ Head_CT_ReConstruct`，对用户当前操作帮助不大。
|
||
|
||
B. 产生问题原因
|
||
|
||
早期为了证明项目数据源接入，将数据目录路径直接放进了页面副标题。
|
||
|
||
C. 解决问题方案
|
||
|
||
副标题改为只显示当前项目名称；DICOM 数量和 STL 数量保留在上下文标签中。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
工作区首屏应优先显示“当前正在处理哪个项目”和“下一步操作”，底层路径只在诊断、详情或设置区域出现。
|
||
|
||
## 2026-05-04-05-41-22 STL 实体化程度与位姿控制
|
||
|
||
A. 具体问题
|
||
|
||
3D 模型虽然可以显示，但抽样三角面过少时视觉上偏稀疏，用户希望更接近白色实体 STL 拼装效果，并且能够手动调整整体模型位姿。
|
||
|
||
B. 产生问题原因
|
||
|
||
项目库为了避免大体积 STL 造成浏览器卡顿，使用固定低抽样量预览；同时模型 group 只有自动旋转，没有暴露旋转、平移、缩放等用户控制。
|
||
|
||
C. 解决问题方案
|
||
|
||
新增“预览/标准/精细”实体化程度，后端 STL preview 抽样上限提升到 `36000`；前端新增白色实体模式、自动旋转开关、旋转 X/Y/Z、平移 X/Y/Z、缩放和重置位姿控制，所有位姿变换作用在整体 group 上。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
大模型预览应提供性能档位，而不是在“速度”和“实体感”之间固定取舍；位姿控制必须作用于整体模型容器，避免破坏各 STL 构件的相对拼装关系。
|
||
|
||
## 2026-05-04-05-41-22 DICOM 长按切片反馈
|
||
|
||
A. 具体问题
|
||
|
||
长按切片上下箭头时，编号会变化，但用户希望图像也有连续变化的运动感。
|
||
|
||
B. 产生问题原因
|
||
|
||
前端连续修改 `sliceIndex` 后依赖异步 API 返回更新图像，缺少请求乱序保护和切片切换中的视觉反馈。
|
||
|
||
C. 解决问题方案
|
||
|
||
将长按步进间隔缩短到 `95ms`，为 DICOM preview 请求加入递增序号，只允许最新请求更新画面；切片切换时给 canvas 容器增加轻微缩放、亮度和状态提示。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
连续浏览医学影像时，必须同时处理“状态连续变化”“图像异步返回”和“旧请求覆盖新请求”三个问题；前端应保留上一帧并提供明确切换反馈。
|
||
|
||
## 2026-05-04-05-41-22 逆向工作区标题去重
|
||
|
||
A. 具体问题
|
||
|
||
逆向工作区同时出现全局标题和页面内标题，也重复显示“当前项目”。
|
||
|
||
B. 产生问题原因
|
||
|
||
页面局部标题和全局 header 没有统一职责，项目上下文既出现在副标题，也出现在标签行。
|
||
|
||
C. 解决问题方案
|
||
|
||
保留全局 header 的“逆向工作区”，删除页面内重复标题和副标题；保留并放大当前项目、DICOM 数量、STL 数量标签。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
页面级标题应由全局导航或内容区二选一承担；当前对象信息只保留在最醒目的单一位置，减少重复文本造成的噪声。
|
||
|
||
## 2026-05-04-05-56-34 DICOM 多平面物理比例
|
||
|
||
A. 具体问题
|
||
|
||
矢状面和冠状面只按像素矩阵重建，没有考虑切片间距与单张图像内像素间距，导致图像观感过扁。
|
||
|
||
B. 产生问题原因
|
||
|
||
后端重建平面时直接使用 `切片数 x 行/列数` 作为输出尺寸，默认把切片方向和像素方向当成等距网格。
|
||
|
||
C. 解决问题方案
|
||
|
||
解析 `PixelSpacing`、`SliceThickness`、`SpacingBetweenSlices` 和 `ImagePositionPatient`；优先用相邻 `ImagePositionPatient` 距离估计真实切片间距，并按 `sliceSpacing` 与像素间距做最近邻重采样，返回 spacing 与 physicalSize。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
医学影像任意重建平面都必须带着物理 spacing 计算，不应只看像素数量；当 DICOM tag 缺失时要明确 fallback 来源。
|
||
|
||
## 2026-05-04-05-56-34 DICOM 信息面板
|
||
|
||
A. 具体问题
|
||
|
||
前端缺少 DICOM 详细信息查询，用户无法看到像素间距、切片间距等判断空间比例的关键信息。
|
||
|
||
B. 产生问题原因
|
||
|
||
原有 API 只服务于灰度预览，没有暴露 DICOM 元数据和序列级空间统计。
|
||
|
||
C. 解决问题方案
|
||
|
||
新增 `GET /api/projects/:projectId/dicom-info`，返回患者、检查、序列、图像矩阵、窗宽窗位、spacing、物理尺寸和首尾切片位置；前端增加“信息”按钮和 DICOM 详细信息弹窗。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
影像显示功能旁应提供可审计的元数据入口，特别是任何影响几何比例、配准和导出的空间参数。
|
||
|
||
## 2026-05-04-05-56-34 3D 模型交互控制简化
|
||
|
||
A. 具体问题
|
||
|
||
3D 模型页存在不需要的白色实体模式和自动旋转，同时缺少更高细节档位；鼠标拖拽、滚轮等画布操作不能同步到右侧位姿控件。
|
||
|
||
B. 产生问题原因
|
||
|
||
前一版位姿控制主要依赖右侧滑块，画布本身只负责渲染；显示开关也偏演示型，没有完全贴近用户的实际浏览习惯。
|
||
|
||
C. 解决问题方案
|
||
|
||
移除白色实体和自动旋转；新增“超精细”档，后端 STL 抽样上限提升到 `72000`；画布监听左键旋转、右键或 Shift 平移、滚轮缩放，并回写整体位姿 state。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
三维浏览默认应遵循常见交互习惯，UI 控件与鼠标操作必须共享同一份状态；演示型开关要及时剔除，避免干扰核心工作流。
|
||
|
||
## 2026-05-07-16-20-46 3D 默认位姿
|
||
|
||
A. 具体问题
|
||
|
||
网页端 3D 模型默认位姿看起来不像用户参考图中的正常位姿，打开后更像斜向观察。
|
||
|
||
B. 产生问题原因
|
||
|
||
默认 Three.js 相机使用 `(4.5, 3.5, 5)` 斜向等距视角，而用户期望的是接近俯视/轴向的标准视角。
|
||
|
||
C. 解决问题方案
|
||
|
||
将默认相机改为俯视方向：`camera.up=(0,1,0)`、`camera.position=(0,0,6)`、`lookAt(0,0,0)`；保留默认位姿滑块为旋转 0、平移 0、缩放 1，重置位姿也回到同一基准。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
默认位姿应该由相机预设和模型位姿共同定义；如果用户提供标准视图截图，应优先匹配相机视角，再决定是否需要固定模型 Z 轴校正。
|
||
|
||
## 2026-05-07-16-35-52 3D 位姿重置与旋转中心
|
||
|
||
A. 具体问题
|
||
|
||
整体位姿只有一个重置按钮，无法分别恢复旋转和平移缩放；同时用户感觉模型旋转中心不在模型正中间，缺少右下角 XYZ 方位参考。
|
||
|
||
B. 产生问题原因
|
||
|
||
前端位姿状态虽包含旋转、平移和缩放，但重置操作仍使用单一 `defaultModelPose`；Three.js 预览也使用单 group 同时承载旋转、平移和缩放，层级职责不够清晰；画布缺少固定的方位提示。
|
||
|
||
C. 解决问题方案
|
||
|
||
抽出统一的位姿 clamp 方法；新增 `重置旋转位姿` 与 `重置平移缩放位姿`；旋转项增加 ±90° 快捷按钮，平移和缩放增加正负方向快捷步进；Three.js 渲染拆为 `poseGroup` 负责平移、`pivotGroup` 负责围绕整体包围盒中心旋转和缩放；右下角增加 X/Y/Z 方位与旋转角度 overlay。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
三维位姿控制应按旋转、平移、缩放分开管理；模型加载后必须先基于所有 STL 的整体包围盒做中心化，再把旋转和缩放应用到中心 pivot 上；涉及交互状态时，滑块、按钮和鼠标操作必须共享同一份 clamp 逻辑。
|
||
|
||
## 2026-05-07-16-53-23 STL 抽样中心漂移与动态坐标轴
|
||
|
||
A. 具体问题
|
||
|
||
用户旋转模型后切换 `预览/标准/精细/超精细`，模型位置会明显偏移；鼠标拖拽旋转时也感觉旋转中心没有落在模型内部；右下角坐标轴不随旋转位姿变化。
|
||
|
||
B. 产生问题原因
|
||
|
||
前端用当前抽样出来的 STL 顶点计算整体包围盒，不同细节档位的抽样集合不同，导致中心点和缩放基准随档位变化；右下角坐标轴是固定 HTML/CSS 图形，没有基于当前旋转矩阵更新。
|
||
|
||
C. 解决问题方案
|
||
|
||
后端 STL preview 在遍历完整二进制 STL 时同步计算全量 `bounds`，前端加载时使用所有可见 STL 的全量包围盒合成稳定中心和尺寸，再把抽样 geometry 平移到该中心；右下角坐标轴改为 SVG，根据 `rotateX/Y/Z` 生成 Three.js 旋转矩阵并投影 X/Y/Z 三轴。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
任何用于配准、视角稳定、旋转中心的几何参数都必须来自全量模型或稳定元数据，不能来自随性能档位变化的抽样数据；坐标系、状态文字和模型实际位姿应共用同一份 pose 状态。
|
||
|
||
## 2026-05-07-17-05-43 模型显示实体档位
|
||
|
||
A. 具体问题
|
||
|
||
用户不再需要低质量 `预览` 档位，希望在 `模型显示` 中增加更接近 STL 实体面片的 `实体` 档位。
|
||
|
||
B. 产生问题原因
|
||
|
||
原有档位以性能抽样为主，最高 `超精细` 仍受后端 `72000` 三角面上限约束，且材质继续使用用户设置的半透明度，视觉上仍偏点状或半透明预览。
|
||
|
||
C. 解决问题方案
|
||
|
||
前端删除 `预览` 档位，新增 `实体` 档位并设置更高请求上限 `200000`；后端 STL preview clamp 同步提升到 `200000`；实体档位下将材质不透明度下限提高到 `0.94`，在保留构件颜色的同时增强实体感。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
模型显示档位应明确区分“性能抽样”和“实体查看”；若新增高质量档位，需要同步检查前端请求 limit、后端 clamp、材质表现和浏览器性能边界。
|
||
|
||
## 2026-05-07-17-28-34 逆向工作区三维融合视角
|
||
|
||
A. 具体问题
|
||
|
||
逆向工作区原来的 `影像与模型融合视角` 只是二维 DICOM 图片和示意轮廓叠加，不能表现 DICOM 体数据、切片范围、STL 模型同场景融合，也不能让 DICOM 和模型作为整体旋转观察。
|
||
|
||
B. 产生问题原因
|
||
|
||
早期实现更偏演示界面，没有后端接口提供一段 DICOM 体数据纹理；前端也没有 Three.js 融合场景，只是在二维 canvas 上放置静态标注层。
|
||
|
||
C. 解决问题方案
|
||
|
||
新增 `dicom-fusion-volume` 后端接口，按起止切片返回最多 64 张、最大 256 像素边长的轴向 CT 纹理和 spacing/physicalSize；前端逆向工作区新增 Three.js 融合场景，将 DICOM 渲染为黑色长方体和切片纹理，将 STL preview 模型加载到同一场景，并提供切片范围与模型位姿控件。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
融合、配准、体素化相关视图应优先使用三维数据结构，而不是二维示意图；DICOM 体数据接口必须限制切片数量和纹理尺寸，保证浏览器交互稳定；模型相对 DICOM 的调整和整体场景观察要分开管理。
|
||
|
||
## 2026-05-07-18-11-12 构件层级状态与可视化工具栏
|
||
|
||
A. 具体问题
|
||
|
||
项目库构件层级的单个眼睛按钮表现不稳定；构件缺少可编辑的 1 到 255 ID；逆向工作区仍显示 `分割 Mask`，缺少模型显示、位姿保存/选择和构件层级等可视化控制。
|
||
|
||
B. 产生问题原因
|
||
|
||
构件样式状态只记录 visible/color/opacity，部分更新路径会用默认值重建对象，容易丢失扩展字段；逆向工作区三维融合视角初版只加载模型，没有把项目库中的模型显示和构件层级控制模式迁移过来。
|
||
|
||
C. 解决问题方案
|
||
|
||
扩展构件样式状态为 visible/color/opacity/partId，所有更新都保留既有字段；项目库和逆向工作区均使用 1 到 255 的 ID clamp；新增 `模型库` 复用项目库并默认进入模型页；逆向工作区将中间栏改为 `可视化工具栏`，加入模型显示档位、位姿保存/选择和构件层级，并把这些状态传入 Three.js 模型加载逻辑。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
构件层级状态应作为统一结构在不同页面复用；任何新增构件字段都要检查初始化、单项更新、全局更新和默认 fallback 四条路径；逆向工作区的可视化控制应与项目库模型页保持一致，避免用户在两个页面学两套交互。
|
||
|
||
## 2026-05-07-18-42-53 构件 ID 跨页面联动
|
||
|
||
A. 具体问题
|
||
|
||
项目库 3D 模型和逆向工作区可视化工具栏都能修改构件 ID，但两边原先分别维护本地状态，无法保证 ID、显示隐藏、颜色和透明度一致。
|
||
|
||
B. 产生问题原因
|
||
|
||
构件样式属于项目级配置，但旧实现只保存在 React 组件 state 中，页面切换或不同浏览器访问时不会自动共享。
|
||
|
||
C. 解决问题方案
|
||
|
||
在项目数据中新增 `moduleStyles` 字段，并新增 `PATCH /api/projects/:projectId/module-styles` 接口。项目库和逆向工作区都读写同一后端状态，服务端统一补齐默认值并将 `partId` 限制在 `1~255`。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
凡是需要跨页面、跨浏览器一致的配置项，优先放入后端项目状态；前端可以保留本地 state 提升响应速度，但必须通过 API 持久化并从项目数据恢复。
|
||
|
||
## 2026-05-08-01-19-42 融合视角缓存、边界与切割控制
|
||
|
||
A. 具体问题
|
||
|
||
融合视角在切片范围变化时需要反复请求 DICOM 体数据；模型旋转中心带有模型偏移，极端旋转后容易看起来脱离 DICOM；同时缺少 DICOM/模型边界、透明度档位和沿 DICOM 帧切割模型的操作入口。
|
||
|
||
B. 产生问题原因
|
||
|
||
前一版融合视图以单次加载为主，没有前端缓存点位；模型居中后又把模型组整体设置了 Z 偏移，使旋转 pivot 不完全等同于 DICOM 体中心；三维辅助元素只显示了 DICOM 边线，没有完整的模型边界和切割平面。
|
||
|
||
C. 解决问题方案
|
||
|
||
在前端使用 `Map` 按项目、模式和切片终点缓存 `DicomFusionVolume`；DICOM 切片范围增加五个预存点位和一键预存；Three.js 中将模型旋转组保持在 DICOM 原点，把模型自身偏移放入子节点；增加 DICOM 边界、模型边界、DICOM 透明度三档、切割帧滑条和 clipping plane 切割面。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
涉及 DICOM 与 STL 配准的旋转、缩放、切割操作，应优先明确坐标系和 pivot 来源，默认以 DICOM 体中心为基准；高频切片请求应先设计缓存键和预取策略，避免 UI 操作直接触发重复网络与纹理构建。
|
||
|
||
## 2026-05-08-01-53-07 DICOM 范围变化不改变空间基准
|
||
|
||
A. 具体问题
|
||
|
||
DICOM 切片范围变化后，融合视图中的 DICOM 体深度和帧分布会随范围重新计算，导致模型看起来被自动居中或改变了和 DICOM 的原始配准位置；切分开启后也缺少在 DICOM 帧上直观看到 Mask 的反馈。
|
||
|
||
B. 产生问题原因
|
||
|
||
后端 `dicom-fusion-volume` 使用当前 `start/end` 的范围长度计算 `physicalSize.depth`；前端又把当前返回的帧均匀铺满整个 DICOM box，而不是按原始 DICOM index 放回完整序列位置。
|
||
|
||
C. 解决问题方案
|
||
|
||
后端 physical depth 改为完整序列深度；前端 DICOM slice plane 的 Z 位置改用 `volume.indices[index] / (total - 1)` 映射到完整 DICOM box；切片范围改为 `sliceStart/sliceEnd` 双端点，默认最高切片；切割开启时额外渲染切割帧 DICOM texture，并叠加橙色 Mask 轮廓。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
所有配准相关可视化都必须区分“显示范围”和“空间基准”：显示范围可以变化，但 DICOM 物理尺寸、模型缩放基准和坐标原点不能跟着变化；任何切割或 Mask 预览都要明确只是辅助显示，不能修改原始 DICOM/STL 位姿。
|
||
|
||
## 2026-05-08-03-03-52 项目定位错误导致控件未修复
|
||
|
||
A. 具体问题
|
||
|
||
用户要求将“DICOM 切片范围”的起点、终点合并为一个范围条，但页面仍显示两个上下排列的进度条。
|
||
|
||
B. 产生问题原因
|
||
|
||
前一次处理时依据当前工作目录误改了 `Head_CT_Morph`，而用户截图中的真实页面来自 `ReVoxelSeg_DICOM/WebSite/src/components/ReverseWorkspace.tsx`。没有先用截图中的页面文案和 DOM 片段全局定位真实渲染文件，导致改动没有作用到用户看到的程序。
|
||
|
||
C. 解决问题方案
|
||
|
||
在 `/home/wkmgc/Desktop` 范围内搜索 `DICOM 切片范围` 和 `三维融合场景已就绪`，定位到正确项目 `ReVoxelSeg_DICOM`。将 `ReverseWorkspace.tsx` 中两个独立 `range` 替换为单条自绘轨道叠加两个端点的范围控件，并在 `index.css` 中隐藏原生 range 轨道、保留可拖动 thumb。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
收到 UI 截图或 DOM 片段时，先用页面可见文案、class 片段和组件文本在所有相关项目目录中定位真实源码，再修改代码。若当前仓库内找不到截图中的文本，必须立即扩大搜索范围并向用户说明实际项目位置，不能默认当前工作目录就是目标项目。
|
||
|
||
## 2026-05-08-03-13-20 模型切分必须由 DICOM 范围统一驱动
|
||
|
||
A. 具体问题
|
||
|
||
逆向工作区初始 DICOM 范围只落在最后一张；模型切分还有独立“帧”滑块，与 DICOM 切片范围割裂；切分开启后额外生成 `CUT MASK` 伪贴图，容易误导用户以为是真实语义分割结果。
|
||
|
||
B. 产生问题原因
|
||
|
||
前一版把“DICOM 显示范围”和“模型切割帧”设计成两套状态，并为了给切割反馈绘制了演示性质的二维 mask 纹理，没有把切分严格绑定到 DICOM 起点和终点双帧。
|
||
|
||
C. 解决问题方案
|
||
|
||
删除 `cutSlice` 状态和模型切分帧滑块，项目加载时将 `sliceStart` 初始化为 `0`、`sliceEnd` 初始化为最大帧；`FusionThreeView` 改接收 `cutStart/cutEnd`，根据 DICOM 物理深度映射为两张 clipping plane，模型切分启用后只保留两帧之间的中间模型区域；删除 `createCutMaskTexture` 和 `CUT MASK` 贴图调用。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
所有模型切分、分割预览、Mask 展示都必须明确数据来源。没有真实体素化或真实语义分割结果时，不应使用伪造 mask 图像；同一业务动作只保留一套权威控制状态，模型切分应默认由 DICOM 切片范围驱动。
|
||
|
||
## 2026-05-08-03-23-51 重复入口与辅助显示清理
|
||
|
||
A. 具体问题
|
||
|
||
系统同时提供“项目库”和“模型库”两个入口，实际模型库只是复用项目库的模型页，信息架构重复；逆向工作区的 DICOM 范围说明和五点预存按钮已经不必要；模型切分启用后出现红色辅助平面，干扰观察。
|
||
|
||
B. 产生问题原因
|
||
|
||
早期为了快速进入模型页新增了独立 `MODELS` 路由和侧边栏入口；DICOM 范围控件在调试缓存阶段加入了预存点位；模型切分为了强调切割位置渲染了半透明平面，但用户当前更需要干净的真实裁切效果。
|
||
|
||
C. 解决问题方案
|
||
|
||
删除 `ViewType.MODELS`、侧边栏“模型库”和 `App.tsx` 中对应分支，保留“项目库”统一承载 DICOM、模型、Mask 视图；删除 DICOM 范围说明、五点预存状态和按钮，保留 `fusionVolumeCacheRef` 对实际加载范围的缓存；删除切分辅助平面 Mesh，只保留两张 clipping plane 裁切模型。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
新增导航入口前先判断是否是独立业务对象和独立工作流，避免用多个入口指向同一组件状态；辅助视觉元素应在用户确认有价值后保留，医学三维视图中默认少放装饰或调试平面，避免遮挡真实数据。
|
||
|
||
## 2026-05-08-03-35-22 Mask 展示改为真实 STL 切面
|
||
|
||
A. 具体问题
|
||
|
||
逆向工作区右侧 `Mask 展示` 仍然是二维彩色示意图，并且底部存在“导出进度”栏；用户希望看到切割后的 STL 实体切面。
|
||
|
||
B. 产生问题原因
|
||
|
||
旧 `Mask 展示` 是早期演示 UI，没有接入真实 STL 模型，也没有复用 DICOM 范围切割逻辑；导出进度栏展示的是导出状态文本，不是用户当前关注的切面实体结果。
|
||
|
||
C. 解决问题方案
|
||
|
||
新增 `CutSectionPreview` Three.js 组件，复用当前项目 STL preview、构件颜色/隐藏状态、模型位姿和 DICOM 切片范围；启用模型切分时使用两张 clipping plane 保留中间区域，并以实体材质展示裁切后的 STL。删除旧二维 Mask 示意结构和底部“导出进度”栏。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
右侧结果展示区域应优先呈现真实数据或真实处理结果，避免使用占位式示意图长期冒充结果；如果尚未生成真实语义分割 Mask，应明确展示当前可验证的 STL 切面实体，而不是伪造 Mask 形状。
|
||
|
||
## 2026-05-19-22-59-07 工程分析核心文档被删除状态下的恢复
|
||
|
||
A. 具体问题
|
||
|
||
本次开始时工作区中大量 `工程分析/` 历史文档处于删除状态，且本地目录不存在；如果直接创建新的短版 `经验记录.md` 或直接暂存整个目录，可能丢失旧知识库或把无关删除混入本次备份。
|
||
|
||
B. 产生问题原因
|
||
|
||
这些删除状态在本次操作前已经存在，且 `工程分析/经验记录.md` 在 Git 中已有 795 行历史经验。当前需求又要求读取或创建 `工程分析/`，容易把“恢复核心文档”和“提交所有删除”混为一谈。
|
||
|
||
C. 解决问题方案
|
||
|
||
先通过 Git 读取旧 `工程整体分析.md`、`代码编纂工作流.md` 和 `经验记录.md`，确认历史内容；随后只恢复并更新这三个核心文件，新增本次三份时间戳文档和 `AGENTS.md`，暂存时显式列出本次相关路径，避免提交其他历史删除。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
每次发现工作区已有删除或修改时，先区分是否属于本次需求；文档备份 commit 要显式暂存文件路径，不能用 `git add .`。对 `经验记录.md` 这类知识库文件，更新前必须确认旧内容仍被保留。
|
||
|
||
## 2026-05-19-22-59-07 固化后续代码编纂工作流
|
||
|
||
A. 具体问题
|
||
|
||
用户要求后续所有项目修改相关需求都执行固定流程，但仅在对话中说明流程不够稳固，未来进入项目的助手或开发者可能看不到这条约束。
|
||
|
||
B. 产生问题原因
|
||
|
||
工作流要求跨越多次会话和多次修改，单靠当前对话记忆不可靠；项目内原有 `代码编纂工作流.md` 也处于工作区删除状态，需要恢复并更新为当前版本。
|
||
|
||
C. 解决问题方案
|
||
|
||
更新 `工程分析/代码编纂工作流.md`，明确 0 到 7 步、默认不等待二次确认、文档备份提交和重新部署要求；同时新增根目录 `AGENTS.md`，把后续修改必须读取并执行该工作流作为项目入口约束。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
后续任何项目修改前，先读取根目录 `AGENTS.md` 和 `工程分析/代码编纂工作流.md`；若用户提出新流程要求，应同步更新这两个入口文档和经验记录，确保流程约束留在仓库中。
|
||
|
||
## 2026-05-19-22-59-07 Gitea HTTP 远端缺少可用凭据
|
||
|
||
A. 具体问题
|
||
|
||
本次本地文档备份 commit 已完成，但执行 `git push origin main` 时失败，Git 提示无法读取 `http://192.168.31.5:5002` 的用户名。
|
||
|
||
B. 产生问题原因
|
||
|
||
当前 `origin` 使用 HTTP Gitea 地址，执行环境没有交互式用户名输入，也没有可用的凭据助手或已保存认证信息。
|
||
|
||
C. 解决问题方案
|
||
|
||
保留本地 commit，不在命令行临时拼接账号密码，也不把凭据信息写入仓库或远端 URL。将推送失败原因记录到测试方案和经验记录中，等待用户提供安全的凭据方式后再推送。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
需要 Gitea 远端备份前，先确认远端认证方式。优先使用安全的凭据助手、SSH remote 或用户已配置好的 token；不要把账号密码写进 commit、文档、remote URL 或 shell 历史。
|
||
|
||
## 2026-05-19-23-47-31 逆向分割映射视图的数据来源边界
|
||
|
||
A. 具体问题
|
||
|
||
用户要求右侧二维视图展示由三维 STL 模型逆向推导的分割掩码 Label Map，并与构件层级严格对应；但当前后端尚未提供医学级真实体素化 Label Map 文件。
|
||
|
||
B. 产生问题原因
|
||
|
||
现有系统的真实数据能力主要是 DICOM preview、DICOM fusion volume 和 STL preview 三角面抽样，历史版本的右侧区域也已从伪二维 Mask 改为 STL 实体切面。若直接绘制任意彩色区域，会再次变成无来源 Mask。
|
||
|
||
C. 解决问题方案
|
||
|
||
右侧新建 `VoxelizationMappingView`，底层用 DICOM preview 灰度像素作为 Base Layer，上层只根据 STL preview 顶点、当前 Z 切片位置和构件 `moduleStyles` 投影绘制 Overlay Label Map。每个彩色覆盖区域都来自具体 STL 构件，并复用构件颜色、透明度、显示隐藏和 `partId`。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
在真实体素化服务接入前，所有 Label Map 类可视化必须明确使用 STL 几何或后端生成结果作为来源；不要重新引入无数据来源的演示 Mask。后续若增加医学级体素化，应保留当前 Base/Overlay UI，但将 Overlay 数据源替换为后端真实 Label Map。
|
||
|
||
## 2026-05-19-23-47-31 右侧独立切片导航与左侧范围状态分离
|
||
|
||
A. 具体问题
|
||
|
||
右侧二维映射视图需要逐层浏览单张 DICOM 切片，而左侧三维融合视图使用的是 DICOM 切片范围和模型切分区间；如果共用同一状态，拖动右侧滑条会破坏左侧融合范围。
|
||
|
||
B. 产生问题原因
|
||
|
||
旧工作区已经有 `sliceStart/sliceEnd` 双端点状态，用于三维 DICOM 范围和 STL clipping plane。右侧新增 Slice Navigator 是单切片校验动作，语义不同。
|
||
|
||
C. 解决问题方案
|
||
|
||
新增独立 `mappingSlice` 状态传入 `VoxelizationMappingView`，右侧 Slice Navigator 只修改该状态；左侧 `sliceStart/sliceEnd` 继续驱动三维融合范围和模型切分，两套状态互不覆盖。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
新增影像浏览控件前先判断其控制对象是“单切片位置”还是“显示范围/切割范围”。单切片校验使用独立 slice 状态，范围切割使用起止端点状态，避免不同视图之间产生隐式联动。
|
||
|
||
## 2026-05-20-00-19-47 右侧映射视图必须复用中部模型位姿
|
||
|
||
A. 具体问题
|
||
|
||
右侧“逆向分割映射视图”虽然已经使用 DICOM Base Layer 和 STL Overlay，但 Overlay 计算没有接入中部“模型位姿”状态；用户拖动 X/Y/Z 平移或旋转后，左侧三维视图变化，右侧二维映射仍按旧 STL 原始坐标绘制。
|
||
|
||
B. 产生问题原因
|
||
|
||
上一版 `VoxelizationMappingView` 只接收 `moduleStyles`、`slice` 和 STL preview 数据，没有接收 `modelPose`；`drawVoxelOverlayLayer` 直接使用 STL 原始顶点和全局 bounds 计算投影，没有先执行与三维场景一致的归一化、旋转、缩放和平移。
|
||
|
||
C. 解决问题方案
|
||
|
||
为 `VoxelizationMappingView` 增加 `modelPose` 入参，由父组件直接传入中部工具栏的当前位姿；在 Overlay 计算前对 STL 顶点执行 `scale -> rotateX -> rotateY -> rotateZ -> translate`，再与当前 Z 轴 DICOM 切片平面求交，并使用 `requestAnimationFrame` 合并高频滑条更新。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
凡是右侧二维映射、Mask、Label Map 或导出预览依赖 STL 空间位置时，都必须确认其输入状态包含当前权威位姿；不能让三维视图和二维视图各自维护坐标变换。新增视图前先列出共享状态：位姿、构件样式、切片位置和数据源。
|
||
|
||
## 2026-05-20-00-19-47 实体 Mask 填充不能覆盖多构件叠加
|
||
|
||
A. 具体问题
|
||
|
||
将截面交线转为实心 Mask 时，如果每个构件直接在主 Overlay canvas 上 `putImageData`，后一个构件的透明像素会覆盖掉前一个构件，导致多构件同时显示时可能只剩最后绘制的构件。
|
||
|
||
B. 产生问题原因
|
||
|
||
Canvas 的 `putImageData` 是像素替换操作，不是透明合成操作；即使 ImageData 中某些像素 alpha 为 0，也会把目标 canvas 对应位置写成透明，从而擦掉已有 Overlay。
|
||
|
||
C. 解决问题方案
|
||
|
||
每个构件先在离屏 canvas 中生成扫描线射线法填充的实心 Mask，再使用 `drawImage` 以 `source-over` 合成到主 Overlay canvas；边界描边也在合成后按构件颜色与透明度绘制，保留多构件叠加效果。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
多层或多构件 Canvas 叠加时，优先使用离屏画布或单次合并后的 ImageData；只有在明确要替换整张图时才使用主 canvas 的 `putImageData`。涉及透明叠加的渲染改动，必须检查“前一层是否会被透明像素擦除”。
|
||
|
||
## 2026-05-20-00-38-39 多视图 FOV 对齐必须使用同源物理尺度
|
||
|
||
A. 具体问题
|
||
|
||
右侧“逆向分割映射视图”此前使用独立归一化 `viewExtent` 映射 STL 截面，左侧三维融合视图则根据 DICOM 物理尺寸和 `baseExtent` 计算显示尺寸；两侧视场和缩放来源不同，容易出现同一层切片下解剖结构和 Overlay Mask 大小不一致。
|
||
|
||
B. 产生问题原因
|
||
|
||
右侧算法只使用 STL bounds 做归一化，没有读取 DICOM `physicalSize`、`Pixel Spacing` 和 slice spacing；同时左侧三维视图过去按当前可见 STL 构件计算 bounds，构件显隐还可能改变左侧模型缩放。
|
||
|
||
C. 解决问题方案
|
||
|
||
右侧新增 `getPreviewPhysicalSize`、`getFovCanvasSize` 和同源 `getModelSceneMetrics`，用 DICOM 物理宽高、层厚、总层数和左侧 `baseExtent=4.6` 推导 `dicomWidth/dicomHeight/dicomDepth`、slice Z 与 `modelBaseScale`。左侧三维视图改为始终用全部 STL bounds 建立全局模型尺度，构件显隐只影响 Mesh 是否渲染。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
新增任何二维/三维联动视图前，先明确使用哪套物理坐标系和 FOV；DICOM Base Layer、STL Overlay、slice Z 和模型缩放必须从同一组 spacing、physicalSize 与全局 bounds 推导，不能在不同视图中各自定义归一化范围。
|
||
|
||
## 2026-05-20-00-38-39 实体 Mask 填充需要补齐内部空洞
|
||
|
||
A. 具体问题
|
||
|
||
仅依赖扫描线交点配对填充时，复杂 STL 截面或抽样边界可能产生小孔洞，视觉上仍会像漏隙，不符合“闭合实体区域”Mask 的审查预期。
|
||
|
||
B. 产生问题原因
|
||
|
||
Mesh-Plane Intersection 得到的是离散截面线段，浏览器端再进行像素级光栅化；线段精度、重复交点、边界浮点误差和抽样上限都可能让填充区域内部残留透明像素。
|
||
|
||
C. 解决问题方案
|
||
|
||
在每个构件的离屏 Mask ImageData 中完成扫描线填充后，从画布四边对透明区域做 flood fill 标记外部背景；任何未被外部连通到的透明像素都视为内部孔洞并填为当前构件颜色，再合成回主 Overlay。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
所有实体 Mask 光栅化都应包含“内部孔洞填补”或等价的连通域后处理；验证时不能只看边界是否有线，还要检查内部是否连续饱满。若后续接入后端体素化，也应保留连通域清理策略作为质量检查。
|
||
|
||
## 2026-05-20-01-08-38 工具栏空间不足时优先调整栅格比例
|
||
|
||
A. 具体问题
|
||
|
||
逆向工作区左侧“影像与模型融合视角”占用桌面端 7 栅格，中部“可视化工具栏”只占 2 栅格，导致三维视图偏大而工具栏过窄，模型位姿和构件层级控制显得拥挤。
|
||
|
||
B. 产生问题原因
|
||
|
||
早期布局更偏向三维展示，将主要横向空间给了融合视图；随着中部工具栏承担模型显示、融合显示、切分、位姿和构件层级等操作，2 栅格已经不足以承载密集控件。
|
||
|
||
C. 解决问题方案
|
||
|
||
将桌面端三栏比例从 `7 / 2 / 3` 调整为 `6 / 3 / 3`，右侧映射视图保持不变，左侧三维视图让出一格给中部工具栏。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
新增工具栏控件后，应重新评估三栏空间分配。操作密集型面板不能长期压缩在过窄栅格内；如果中部继续增加控件，应优先考虑分组、折叠或继续调整栅格比例。
|
||
|
||
## 2026-05-20-01-08-38 小步长控制需要同步显示精度
|
||
|
||
A. 具体问题
|
||
|
||
用户要求模型位姿平移步长改为 `0.005`，如果只改 slider step，而数值仍按两位小数显示，界面会把部分精细变化四舍五入隐藏。
|
||
|
||
B. 产生问题原因
|
||
|
||
旧显示逻辑用 `step < 1 ? 2 : 0` 固定小数位，适合 `0.05` 和 `1`，但不适合 `0.005` 这种三位小数步长。
|
||
|
||
C. 解决问题方案
|
||
|
||
新增 `getStepPrecision`，根据 step 本身计算显示小数位；平移 X/Y/Z step 改为 `0.005` 后自动显示三位小数，旋转仍显示整数，缩放仍显示两位小数。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
调整任何滑条或步进按钮的 step 时，同步检查数值展示、长按步进和手动输入精度，避免控制精度和显示精度不一致。
|
||
|
||
## 2026-05-20-01-38-33 NIfTI 导出必须与 DICOM 体数据同维同距
|
||
|
||
A. 具体问题
|
||
|
||
旧的 NII/NII.GZ 导出生成的是固定 `64x64x64` 演示 Mask，用户在 ITK-SNAP 中打开时无法与真实 DICOM 序列对应，表现为尺度、层数和内容都不可信。
|
||
|
||
B. 产生问题原因
|
||
|
||
早期导出接口没有读取真实 DICOM Pixel Data、Pixel Spacing 和 slice spacing，而是直接写入一个合成球体数据；这类演示数据适合验证下载链路，但不能用于医学影像工具复核。
|
||
|
||
C. 解决问题方案
|
||
|
||
后端新增真实 NIfTI-1 写入链路：DICOM 原始影像导出为 `512x512x300` int16 HU volume，分割影像导出为同维度 uint8 Label Map，并把 spacing 写入 NIfTI header。分割数据复用 STL 构件采样切面、当前位姿变换和扫描线填充逻辑生成，标签值对应构件 `partId`。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
任何影像导出功能都必须先确认维度、spacing、datatype、vox_offset 和真实数据来源。不能用固定尺寸演示数据替代生产导出；新增导出后至少用脚本读取 NIfTI header，并确认体素数和 DICOM 序列一致。
|
||
|
||
## 2026-05-20-01-38-33 浏览器下载不应依赖 blob:http 临时地址
|
||
|
||
A. 具体问题
|
||
|
||
浏览器控制台出现 `blob:http://... was loaded over an insecure connection`，用户误以为导出的 NII.GZ 文件本身或服务部署存在安全错误。
|
||
|
||
B. 产生问题原因
|
||
|
||
前端先 `fetch` 后端文件，再用 `URL.createObjectURL(blob)` 生成临时 `blob:http` 地址触发下载；在 HTTP 部署环境下，浏览器会对 blob 来源继承非安全上下文并给出警告。
|
||
|
||
C. 解决问题方案
|
||
|
||
将 NIfTI、DICOM 压缩包和多文件导出统一改成后端直链附件下载，由 Express 设置 `Content-Disposition`，前端只创建 `<a href="/api/...">` 触发下载，不再生成 blob URL。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
面向大文件、医疗影像和压缩包下载时优先使用后端附件直链。如果必须用 blob，应明确浏览器安全提示的影响；生产环境仍应考虑 HTTPS，但不能把 blob 临时地址当作常规下载路径。
|
||
|
||
## 2026-05-20-01-38-33 位姿列表需要进入项目状态而不是组件内存
|
||
|
||
A. 具体问题
|
||
|
||
用户保存的可视化工具栏位姿在重新进入项目后消失，造成调好的 STL/DICOM 对齐姿态无法继续复核或用于导出。
|
||
|
||
B. 产生问题原因
|
||
|
||
旧实现把 `savedPoses` 放在 `ReverseWorkspace` 组件本地 state 中，页面重新加载或重新进入项目时只会恢复默认、俯视、侧视三组临时位姿，没有写回后端项目状态。
|
||
|
||
C. 解决问题方案
|
||
|
||
为项目状态新增 `modelPoses` 字段，后端归一化默认位姿并提供 `PATCH /api/projects/:projectId/model-poses`；前端加载项目时读取 `project.modelPoses`，保存或重命名位姿时立即写回后端。
|
||
|
||
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-15-10 三维方向标识必须来自真实世界矩阵
|
||
|
||
A. 具体问题
|
||
|
||
右下角 XYZ 标识原先是静态 SVG，无法随模型旋转位姿和三维融合场景拖拽旋转变化；用户调整模型后，标识仍显示固定方向，容易误导“平移 X/Y/Z 后模型会往哪里移动”的判断。
|
||
|
||
B. 产生问题原因
|
||
|
||
旧标识只是界面装饰，没有读取 Three.js 中 `fusionRoot` 和 `modelPoseGroup` 的实时变换。模型实际显示方向由场景根节点旋转、模型位姿旋转和相机投影共同决定，静态二维箭头无法表达这个组合结果。
|
||
|
||
C. 解决问题方案
|
||
|
||
新增轴向投影辅助函数，在动画循环中读取 `modelPoseGroup` 的 world position 与 world quaternion，将模型局部 X/Y/Z 方向投影到当前 camera 屏幕空间，再驱动右下角小 SVG 的线段终点。使用投影签名去重，只有方向变化时才更新 React 状态。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
凡是三维视图中的方向、法向、切面或平移提示，都应从 Three.js 真实对象矩阵或统一坐标变换链路推导，不能手写静态示意。若该提示会随拖拽视角变化，还必须包含场景根节点和相机投影。
|
||
|
||
## 2026-05-20-02-32-47 分割影像与类别元数据必须同包同源
|
||
|
||
A. 具体问题
|
||
|
||
用户要求“导出全部 NII.GZ”改成压缩包形式，同时分割影像必须附带不同类别 ID 与名称的对应 JSON，并且分割范围可选所有类别或可见类别。如果 NIfTI 和 JSON 分开下载，或二者使用不同筛选条件，后续在 ITK-SNAP 查看时容易无法追溯标签语义。
|
||
|
||
B. 产生问题原因
|
||
|
||
旧前端对多个导出目标采用连续触发多个直链下载，缺少一个原子化导出包；旧分割生成逻辑默认跳过隐藏构件，也没有把实际参与导出的 label/partId/name/fileName/color 等元数据写入侧车文件。
|
||
|
||
C. 解决问题方案
|
||
|
||
新增 `/api/projects/:projectId/export-bundle`，将 DICOM NIfTI、分割 NIfTI、位姿 JSON 和分割 labels JSON 放入同一个 `.tar.gz`。分割生成函数和 labels JSON 生成函数共用 `segmentationScope=visible|all`，确保可见/全量筛选逻辑一致；labels JSON 中记录 label、partId、name、categoryName、className、fileName、color、opacity、visible 和 activePose。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
任何分割影像导出都应同时考虑语义侧车文件，并保证侧车元数据与实际 mask 标签来自同一批样式和筛选条件。多文件导出优先做成一个后端归档包，避免浏览器多下载顺序、丢文件或元数据错配。
|
||
|
||
## 2026-05-20-02-55-11 大面数 STL 导出不能复用预览抽样网格
|
||
|
||
A. 具体问题
|
||
|
||
用户在 ITK-SNAP 中查看导出的分割 NIfTI 时，`头部` 类别仍呈散点或点云状，而原始 `头部.stl` 是完整实体表面。
|
||
|
||
B. 产生问题原因
|
||
|
||
后端 NIfTI 分割生成复用了 `createStlPreview(file, 200000)` 的预览顶点数组。`头部.stl` 约有 257 万个三角面，但导出时最多只保留 20 万个抽样面；闭合轮廓被抽稀后，Mesh-Plane Intersection 生成的扫描线交点不连续，实体填充会退化成稀疏点/线。
|
||
|
||
C. 解决问题方案
|
||
|
||
保留预览抽样数据仅用于 bounds 和网页显示；NIfTI 导出路径改为逐三角读取完整二进制 STL buffer，对全部网格面执行位姿变换、平面求交和扫描线光栅化。同时后端每个构件、每个 slice 先写入临时二值 mask，再通过四边 flood fill 标记外部区域，将内部未连通孔洞补齐后写入最终 Label Map。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
预览数据、抽样数据和医学导出数据必须明确分层。凡是 NIfTI、Mask、Label Map、体素化这类可用于医学工具复核的导出功能，都不得复用用于前端性能优化的抽样网格；验证时必须检查大面数构件的 label 体素数量、slice 覆盖范围和侧视/冠状重建是否连续。
|
||
|
||
## 2026-05-20-03-19-25 分割结果保存必须携带位姿与导出上下文
|
||
|
||
A. 具体问题
|
||
|
||
用户要求在逆向工作区将当前“逆向分割映射视图”保存至项目库，并在项目库分割结果区域继续导出。如果只保存一个名称或时间，项目库无法复现保存当时的位姿、类别范围和构件样式。
|
||
|
||
B. 产生问题原因
|
||
|
||
分割结果不是一个静态按钮状态，而是由模型位姿、构件显隐、颜色、透明度、partId 和分割范围共同决定；这些上下文如果仍散落在组件 state 或只存在当前页面，重新进入项目库后导出的结果可能与保存时不一致。
|
||
|
||
C. 解决问题方案
|
||
|
||
项目状态新增 `segmentationResults`，保存当前结果名称、时间、`segmentationScope`、模型位姿和构件样式快照；逆向工作区通过后端接口写入项目，项目库分割结果区域读取该记录，并用最新保存结果的位姿作为导出默认输入。导出包新增 `stl` 目标，将原始 STL 文件放入同一个 tar.gz 中。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
凡是“保存至项目库”“保存结果”“复核后导出”类功能，都必须明确保存的是结果本体还是生成结果所需的上下文。医学导出相关记录至少要包含位姿、分割范围、标签样式和生成时间；新增导出目标时也要同步检查逆向工作区和项目库两个入口是否一致。
|
||
|
||
## 2026-05-20-11-07-27 软著素材位姿不能成为产品默认最佳参数
|
||
|
||
A. 具体问题
|
||
|
||
`head-ct-demo-pose-data.json` 只是软著和专利撰写时用于展示的素材，不应被产品标注为“最佳位姿”，也不应在用户进入项目时被默认优先加载。
|
||
|
||
B. 产生问题原因
|
||
|
||
早前为了演示效果，将示例位姿固化到前后端默认位姿列表，并在逆向工作区加载时优先选择“最佳位姿/位姿2”。这会把文档素材和产品运行时状态混在一起，导致用户误以为该位姿经过业务确认。
|
||
|
||
C. 解决问题方案
|
||
|
||
后端移除 `best/最佳位姿` 默认记录，并在归一化历史数据时过滤旧 `best` 项；前端移除 `headCtBestPose` 和默认保存位姿中的最佳项，项目加载时恢复优先选择 `default`，保留用户手动导入位姿 JSON 的能力。软著材料输出到 `新撰写软著文档/`，并明确不纳入 Git/Gitea 暂存。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
示例素材、专利素材、软著素材只能作为文档或手动导入资源使用，不能命名为“最佳”“推荐”等产品级默认值。今后新增默认位姿或默认参数时，应同时检查前端默认列表、后端状态归一化和项目加载优先级，避免文档素材污染运行时逻辑。
|
||
|
||
## 2026-05-20-11-34-57 软著截图自动化要兼顾 WebGL 渲染环境
|
||
|
||
A. 具体问题
|
||
|
||
为软著说明书插入真实系统截图时，普通 Chrome Headless 能正常截取登录、概况和项目库界面，但进入逆向工作区后页面空白，导致逆向工作区和导出选项截图不可用。
|
||
|
||
B. 产生问题原因
|
||
|
||
逆向工作区包含 Three.js 三维融合视图，普通 headless 环境中 WebGL 上下文创建失败，React 渲染链路被三维视图错误打断，最终截图只得到空白页面。
|
||
|
||
C. 解决问题方案
|
||
|
||
截图脚本在进入逆向工作区时改用 Chrome 软件 WebGL 参数，包括 `--enable-unsafe-swiftshader`、`--use-gl=angle` 和 `--use-angle=swiftshader`，等待页面稳定后重新截取逆向工作区与导出面板。生成 Word 时解析 Markdown 图片语法，并将 8 张 PNG 以嵌入媒体的形式写入说明书 `.docx`。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
凡是为含三维场景的页面生成截图或录屏，都应优先验证截图不是空白，并检查浏览器控制台是否有 WebGL 创建失败信息。自动化截图应准备软件渲染兜底；Word 交付前必须用 `unzip -l` 检查 `word/media/` 是否包含预期图片。
|
||
|
||
## 2026-05-20-11-51-05 默认医学数据资产入库需要明确体积与二进制属性
|
||
|
||
A. 具体问题
|
||
|
||
默认项目依赖 `Head_CT_DICOM/` 和 `Head_CT_ReConstruct/`，但两个目录原先被 `.gitignore` 排除。新环境只克隆代码时无法直接加载默认演示项目，需要额外复制医学数据资产。
|
||
|
||
B. 产生问题原因
|
||
|
||
早期工作流把 DICOM/STL 视为不进入普通文档备份的大型医学源数据，避免无意提交；但当前用户明确要求把默认项目数据作为仓库交付资产，以支持新环境开箱构建。
|
||
|
||
C. 解决问题方案
|
||
|
||
移除 `.gitignore` 中对 `Head_CT_DICOM/` 和 `Head_CT_ReConstruct/` 的忽略规则，新增 `.gitattributes` 将 `*.dcm` 和 `*.stl` 标记为 binary。提交前统计数据体积和文件数，验证默认项目接口仍返回 DICOM 300 张、STL 9 个构件。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
默认演示数据和运行态输出要分开管理：默认项目资产可以入库，但导出文件、状态文件和用户临时数据仍应保持忽略。新增大体积医学数据前必须记录体积、文件数、脱敏/授权假设和远端推送结果；若体积继续增长，应评估 Git LFS 或独立数据包发布。
|
||
|
||
## 2026-05-20-12-09-47 软著说明书逐章配图与视频需要同时校验交付格式
|
||
|
||
A. 具体问题
|
||
|
||
用户要求软著说明书中每一个 `## X.` 章节都配图，并录制系统使用视频，位姿导入必须使用 `head-ct-demo-pose-data.json`。如果只更新 Markdown 或只生成截图，不重新生成 Word 与视频，就会出现交付材料与源文档不一致的问题。
|
||
|
||
B. 产生问题原因
|
||
|
||
软著材料同时存在 Markdown、Word、截图目录和视频目录，多种格式之间没有自动同步机制；逆向工作区还依赖 WebGL 和隐藏文件输入，普通截图流程容易漏掉位姿导入成功状态或生成空白三维画面。
|
||
|
||
C. 解决问题方案
|
||
|
||
使用 Chrome 自动化打开系统核心页面并导入 `head-ct-demo-pose-data.json`，生成 23 张章节截图并插入到说明书 23 个 `## X.` 章节下；对 DICOM 信息截图中的患者姓名与编号区域进行遮盖脱敏；使用 `ffmpeg` 生成 H.264 MP4 系统使用视频；重新生成 `1. 软著说明书.docx` 并通过 `unzip -t` 和 `word/media` 数量检查确认 23 张图片已嵌入。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
软著说明书增加、删除或改名章节后，应重新跑“章节数、图片数、图片文件存在、Word 媒体数量、视频信息”五类检查。涉及医学影像信息截图时必须先确认是否存在患者姓名、编号等敏感字段；涉及位姿展示时必须记录所用 JSON 文件，并在截图或视频中保留导入成功状态。
|
||
|
||
## 2026-05-20-12-29-06 软著截图应区分完整页面与章节聚焦图
|
||
|
||
A. 具体问题
|
||
|
||
用户指出软著说明书中的图片不要截取。上一轮为了让章节主题更聚焦，将部分完整截图裁成局部卡片或面板，导致 Markdown 预览中图片像是只展示了页面片段。
|
||
|
||
B. 产生问题原因
|
||
|
||
软著说明书截图既要图文对应，又要保持审查材料中的界面完整性。局部裁剪虽然能突出功能区，但会丢失导航、模块位置和完整操作上下文，不符合用户对“完整截图”的预期。
|
||
|
||
C. 解决问题方案
|
||
|
||
重新使用 Chrome 自动化生成 23 张 1680x1050 完整视口截图，仅对 DICOM 信息截图中的患者姓名和患者编号值做遮盖脱敏，不再裁剪功能卡片或局部区域。重新生成 `1. 软著说明书.docx`，并通过章节图片引用、图片尺寸、Word 图片位置和服务部署检查。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
软著截图默认采用完整页面截图；只有用户明确要求“局部图”“放大细节图”时才裁剪。若同一完整页面用于多个章节，校验 Word 时应统计正文图片位置数量，而不能只看 `word/media` 文件数，因为 Word 会复用相同图片二进制。
|
||
|
||
## 2026-05-20-14-19-23 逆向分割结果单结果化需要前后端同时收口
|
||
|
||
A. 具体问题
|
||
|
||
用户要求项目库“分割结果”改为“逆向分割结果”，并且只保留一个当前结果，同时逆向工作区退出时询问是否保存、再次进入时读取项目库结果。如果只改前端展示，后端仍保存多条记录，导出和重新进入工作区会继续使用不一致的状态。
|
||
|
||
B. 产生问题原因
|
||
|
||
原有设计把 `segmentationResults` 作为历史列表保存，前端项目库按列表展示，后端导出接口默认使用当前请求参数或项目样式。新的业务语义改成项目级唯一当前结果，涉及保存接口、状态归一化、导出默认参数、工作区加载恢复和视图切换守卫多个链路。
|
||
|
||
C. 解决问题方案
|
||
|
||
后端归一化和保存接口均改为只保留最新一条逆向分割结果，并把位姿、构件样式、切片范围、映射切片和显示状态一起保存；导出接口默认读取最新保存结果。前端项目库改为两张结果预览图和统一导出面板；逆向工作区顶部集中保存与导出按钮，保存后显示渐隐提示；主应用视图切换时调用工作区离开守卫，保存失败时阻断退出。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
凡是把“历史记录”改为“当前唯一状态”的需求，都要同步检查数据模型、归一化逻辑、保存接口、列表 UI、导出默认参数和重新进入页面的恢复逻辑。提交前用 `rg` 搜索旧文案和旧入口，避免残留重复下载按钮或旧命名造成用户误解。
|
||
|
||
## 2026-05-20-14-53-31 保存提示与管理操作需要区分状态语义
|
||
|
||
A. 具体问题
|
||
|
||
用户要求逆向工作区在未修改或刚保存后离开时不再弹出保存确认，同时系统管理工作区的添加、编辑、删除用户按钮必须真正可用，并且不能删除当前登录用户。
|
||
|
||
B. 产生问题原因
|
||
|
||
上一轮实现的离开守卫只知道“正在离开逆向工作区”，不知道当前可视化状态是否已经保存，因此无条件弹窗；系统管理页原先只实现了用户列表和重置演示环境，操作按钮没有对应 API 和表单逻辑。
|
||
|
||
C. 解决问题方案
|
||
|
||
为逆向工作区建立保存快照，快照覆盖位姿、构件样式、切片范围、映射切片、模型显示、DICOM 融合强度、边界和切分状态；项目加载和保存成功后刷新快照，离开时只有当前快照与保存快照不同才弹确认。后端补齐 `/api/users` 的新增、编辑和删除接口，删除时拒绝当前登录用户；前端系统管理页改为真实表单和操作流。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
凡是“离开前确认保存”类交互，都要先定义脏状态快照，不能只按页面离开事件弹窗。后台管理按钮必须有明确接口、成功/失败反馈和权限边界；至少要覆盖新增、编辑、删除自己、删除其他用户四个验证场景。
|
||
|
||
## 2026-05-20-15-20-15 项目库结果视图应复用逆向工作区真实组件
|
||
|
||
A. 具体问题
|
||
|
||
用户指出项目库中的“影像与模型融合视角”和“逆向分割映射视图”仍像简化预览，不是逆向工作区里的真实效果；同时编辑用户弹窗字段缺少标签，编辑资料时仍出现密码修改入口，容易误解为保存资料会顺带改密。
|
||
|
||
B. 产生问题原因
|
||
|
||
项目库结果页此前为节省加载量，使用了单独的 STL 预览和 DICOM Canvas 组合，导致与逆向工作区的三维融合、二维映射算法和视觉层次不一致。用户管理表单把创建、编辑和改密共用一套输入框，密码字段只通过占位提示表达语义，交互边界不够明确。
|
||
|
||
C. 解决问题方案
|
||
|
||
将逆向工作区的 `FusionThreeView`、`VoxelizationMappingView`、显示精度和 DICOM 融合强度配置导出给项目库复用；项目库逆向结果页在有保存结果时加载 fusion volume，并直接渲染同款三维融合视图和二维映射视图。用户弹窗改为每个输入框都有字段标签；编辑模式只保留姓名、账号、科室；新增和修改密码模式均要求输入两遍密码并做一致性校验。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
凡是用户要求两个页面“效果一致”，优先抽取或导出已有真实组件，不再维护第二套近似 UI。涉及密码、权限、删除等高风险管理操作时，必须把资料编辑和凭据修改拆成不同入口，并通过显式标签、校验和反馈减少误操作。
|
||
|
||
## 2026-05-20-15-33-38 医学影像视图控件不要覆盖审查画布
|
||
|
||
A. 具体问题
|
||
|
||
用户指出逆向工作区的 `Slice Navigator` 格式与“DICOM 切片范围”不统一，并且 Overlay Label Map 的构件统计区域会遮挡 DICOM 影像，影响对二维切片和叠加分割结果的审查。
|
||
|
||
B. 产生问题原因
|
||
|
||
此前 `VoxelizationMappingView` 为了紧凑展示，把切片导航放在视图底部，同时将 Overlay 状态和构件列表使用绝对定位压在影像画布底部。该设计在普通预览中节省空间，但在医学影像核验场景中会遮挡 DICOM 主体区域。
|
||
|
||
C. 解决问题方案
|
||
|
||
将视图结构调整为“影像画布 + 右侧竖向切片导航 + 下方 Overlay 统计面板”：右侧竖向导航使用独立 `mapping-slice-vertical-input`，显示当前 DICOM 切片位置和上下层按钮；Overlay 构件列表移到画布下方，不再覆盖 DICOM 影像。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
医学影像主画布应优先保持无遮挡，状态、统计、导航控件默认放在画布外侧。若必须悬浮在影像上，只能使用小尺寸状态标识，并在提交前检查是否遮挡解剖结构或分割边界。
|
||
|
||
## 2026-05-20-15-54-46 视图交互状态与位姿参数要分层处理
|
||
|
||
A. 具体问题
|
||
|
||
用户要求右侧二维影像支持滚轮缩放、拖拽移动、位置重置，同时三维融合视图也需要视角复位，并增加按方向的三维等比例拉伸。如果把这些交互都写进位姿数据，容易把临时浏览状态误保存进项目结果。
|
||
|
||
B. 产生问题原因
|
||
|
||
二维缩放/平移、三维相机复位属于查看视口状态；模型平移、旋转、缩放属于会影响分割映射和导出的位姿参数。两类状态此前都在可视化层发生，如果不区分，很容易导致“只是看大一点”变成“改变了结果”。
|
||
|
||
C. 解决问题方案
|
||
|
||
二维映射视图新增独立 `mappingViewport`，只通过 CSS transform 同步作用于 Base DICOM 与 Overlay Canvas，不写入保存结果；三维融合视图用内部 `rootPose` 复位浏览相机，也不改变 `modelPose`。模型等比例拉伸则明确更新 `modelPose.scale`，并限制在旋转 X/Y/Z 均为 90° 整数倍时才可触发。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
新增影像查看交互时必须先判断它属于“浏览视口”还是“结果位姿”。浏览视口状态默认不进入保存和导出；只有会改变模型与 DICOM 空间关系的参数才进入 `modelPose`、保存快照和导出数据。
|
||
|
||
## 2026-05-20-21-25-19 结果复核视图与加载缓存要拆分展示形态
|
||
|
||
A. 具体问题
|
||
|
||
用户要求项目库“逆向分割结果”复用真实三维融合和二维映射效果，但项目库是复核场景，不需要工作区里的完整编辑控件；同时逆向工作区和项目库在跨模块返回时重复载入 DICOM/STL 预览，等待感明显。
|
||
|
||
B. 产生问题原因
|
||
|
||
此前 `FusionThreeView` 和 `VoxelizationMappingView` 虽然已复用到项目库，但组件只有一种工作区展示形态，项目库只能带着 Base/Overlay 标签、统计面板和较宽导航一起展示。DICOM 预览、DICOM fusion volume 和 STL preview 的缓存也在组件或页面局部，页面卸载后缓存随之丢失。
|
||
|
||
C. 解决问题方案
|
||
|
||
将只读预览数据缓存提升为模块级缓存函数，项目库、逆向工作区和 STL 查看器统一使用 `getCachedDicomPreview`、`getCachedDicomFusionVolume`、`getCachedModelPreview`。`FusionThreeView` 增加项目库复核视角预设，复位后呈现更正向的三维融合观察角度；`VoxelizationMappingView` 增加 `library` 紧凑变体，把窗宽、旋转和位置重置放在同一黑色工具行，画布内只保留视图名、DICOM 切片位置和窄竖向进度条。逆向工作区首次进入前增加加载页，显示进度、阶段和速度。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
同一个医学视图组件被复用到“编辑工作区”和“项目库复核”时，应优先通过 `variant` 或视角预设区分展示密度，而不是复制第二套近似实现。大体积医学预览数据应使用按项目、切片、窗宽、文件和采样精度组成的缓存 key，避免跨项目串数据；加载页只阻塞首次必要数据，不把普通浏览视口变化误判为需要重新进入全屏加载。
|
||
|
||
## 2026-05-20-22-07-46 导出命名与 Overlay 摘要位置要兼顾浏览器和视图语义
|
||
|
||
A. 具体问题
|
||
|
||
用户要求“导出项目及结果”的文件名改为“项目名_时间”，同时项目库与逆向工作区的逆向分割映射视图要共享黑底调控语言，但 Overlay Label Map 在项目库放右侧下方、在工作区保留在下方。
|
||
|
||
B. 产生问题原因
|
||
|
||
导出接口原先使用项目 ID 生成 `head-ct-demo-nifti-export.tar.gz`，便于程序处理但不便于用户归档。映射视图此前只区分工作区和项目库两种整体 `variant`，没有进一步区分 Overlay 摘要在右侧还是底部，导致布局需求变化时容易复制组件或堆叠条件。
|
||
|
||
C. 解决问题方案
|
||
|
||
后端新增项目名清洗、Asia/Shanghai 时间戳和 RFC 5987 `filename*` 响应头，导出包命名为 `项目名_时间.tar.gz`。前端在 `VoxelizationMappingView` 中增加 `overlayPlacement`，项目库使用 `side` 将 Overlay 摘要放到右侧下方，逆向工作区使用同一黑底工具行但传入 `bottom`，使 Overlay 保持在影像下方。项目库结果摘要移除切片和类别范围，仅保留构件总数、最后保存时间和模型位姿。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
涉及中文下载名时应同时设置 ASCII fallback 和 `filename*`，并用 `curl -D -` 抽查响应头。复用医学影像组件时，布局差异应继续沉到小粒度参数，例如 `overlayPlacement`、`viewPreset`，避免为了位置差异复制整套视图；同时确认 Overlay 摘要不遮挡 DICOM 主画布。
|
||
|
||
## 2026-05-20-22-35-42 项目导入不能覆盖默认医学数据
|
||
|
||
A. 具体问题
|
||
|
||
用户要求项目库 DICOM 与 STL 导入按钮真正可用，同时“头部CT 模型逆向体素化演示”仍作为测试数据保留，导入其他影像或模型不能污染默认 `Head_CT_DICOM/` 与 `Head_CT_ReConstruct/`。
|
||
|
||
B. 产生问题原因
|
||
|
||
后端此前所有 DICOM/STL 预览、导出和分割生成都硬编码读取默认数据目录，项目库导入按钮也没有对应上传接口。若直接把上传文件写入默认目录，会破坏演示环境重置语义，并让默认项目资产与用户项目资产混在一起。
|
||
|
||
C. 解决问题方案
|
||
|
||
新增项目级上传接口，将导入文件写入 `WebSite/data/uploads/<projectId>/DICOM|STL`，项目状态只保存相对路径；预览、三维融合、STL 模型、导出包和分割生成统一改为根据项目路径解析文件。恢复演示环境仍通过默认状态回到原始 `Head_CT_*` 数据。前端导入按钮接入隐藏文件选择器，并在无 DICOM/STL 时显示明确导入提示。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
凡是新增医学影像或模型导入能力，都必须区分“默认演示资产”和“项目用户资产”。后端路径解析不能继续硬编码单一目录；导入后要清理前后端缓存并清空旧分割结果，避免新数据套用旧预览或旧位姿结果。
|
||
|
||
## 2026-05-20-23-28-51 项目库结果操作要避免遮挡与误覆盖
|
||
|
||
A. 具体问题
|
||
|
||
用户指出位姿微调首次点击会带动可视化工具栏滚动条上跳，竖向 Slice Navigator 圆点没有稳定居中；项目库 Overlay Label Map 仍是黑色面板且位置不利于复核，“已保存”状态竖排；已有 DICOM/STL 再导入时缺少覆盖提醒，DICOM 详情也不应等点击后才解析。
|
||
|
||
B. 产生问题原因
|
||
|
||
位姿按钮在可滚动容器内按下时会触发浏览器默认焦点滚动，状态更新后滚动位置没有被恢复。项目库复用映射组件时仍使用组件内部深色 Overlay 摘要，导出入口放在下方导致菜单容易被页面边界裁切。DICOM 详情接口只做按需解析，导入流程没有缓存元数据，也没有在前端导入入口判断现有资产。
|
||
|
||
C. 解决问题方案
|
||
|
||
为位姿微调按钮增加 `preventDefault`，并在 `modelPose` 更新前后保持可视化工具栏 `scrollTop`。调整竖向 range input 的轨道和 thumb 偏移，使项目库与逆向工作区滑块居中。`VoxelizationMappingView` 增加 Overlay 统计回调和 `overlayPlacement="none"`，项目库外置浅色 Overlay 摘要；导出按钮移到顶部操作区，结果状态徽标增加不换行约束。项目导入前根据 DICOM/STL 现有数量弹覆盖确认；后端导入 DICOM 时生成 `.revoxelseg-dicom-info.json`，详情接口优先读取缓存。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
可滚动面板内的长按按钮要优先处理焦点滚动和滚动位置恢复；医学视图内的统计面板若影响主画布或菜单可达性，应外置为复核信息块。任何覆盖式资产导入都要在前端显式确认，并在后端同步生成或清理与资产强绑定的缓存，防止新旧 DICOM/STL 信息串用。
|
||
|
||
## 2026-05-21-00-05-04 大文件导入不能在浏览器内 base64 化
|
||
|
||
A. 具体问题
|
||
|
||
用户批量导入 STL 模型时 Chrome 出现 `Render process gone / Out of Memory`，同时 DICOM 和 STL 导入缺少进度条，也不能直接上传 ZIP 等压缩包，导致大体量医学数据传输和反馈体验都不稳定。
|
||
|
||
B. 产生问题原因
|
||
|
||
旧导入链路会在前端对每个文件执行 `arrayBuffer -> binary string -> base64`，再把所有文件塞进一个 JSON 请求。STL 或 DICOM 文件稍大时，浏览器会同时持有原始文件、ArrayBuffer、字符串、base64 和 JSON body 多份副本，内存膨胀很快；JSON 上传也无法可靠提供上传进度。
|
||
|
||
C. 解决问题方案
|
||
|
||
前端改为 `XMLHttpRequest + FormData` multipart 上传，使用 `xhr.upload.onprogress` 展示上传百分比、文件数和体积，上传完成后进入“服务器正在解压与解析”状态。后端引入 `multer` 使用磁盘临时文件接收上传，并支持普通 DICOM/STL、ZIP、TAR、TAR.GZ、TGZ 和单文件 GZ；解压后只筛选当前导入类型需要的文件，写入项目级上传目录，并清理运行缓存和临时文件。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
凡是医学影像、STL、NIfTI、压缩包等大文件导入，都不要在浏览器内转 base64 或拼接巨型 JSON；默认使用 multipart 或分片上传，并把解压、筛选、校验放在服务端。导入 UI 应区分“上传进度”和“服务器处理阶段”，避免用户误以为进度到 100% 就已经完成解析。
|
||
|
||
## 2026-05-21-00-43-44 导入失败要在主操作区保留可见错误
|
||
|
||
A. 具体问题
|
||
|
||
用户导入 `3279-STL.zip` 后浏览器控制台出现 `422 Unprocessable Entity`，但页面主操作区没有明显反馈，用户感知为“没有反应”。后续用同一 ZIP 直接调用接口验证可成功导入 26 个 STL，说明压缩包本体可读，问题更集中在失败反馈不可见和缺少后端可追踪日志。
|
||
|
||
B. 产生问题原因
|
||
|
||
前端导入异常只写入左侧项目栏底部的小号 `actionMessage`，主内容区域的进度条会消失，用户视线集中在右侧模型区域时很难看到错误。后端 422 返回虽然包含 `message`，但服务端没有记录项目、导入类型和文件数量，排查需要重新手工复现。
|
||
|
||
C. 解决问题方案
|
||
|
||
将项目库导入状态扩展为 `uploading/processing/done/failed`，失败时在顶部进度卡保留红色错误状态、百分比和后端错误原因，不再自动消失。后端导入 catch 中增加结构化日志，记录 `projectId`、`kind`、上传文件数量和错误消息。并用用户提供的 `3279-STL.zip` 对项目 `123` 实际导入，确认项目更新为 26 个 STL。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
所有文件导入、导出、保存这类长操作失败时，都要在主操作路径旁保留显眼错误卡，不能只写入边栏或短暂 toast。后端对 4xx/5xx 的可恢复业务错误应记录足够上下文，尤其是项目 ID、导入类型、文件数量和原始异常消息，方便从用户截图快速定位。
|
||
|
||
## 2026-05-21-00-58-25 三维视图需要 WebGL 降级保护且软著截图要强制视口
|
||
|
||
A. 具体问题
|
||
|
||
自动化浏览器回归进入逆向工作区时，Headless Chrome 在默认图形参数下无法创建 WebGL 上下文，`FusionThreeView` 直接抛出 Three.js 渲染错误，导致工作区组件崩溃。软著截图第一次生成时浏览器实际截图尺寸为 1680x963，与素材清单中约定的 1680x1050 不一致。
|
||
|
||
B. 产生问题原因
|
||
|
||
三维融合视图和 STL 切面预览此前默认 `new THREE.WebGLRenderer` 一定成功，没有捕获无 GPU、远程桌面、浏览器禁用硬件加速或 Headless 图形实现异常。截图脚本只设置了 Chrome 窗口大小，没有通过 DevTools `Emulation.setDeviceMetricsOverride` 强制页面视口，因此截图高度受 Headless 浏览器可用视区影响。
|
||
|
||
C. 解决问题方案
|
||
|
||
在 `FusionThreeView` 与 `CutSectionPreview` 初始化 WebGLRenderer 时增加 try/catch，创建失败时显示三维视图不可用提示，并保留二维 DICOM、逆向分割映射、保存和导出等功能继续可用。软著截图改用 Chrome Headless + SwiftShader WebGL 参数，并通过 DevTools 强制 1680x1050 视口；截图后用文件尺寸、章节图片数量、Word drawing 数量和代码汇总行数做校验。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
所有 WebGL/Three.js 视图都应把渲染器创建失败视为可恢复状态，不能让单个三维画布拖垮整个工作区。自动生成软著或验收截图时，除了设置浏览器窗口，还必须设置设备视口，并在生成后校验图片尺寸、非空像素、章节数量、图片引用和 docx 内嵌图片位置数量。
|
||
|
||
## 2026-05-21-09-29-47 自动拉伸要统一全局包围盒并限制短轴放大
|
||
|
||
A. 具体问题
|
||
|
||
项目 `123` 中，用户反馈初次进入逆向工作区时自动 Z 拉伸正常，但手动点击 `Z拉伸` 后仍像差一块；点击 `Y拉伸` 时模型整体会明显放大。同时用户要求 `缩放` 参数按三位小数展示，并且 `-` / `+` 每次只调整 `0.005`。
|
||
|
||
B. 产生问题原因
|
||
|
||
自动拉伸此前容易在不同路径中混用可见构件包围盒和三维融合视图使用的全局 STL 包围盒，重复点击时计算基准和实际渲染基准不完全一致。另一方面，单轴贴合本质是三维等比例缩放；当 Y 轴是模型短轴时，直接按 Y 轴填满 DICOM 会把 X/Z 同步放大，表现为一键明显放大并可能超出视场。缩放控件也沿用了 `0.05` 步长和两位小数显示，不适合精细配准。
|
||
|
||
C. 解决问题方案
|
||
|
||
逆向工作区自动拉伸统一读取项目全局 STL 包围盒，并用与三维融合视图一致的 DICOM 物理尺寸和基础比例计算目标缩放。单轴贴合时先计算所选轴目标缩放，再计算 X/Y/Z 三轴都能容纳在 DICOM 体内的上限，最终取两者较小值，保证 `Y拉伸` 不会越界放大。`scale` 控件步长改为 `0.005`，输入和显示按三位小数格式化；项目库 3D 模型位姿也同步改为 `0.005` 步长并对内部缩放值做三位小数取整。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
凡是涉及 STL 与 DICOM 尺度自动匹配的逻辑，都必须明确使用“全局包围盒”还是“可见构件包围盒”，并与实际渲染组件保持一致。单轴等比例贴合要考虑其他轴的视场约束，短轴贴合不能无限放大长轴；位姿数值控件的步长、显示精度、内部取整和导出数据要同步设计，避免 UI 看起来精细但实际状态漂移。
|
||
|
||
## 2026-05-21-10-05-51 软著材料更新要同步源码、截图、Word 与素材清单
|
||
|
||
A. 具体问题
|
||
|
||
用户要求继续更新 `新撰写软著文档/` 中的所有软著材料，并重新拍摄说明书图片。此前说明书、登记表、代码汇总和视频素材已经存在，但最新功能变更包括自动拉伸 DICOM 体范围约束、缩放三位小数、0.005 级微调等内容，若只更新文字或只更新截图，软著材料会与当前系统不一致。
|
||
|
||
B. 产生问题原因
|
||
|
||
软著材料由 Markdown、Word、图片、视频、代码汇总和素材清单组成，属于多文件联动交付。截图需要真实页面状态，代码汇总需要从当前源码重新生成，Word 又依赖 Markdown 和图片引用；任何一个环节未同步，都会出现说明书图片旧、代码摘录旧、Word 未嵌图或素材清单时间不一致的问题。
|
||
|
||
C. 解决问题方案
|
||
|
||
按 `※撰写Agent.md` 流程复查说明书、登记表、代码汇总和素材清单。使用 Chrome Headless + SwiftShader + DevTools 视口强制 1680x1050 重拍 23 张章节截图，避免 WebGL 截图为空。说明书补充自动拉伸、DICOM 体范围约束、三位小数缩放和 0.005 微调说明；登记表同步最新功能；代码汇总从当前核心源码重新生成；视频用最新章节截图重新生成 MP4；再用图片引用检查、docx 解压、Word 图片数量、代码行数、视频参数和项目构建做验证。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
后续只要系统功能发生变化并要求更新软著材料，应同时更新 Markdown 正文、截图、Word、代码汇总、视频脚本和素材清单，不能只改其中一项。截图自动化必须固定视口并校验图片尺寸、非空像素和引用数量；代码汇总应从当前源码机械生成或明确摘录范围；软著目录按用户要求不提交 Gitea，只提交工程分析记录。
|
||
|
||
## 2026-05-21-10-38-49 Docker 部署要同时处理默认资产、运行态挂载与公网隧道
|
||
|
||
A. 具体问题
|
||
|
||
用户要求停止旧程序，并新增本机与威联通 NAS 两套 Docker 部署方式，同时把 frpc 配置直接写入 Compose，将容器内服务映射到 FRP 服务端 `82.157.255.195` 的 `10008` 端口，最终支持 `http://192.168.3.11:4000/` 和 `revoxel.huijutec.cn` 双入口访问。
|
||
|
||
B. 产生问题原因
|
||
|
||
项目此前主要通过 `tmux + npm run serve` 运行，部署依赖当前工作目录和 Node 环境。Docker 化时如果只打包 `WebSite/`，默认项目会找不到仓库根目录下的 `Head_CT_DICOM/` 与 `Head_CT_ReConstruct/`；如果直接挂载整个 `WebSite/data` 和 `exports` 到镜像内部但不区分默认资产，又容易把运行态数据、导出文件或旧状态混进镜像和 Git。
|
||
|
||
C. 解决问题方案
|
||
|
||
新增 `Docker部署/`，在 Dockerfile 中以项目根目录为构建上下文，复制 `WebSite/`、`Head_CT_DICOM/` 和 `Head_CT_ReConstruct/`，容器启动时使用 `NODE_ENV=production` 与 `npm run serve -- --host 0.0.0.0 --port 4000`。两份 Compose 分别适配本机相对路径与 QNAP `/share/Container/revoxelseg_dicom` 绝对路径，运行态仅挂载 `/app/WebSite/data` 和 `/app/WebSite/exports`。frpc 容器启动时动态写入 `/tmp/frpc.toml`，映射 `revoxelseg_web:4000` 到远端 `10008`。同时在 `.dockerignore` 和 `.gitignore` 中排除构建缓存、运行态目录和导出数据。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
后续部署变更应先停止旧 4000 服务，再启动新部署方式，避免端口冲突。Docker 构建要明确区分默认演示资产、业务源码和运行态挂载目录；NAS 版 Compose 应使用绝对路径，方便 Container Station 直接导入。frpc 配置变更后必须查看 frpc 日志，确认 `login to server success` 和 `start proxy success`，再用局域网地址和公网域名分别验证。
|
||
|
||
## 2026-05-21-11-13-49 独立 Docker 程序包要脱离主工程验证
|
||
|
||
A. 具体问题
|
||
|
||
用户要求将完整 Docker 程序放到 `~/Desktop/ReVoxelSeg_DICOM_Docker`，后续即使没有原始 `ReVoxelSeg_DICOM` 文件夹也能直接运行；独立目录不应包含工程分析、软著材料和其他杂项，并要求 Docker Compose 文件放在程序根目录，同时在 Gitea 新开分支存储。
|
||
|
||
B. 产生问题原因
|
||
|
||
之前 Docker 部署文件位于主项目 `Docker部署/` 子目录，构建上下文依赖原始工程根目录。如果直接复制该子目录，缺少 `WebSite/`、默认 DICOM 和 STL 数据，无法脱离主工程运行；如果直接复制整个主工程，又会把工程分析、软著、参考模板、运行态数据和未跟踪测试文件一起带入独立部署包。
|
||
|
||
C. 解决问题方案
|
||
|
||
新建 `/home/wkmgc/Desktop/ReVoxelSeg_DICOM_Docker`，只同步 `WebSite/`、`Head_CT_DICOM/`、`Head_CT_ReConstruct/`，并排除 `node_modules`、`dist`、`data`、`exports` 和本地环境文件。将 `Dockerfile`、本机 `docker_compose.yaml`、NAS `docker_compose.nas.yaml` 和 README 放在独立目录根部。停止旧 Compose 后从独立目录执行构建和启动，验证局域网地址、公网域名、健康接口和 frpc 日志。最后在独立目录初始化 Git 仓库，推送到 Gitea 新分支 `docker-standalone-20260521`。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
后续若维护 Docker 独立包，应优先在 `ReVoxelSeg_DICOM_Docker` 目录内修改和验证，不要依赖主工程相对路径。根目录 Compose 文件中，本机版保留为 `docker_compose.yaml`，NAS 版使用 `docker_compose.nas.yaml`，避免同名文件冲突。独立分支内容结构与 main 不同，推送前必须检查目录纯净度，确认不含工程分析、软著材料、node_modules、dist、data、exports 等无关内容。
|
||
|
||
## 2026-05-21-14-19-12 Release 多版本发布要用 tag 固化配置差异
|
||
|
||
A. 具体问题
|
||
|
||
用户要求在 Gitea Releases 中发布机器直接部署版、NAS 直接部署版和通用版三个版本。其中通用版必须删除具体 FRPC 反向代理信息，避免固定服务地址、token、远端端口和公网域名限制其他环境使用。
|
||
|
||
B. 产生问题原因
|
||
|
||
独立 Docker 包的 `docker_compose.yaml` 默认面向当前机器部署，`docker_compose.nas.yaml` 面向 QNAP 绝对路径部署；如果只发布同一个分支源码包，用户下载后仍需判断使用哪个 Compose，通用版也会夹带当前环境的 FRPC 敏感配置。Gitea Release 又是以 tag 为版本锚点，必须为不同部署语义固定不同 tag。
|
||
|
||
C. 解决问题方案
|
||
|
||
在独立 Docker 仓库中从 `docker-standalone-20260521` 派生三个发布分支：机器版保留当前本机根目录 `docker_compose.yaml`；NAS 版将 NAS Compose 复制为根目录 `docker_compose.yaml`；通用版重写根目录 `docker_compose.yaml`，使用 `.env.example` 和环境变量占位 FRPC 信息，并删除固定 NAS Compose。随后为三种配置分别创建 tag，通过 Gitea API 创建三个 Release。发布前对三种 Compose 执行 `docker compose config`，并用 `rg` 检查通用版不含固定 FRPC 信息。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
以后发布多部署形态时，不要只改 Release 文案；应使用不同 tag 固化不同文件状态。包含具体环境配置的版本可以保留当前内网、域名和 FRPC 信息；通用版本必须使用环境变量或占位模板，并在发布前全目录搜索确认没有遗留服务地址、token、远端端口和固定域名。创建 Gitea Release 后，应再通过 API 或页面确认 Release、tag 和目标提交一致。
|
||
|
||
## 2026-05-21-14-35-20 多部署包应合并到单个 Release 的多个附件
|
||
|
||
A. 具体问题
|
||
|
||
用户指出机器直接部署版、NAS 直接部署版和通用版分别创建三个 Gitea Release 后，发布页面显得杂乱，查找和下载都不够直观；用户希望合并为一个发布项，并用不同附件名称区分部署场景。
|
||
|
||
B. 产生问题原因
|
||
|
||
此前把“部署场景”映射成了“Release 条目”，虽然 tag 追溯清晰，但 Gitea Releases 页面会出现多个同日期、同系统、只因部署配置不同而拆开的发布项。对使用者来说，版本概念应该只有一个，部署差异更适合作为同一 Release 下的资产附件呈现。
|
||
|
||
C. 解决问题方案
|
||
|
||
保留原三个部署 tag 和分支作为源码追溯锚点，新增整合 tag `revoxelseg-docker-all-v2026.05.21` 并创建单个整合 Release。使用 `git archive` 从三个 tag 分别生成本机直接部署版、威联通 NAS 直接部署版和通用版 `.tar.gz` 附件，上传到同一个 Release；确认三个附件均可从 Gitea API 读回后，再删除旧的三个分散 Release 记录。通用版发布前用文本搜索确认未包含固定 FRPC、域名和内网配置。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
后续同一版本存在多个部署形态、系统架构或环境模板时，优先使用“一个 Release + 多个命名附件”的发布模型；只有当版本号、功能内容或源码状态确实不同，才拆成多个 Release。删除旧 Release 前必须先确认新 Release 的附件数量、名称和大小均已从 Gitea API 读回，避免页面清理造成发布物短暂缺失。
|
||
|
||
## 2026-05-21-15-50-21 视频配音应以视频流时长对齐而非容器时长
|
||
|
||
A. 具体问题
|
||
|
||
用户要求为 5 分钟版和 10 分钟版系统使用视频生成配音版，并明确不能出现视频结束后仍有声音，或声音结束后视频继续播放。原始 MP4 的容器时长与视频流时长存在约 0.1 秒差异，如果直接按容器时长对齐音频，末尾可能出现极短的音频尾巴。
|
||
|
||
B. 产生问题原因
|
||
|
||
MP4 容器时长通常取所有流的最大持续时间，原始录屏中音频流和容器时长略长于视频流。配音合成时如果只读取 `format=duration`，会把旁白音轨拉到容器时长；播放器显示上虽然总时长一致，但最后一帧之后仍可能存在很短音频区间，不符合“视频结束不要还有声音”的交付要求。
|
||
|
||
C. 解决问题方案
|
||
|
||
先用 `ffprobe` 分别读取视频流时长、容器时长和音频时长，再以 `v:0` 视频流时长作为最终目标。TTS 原始音频与目标时长差距较小时，使用 `ffmpeg atempo` 做小幅伸缩，并用 `apad + atrim` 精确裁定到视频流时长。最终合成时只映射原视频流和新配音音轨，去除原始音轨，并再次用 `ffprobe` 验证视频流和音频流时长完全一致。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
后续生成配音、字幕或二次包装视频时，不能只看 MP4 容器总时长；必须同时检查视频流和音频流时长。若目标是避免片尾空声，应以视频流时长为准；若目标是保留完整旁白，则需要明确允许画面补帧或拉伸。大幅时长差不要依赖静音填充，应优先调整文案长度和 TTS 语速，再做细微 `atempo` 对齐。
|
||
|
||
## 2026-05-21-16-34-09 暂停服务时不应再执行重新部署
|
||
|
||
A. 具体问题
|
||
|
||
用户要求“停一下现在的系统”，目标是暂停当前服务，而项目工作流默认在修改完成后要求重新部署。如果机械执行重新部署，会违背用户本次意图，让系统又重新对外提供访问。
|
||
|
||
B. 产生问题原因
|
||
|
||
项目工作流面向常规功能修改和部署更新，默认以“修改后恢复服务”为完成标准；但本次属于运行态暂停操作，验收标准恰好相反，需要确认 Docker 容器停止、`4000` 端口释放、健康接口不可访问。
|
||
|
||
C. 解决问题方案
|
||
|
||
先检查当前运行来源，确认服务来自 `/home/wkmgc/Desktop/ReVoxelSeg_DICOM_Docker` 的独立 Docker Compose，而不是 `tmux`。随后执行 `docker compose -f docker_compose.yaml down`，同时停止 web 与 frpc 容器。停止后验证 Compose 服务为空、`4000` 端口无监听、本机健康接口连接失败、公网域名返回后端不可达状态。本次在工程分析中明确记录“不重新部署”是按用户要求执行。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
后续遇到“停止、暂停、下线、关闭服务”类请求时，工作流中的重新部署步骤应解释为“运行态验证”，而不是再次启动服务。最终汇报要明确服务已停、恢复命令是什么，以及哪些入口当前不可访问，避免把暂停请求处理成重启请求。
|
||
|
||
## 2026-05-23-00-32-26 系统功能描述要贴合演示系统真实边界
|
||
|
||
A. 具体问题
|
||
|
||
用户要求撰写 800-1300 字的系统功能文字描述，内容需要覆盖项目核心功能，同时不能把当前演示闭环写成已具备完整临床级自动分割或真实医学级体素化算法。
|
||
|
||
B. 产生问题原因
|
||
|
||
系统名称和目标包含“逆向体素化”“DICOM 分割标注”等较强算法语义，但工程整体分析已明确当前仍以演示闭环为主，真实医学级 STL 到 DICOM 空间体素化算法尚未接入。若只按目标愿景撰写，容易超出当前系统实际能力。
|
||
|
||
C. 解决问题方案
|
||
|
||
先阅读工作流、工程整体分析、经验记录、README 和核心页面源码，再提炼登录、总体概况、项目库、DICOM 预览、STL 预览、三维融合、位姿校准、构件样式、Label Map/NIfTI 导出和系统管理等真实功能。正文中特别使用“演示流程”“复核”“预留接口”等表述，避免承诺临床诊断或已完成真实算法接入，并用字符统计确认正文处于用户要求范围。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
后续撰写项目介绍、软著说明、验收材料或宣传文案时，应先核对工程整体分析和最新源码功能，再区分“已实现能力”“演示能力”和“后续预留能力”。涉及医学影像、分割、诊断和算法效果的表述必须保守准确，不能为了文字完整性虚构尚未落地的临床级能力。
|
||
|
||
## 2026-05-24-09-58-56 Docker 发布分支清理与公网生产模式部署
|
||
|
||
A. 具体问题
|
||
|
||
用户误删了主工程 `Docker部署/` 目录，同时 Gitea 中遗留四个 Docker 发布辅助分支。恢复本机 `tmux` 服务后，本机页面和公网 API 正常，但公网根路径一度返回 `403 Blocked request. This host ("revoxel.huijutec.cn") is not allowed.`。
|
||
|
||
B. 产生问题原因
|
||
|
||
`Docker部署/` 是已跟踪目录，被工作区删除后可从 Git 历史恢复。四个远端分支只是用于固化 v2026.05.21 Docker 发布包配置，Release 已由 tag 和附件承载，不再需要分支长期保留。公网 403 则是因为普通 `npm run serve` 未设置 `NODE_ENV=production`，服务进入 Vite 开发中间件，Vite 对公网 Host 执行 allowedHosts 拦截；同时公网访问还依赖 frpc 隧道，单独启动 Web 服务不足以恢复域名入口。
|
||
|
||
C. 解决问题方案
|
||
|
||
使用 `git restore -- Docker部署` 恢复主工程 Docker 部署文件。确认 Gitea Release `ReVoxelSeg DICOM Docker 部署包 v2026.05.21` 及 3 个附件、相关 tag 均存在后，删除 `docker-standalone-20260521`、`release/docker-machine-20260521`、`release/docker-nas-20260521`、`release/docker-generic-20260521` 四个远端分支。部署时先执行 `npm run lint` 与 `npm run build`，再用 `tmux` 运行 `NODE_ENV=production npm run serve -- --host 0.0.0.0 --port 4000`，并单独启动 host 网络的 `revoxelseg-dicom-frpc` 容器将本机 `127.0.0.1:4000` 映射到 FRP 远端 `10008`。最终验证本机健康接口、首页、公网首页、公网 API、项目数据和登录接口均可用。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
清理发布辅助分支前必须先确认对应 Release、tag 和附件均可读，再删除分支而不是删除 tag 或 Release。通过公网域名部署 `npm run serve` 时应使用 `NODE_ENV=production`，否则 Vite 开发中间件可能拦截公网 Host。公网域名验证要同时检查 Web 服务、frpc 登录与代理成功日志、`/api/health`、首页 HTML 和关键业务 API，避免只看本机 4000 端口。
|
||
|
||
## 2026-05-24-10-09-37 工程分析目录需要长期精简
|
||
|
||
A. 具体问题
|
||
|
||
`工程分析/` 中历史 `需求分析-*`、`实现方案-*`、`测试方案-*` 三件套数量过多，后续继续修改程序时，查找真正需要先读的核心约束和长期经验成本变高；部分早期历史文档此前已处于删除状态，也容易在提交时反复干扰状态判断。
|
||
|
||
B. 产生问题原因
|
||
|
||
原工作流要求每次修改前创建三件套，但没有规定历史三件套的保留周期。随着需求持续迭代，一次性分析文件不断堆积；真正长期有价值的内容实际已经沉淀在 `工程整体分析.md` 和 `经验记录.md` 中，历史三件套更多用于当次可追溯，适合交给 Git 历史保存。
|
||
|
||
C. 解决问题方案
|
||
|
||
保留 `代码编纂工作流.md`、`工程整体分析.md`、`经验记录.md` 和本次 `2026-05-24-10-09-37` 三件套，删除历史三件套与一次性 `系统功能描述-*` 文档。同步更新 `代码编纂工作流.md`，新增工程分析目录精简策略：后续仍必须创建当次三件套，但历史三件套不再默认长期堆积，可通过 Git 历史追溯；长期坑点必须追加进 `经验记录.md`。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
后续做程序修改时优先阅读核心三文档和当次三件套，不要在目录中长期堆积几十个历史流水文件。若某次需求产生可复用经验，应写入 `经验记录.md`；若只是一时执行细节，则交由 Git commit 历史保存。文档治理提交前必须确认没有混入源码、医学数据或运行态文件。
|
||
|
||
## 2026-05-24-10-45-43 分割显示、镜像位姿、DICOM 顺序与导出包结构联动修正
|
||
|
||
A. 具体问题
|
||
|
||
逆向分割映射中部分 STL 构件在二维 DICOM 切片上显示为线段或横向连接线，不像填充实体；模型位姿缺少以模型中心沿 X/Y/Z 轴镜像翻转的能力；“构件分别导出”需要所有构件 NIfTI 集中在同一目录；项目库 DICOM 首页缺少滚轮缩放、拖拽平移和位置重置；项目库和工作区的 DICOM 切片编号使用了数组索引顺序，初始显示为 `1/300` 而不是用户期望的 `300/300`，滑条也被误读成进度条。
|
||
|
||
B. 产生问题原因
|
||
|
||
前端叠加层虽然已有扫描线填充，但在交点稀疏或切面轮廓退化时仍会绘制大量切面线段，视觉上变成“线连接”；服务端导出只保留扫描线交点，缺少稀疏轮廓兜底。`ModelPose` 只包含旋转、平移、缩放，保存、预览、导出都没有镜像字段。DICOM 预览使用零基索引直显，未转换为医学查看习惯的反向层号。自写 tar 导出头只写 100 字节 name 字段，长中文路径会被截断，集中目录后更容易暴露。
|
||
|
||
C. 解决问题方案
|
||
|
||
为 `ModelPose` 和 `ModelPoseValue` 增加 `flipX/flipY/flipZ`，在默认值、归一化、保存、导入、三维预览、二维映射和服务端 NIfTI 导出中统一生效。二维叠加层改为优先实体填充，稀疏切面用闭合外轮廓兜底，已有填充结果不再叠加粗线段；服务端导出同步增加闭合外轮廓兜底写入。项目库 DICOM 首页新增独立 viewport 状态，支持滚轮缩放、拖拽平移和位置重置。DICOM 显示层号统一使用 `total - sliceIndex`，滑条值反向映射且使用菱形非进度条样式。`separate` 导出改到 `segmentation-parts/` 同一目录，并给 tar 生成补充 PAX path 头，保证中文长路径和 `.nii.gz` 扩展完整。Docker Compose 镜像标签和 README 同步到 20260524 能力说明。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
凡是新增位姿字段，必须同时检查前端类型、默认状态、保存/导入、三维渲染、二维映射、服务端归一化、导出坐标变换和项目库回放，不能只改一个界面。涉及 DICOM 层号时要明确区分“数组索引”和“对用户显示的医学层号”。导出压缩包如果包含中文或深层路径，必须用 `tar -tzf` 验证路径完整，不要依赖 100 字节 tar name 字段。分割显示的视觉修正也应同步确认导出数据路径，避免 UI 看似实体而 NIfTI 仍是轮廓。
|
||
|
||
## 2026-05-24-15-37-16 STL 切面填充不能跨断开轮廓全局配对
|
||
|
||
A. 具体问题
|
||
|
||
用户反馈逆向分割映射视图中仍有 mask 呈线条状，导出的 `label.nii` 里 `liver_artery` 等构件出现不规则相连长线和内部黑色线条。项目库 DICOM 影像的“位置重置”也需要放到左转、右转同一工具组，减少查找成本。
|
||
|
||
B. 产生问题原因
|
||
|
||
检查 `project-mpea0n3e-akbpn` 的 `liver_artery.stl`，其二进制 STL 约 220920 个三角面、331119 条量化边，其中边界边为 0，非流形边约 27 条，占 0.008%，说明它不是大面积开口模型。主要问题来自旧体素化逻辑：同一切片上把全部相交线段按扫描行收集后全局排序并两两配对。如果同一行存在多个断开的轮廓、孤立碎片或少量非流形小片，就会把不同连通区域的交点配成一条长桥；内部横向黑线则来自相邻扫描行之间的 1-2 像素细缝没有闭合。
|
||
|
||
C. 解决问题方案
|
||
|
||
前端 overlay 与服务端 NIfTI 导出均改为先按线段端点近邻关系做连通分组，每个连通组独立扫描线填充和闭合外轮廓兜底，避免跨断开轮廓配对。对已生成的二值 mask 增加小缝隙闭合，再执行内部孔洞填充，用于减少实体区域内部横向黑线。项目库 DICOM 画布增加外部 reset token，把“位置重置”按钮放到左转、右转旁边，直接复位缩放和平移。
|
||
|
||
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-16-28-58 导出可见类别必须以当前项目样式为准
|
||
|
||
A. 具体问题
|
||
|
||
用户只显示 `liver_artery` 和 `liver_right` 后，选择“可见类别 + 构件分别导出”，导出包中仍出现 `007-liver_segment_S1-label.nii.gz`、`008-liver_segment_S2-label.nii.gz`、`009-liver_segment_S3-label.nii.gz`。同时，逆向分割映射中 `liver_right` 大区域出现条纹和异常形状，`liver_artery` 仍显得像多条线。
|
||
|
||
B. 产生问题原因
|
||
|
||
项目当前 `moduleStyles` 中 `liver_artery`、`liver_right` 是可见，`S1/S2/S3` 是隐藏；但最新一次保存的 `segmentationResults` 中可见状态正好相反。旧导出逻辑使用历史保存结果的 `moduleStyles` 覆盖项目当前样式，导致“可见类别”按旧状态导出。二维 overlay 另一个问题是 STL 预览最多抽样 20 万三角面，而 `liver_right` 有约 29.7 万面、`liver_artery` 有约 22.1 万面，抽样会缺失一部分切面轮廓，表现为条纹或形状不完整。血管本身也属于细长管状结构，真实切面不会像肝叶一样形成单一大块。
|
||
|
||
C. 解决问题方案
|
||
|
||
导出时合并样式优先级改为：历史保存结果作为 fallback，项目当前 `moduleStyles` 覆盖历史结果，前端导出请求中传入的当前 `moduleStyles` 再覆盖后端状态。这样即使用户刚点击眼睛后立刻导出，也按当前可见状态过滤。逆向分割映射只加载当前可见构件，并把可见构件预览上限提高到 50 万三角面；`liver_right` 与 `liver_artery` 在项目 `123` 中均可全量取面。Docker 文档同步说明“可见类别 + 构件分别导出”严格只导出当前眼睛打开的构件。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
凡是导出“当前可见”这类 UI 状态，不能只依赖历史保存结果；后端应以项目当前状态为准，前端最好显式携带本次导出的关键状态，防止异步保存延迟。二维 overlay 如果用于判断实体形状，必须确认 STL 预览不是抽样缺面；对超过预览上限的大模型，应按可见构件高精度加载或在界面提示。细血管、胆管等管状结构应解释为“天然多小截面/窄带”，不要把所有结构都承诺成单一大实体块。
|
||
|
||
## 2026-05-24-17-29-17 构件层级切换要有加载反馈并避免 passive 事件告警
|
||
|
||
A. 具体问题
|
||
|
||
用户反馈调整逆向工作区“构件层级”时可能出现暂时不显示或看起来像 bug，同时浏览器控制台反复打印 `Unable to preventDefault inside passive event listener invocation`。
|
||
|
||
B. 产生问题原因
|
||
|
||
逆向分割映射视图为了修正抽样缺面，已经改成按当前可见构件高精度加载 STL preview。构件眼睛切换后，新 preview 在网络和前端缓存返回前，旧 overlay 被清空或尚未绘制，界面没有明确进度反馈。另一个问题是项目库 DICOM 画布和逆向映射画布仍使用 React `onWheel` 调用 `preventDefault`，部分浏览器会把 wheel/touch 合成事件按 passive 处理；按钮 `onTouchStart` 中的 `preventDefault` 也会增加同类告警风险。
|
||
|
||
C. 解决问题方案
|
||
|
||
为逆向分割映射视图新增 `overlayLoadState`，在可见 STL 构件列表变化时清空旧 preview、显示 `loaded/total` 进度条，并在每个构件 preview 成功或失败后更新进度，全部完成后再绘制最新 overlay。项目库 DICOM 画布和逆向映射画布改为原生 `addEventListener('wheel', ..., { passive: false })`，保留滚轮缩放和阻止页面滚动能力。长按步进按钮改用 pointer 事件和 `touch-none`，移除 touch 合成事件里的 `preventDefault`。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
后续只要某个 UI 操作会触发异步加载大 STL、DICOM 或导出预计算，都应提供明确加载状态、进度和空状态，避免用户把正常等待理解为显示故障。需要阻止滚轮默认滚动时，应使用原生非被动 wheel 监听并在卸载时清理；触摸按钮优先使用 pointer 事件和 `touch-action` 控制，不要在 passive-prone 的 touch 合成事件中调用 `preventDefault`。
|
||
|
||
## 2026-05-24-18-59-49 薄壳和细长构件需要局部实体化兜底
|
||
|
||
A. 具体问题
|
||
|
||
用户反馈当前项目中 `rib` 在三维融合视图里仍像散点，逆向分割映射视图右侧仍有一条一条的线；希望 `skin`、`rib` 等所有构件在映射视图中尽量显示为实心。
|
||
|
||
B. 产生问题原因
|
||
|
||
当前项目 `rib.stl` 有 524364 个三角面、`skin.stl` 有 2720412 个三角面。此前实体模式预览上限为 20 万，二维映射高精度上限为 50 万；由于预览抽样使用 `ceil(triangleCount / limit)` 计算步长，`rib` 在 50 万上限下仍会变成每隔一个三角面取样，细长结构更容易断成点线。另一个原因是二维填充主要依赖扫描线交点配对，近水平切线会被跳过；当 thin shell 或肋骨切面不能形成完整闭合轮廓时，就只剩线段描边。
|
||
|
||
C. 解决问题方案
|
||
|
||
将实体模式和逆向分割映射预览上限提高到 80 万，服务端 STL preview 上限同步提高到 80 万，使 `rib` 能全量进入实体预览，`skin` 也能获得更高密度抽样。三维实体模式材质改为不透明并写入深度，减少透明材质排序造成的散点观感。前端 overlay 和服务端 NIfTI 导出在扫描线填充之外，对每个连通组的原始切面线段绘制局部 capsule 厚度，再做小缝隙闭合和内部孔洞填充，保证薄壳、细长构件也有实体化兜底。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
后续遇到薄壳、肋骨、皮肤、血管等结构显示成点线时，要同时检查三件事：STL preview 是否因上限导致抽样缺面、二维切面算法是否跳过水平/切线段、透明材质是否造成三维自排序噪声。实体化显示和导出必须同步处理，不能只改 UI；但局部厚度兜底属于演示/显示后处理，接入真实体素化算法后应作为可配置显示选项，而不是替代真实分割算法。
|
||
|
||
## 2026-05-24-19-11-30 位姿微调步进要与显示精度同步
|
||
|
||
A. 问题现象
|
||
用户希望缩放、平移每次移动改为 `0.001`，以便后续对模型与 DICOM 的配准做更细微调整。
|
||
|
||
B. 原因分析
|
||
逆向工作区和项目库各自维护位姿控件步进；平移、缩放曾使用 `0.005`、`0.05` 和 `0.25` 等不同粒度。若只改按钮步进，不同步滑杆 step、显示精度和归一化取整，保存后的位姿可能看起来或实际不是 0.001 级别。
|
||
|
||
C. 处理方式
|
||
将逆向工作区 `poseStepConfig` 中平移 X/Y/Z 与缩放步进统一为 `0.001`，项目库位姿控件的按钮 delta、range step 也统一为 `0.001`。同时为项目库和服务端平移/缩放字段补充三位小数归一化，保证按钮、滑杆、显示、保存和导出使用同一精度。
|
||
|
||
D. 后续建议
|
||
后续调整位姿控件时，要把步进、按钮 delta、range step、数字显示、前端状态归一化、服务端保存归一化和导出数据一起检查；不要只改单个页面或单个控件，否则会出现项目库与逆向工作区微调精度不一致。
|
||
|
||
## 2026-05-24-19-17-13 自动拉伸成功提示不要长期占位
|
||
|
||
A. 具体问题
|
||
|
||
用户点击 `Z拉伸` 后，页面保留“已按 Z 方向进行三维等比例拉伸”提示。该提示不是错误，也不需要长期显示，容易占用界面注意力。
|
||
|
||
B. 产生问题原因
|
||
|
||
自动拉伸成功分支复用了位姿导入/保存状态 `poseImportStatus`，并在每次成功后写入持久成功文案；按钮本身已经有 `stretchingAxis` 加载态，成功后的额外文字反馈并非必要。
|
||
|
||
C. 解决问题方案
|
||
|
||
自动拉伸成功后仍更新模型 `scale` 并保持工作区脏状态判断，但立即清空 `poseImportStatus`。前置校验和异常分支继续写入 `fusionError`，确保数据未加载、角度不满足条件或计算失败时仍有明确错误提示。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
后续新增操作反馈时，要区分“处理中反馈”“成功反馈”和“错误反馈”。短操作可以只保留按钮加载态和错误提示，避免把普通成功信息写入长期占位区域；如果确实需要成功提示，应设计为短暂 toast 或局部临时状态。
|
||
|
||
## 2026-05-24-19-53-00 单击精度和长按速度要分离
|
||
|
||
A. 具体问题
|
||
|
||
平移和缩放已经改为 `0.001` 级微调后，单击精度足够细，但长按加减按钮仍按每次 `0.001`、约 `90ms` 一次重复，连续移动速度太慢。
|
||
|
||
B. 产生问题原因
|
||
|
||
旧长按逻辑直接复用单击的最小步进作为 repeat delta。步进从 `0.005` 降到 `0.001` 后，长按单位时间位移也同步降低，导致用户需要按住很久才能看到明显变化。
|
||
|
||
C. 解决问题方案
|
||
|
||
保留单击仍为 `0.001`，只在长按 repeat 中为平移 X/Y/Z 和缩放使用 5 倍最小步进，并将启动延迟从 `360ms` 缩短到 `240ms`、repeat 间隔从 `90ms` 缩短到 `55ms`。这样短按仍精细，长按可快速穿过较大范围。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
微调控件应把“单击精度”和“长按速度”作为两个参数设计；不要为了长按快而增大最小 step，也不要为了单击精细而让长按只能按最小 step 慢慢跑。调整 repeat 参数后要确认松开、移出和取消 pointer 时定时器会停止。
|
||
|
||
## 2026-05-24-20-06-08 可见构件不能改变映射坐标系
|
||
|
||
A. 具体问题
|
||
|
||
用户反馈不显示 `liver_artery` 时，`liver_segment_S2`、`liver_segment_S3` 不显示或需要跳到更靠后的切片才显示；打开 `liver_artery` 后，`S2/S3` 又回到原先层位附近。
|
||
|
||
B. 产生问题原因
|
||
|
||
逆向分割映射视图为了减少高面数 STL 加载量，只加载当前眼睛打开的高精度 preview；但绘制前的 `getModelSceneMetrics` 也使用了同一组可见文件计算模型全局 bounds。隐藏 `liver_artery` 后，全局中心、基础缩放和 DICOM Z 轴映射被重新计算，其他肝段构件等于换了一个坐标系，所以出现消失或跳层。
|
||
|
||
C. 解决问题方案
|
||
|
||
将“绘制用高精度 preview”和“坐标系用全局 bounds preview”拆开：高精度 preview 仍只加载当前可见构件；另行用低抽样 preview 读取全部 STL 的 bounds，并在 `drawVoxelOverlayLayer` 中使用全部 STL bounds 计算统一 `ModelSceneMetrics`。这样关闭 `liver_artery` 只会隐藏它自己，不会让 `liver_segment_S2/S3` 的层位和位置改变。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
涉及 DICOM/STL 配准的坐标系必须独立于可见性、筛选条件和 UI 状态；性能优化可以只加载可见构件的高精度网格，但全局中心、缩放、slice Z 映射应来自稳定的全部模型边界。凡是用户反馈“隐藏某构件后其他构件位置变了”，优先检查 bounds 是否被可见列表重算。
|
||
|
||
## 2026-05-24-22-40-13 自动微调匹配要锁定人工旋转并使用同一导出坐标系
|
||
|
||
A. 具体问题
|
||
|
||
用户希望在逆向工作区先人工调好大致旋转，然后进入一个新的自动微调匹配工作区，只让系统自动尝试平移 X/Y/Z 与缩放，使用骨骼区域和 DICOM 骨窗收敛到更好的位置。
|
||
|
||
B. 产生问题原因
|
||
|
||
项目此前只有人工位姿控件和导出时的 STL/DICOM 映射逻辑，没有单独的自动优化入口。若自动匹配重新定义坐标系或允许修改旋转，会破坏用户已经完成的人工粗配准；若评分只奖励重合，不限制移动和缩放，也容易出现“为了命中骨窗而漂移”的局部最优。
|
||
|
||
C. 解决问题方案
|
||
|
||
新增 `AUTO_MATCH` 视图、侧边栏入口和逆向工作区顶部“自动微调匹配”按钮，点击时携带当前位姿。服务端新增 `POST /api/projects/:projectId/auto-match` 和 `PATCH /api/projects/:projectId/model-pose`：匹配接口复用导出模块的 STL 全局 bounds、DICOM HU 体数据和 `transformPointForExportPose` 位姿变换；默认选择骨骼命名 STL，按三角面中心采样，使用 HU 骨窗阈值给骨命中奖励、非骨/越界惩罚，并叠加移动惩罚和缩放惩罚；候选搜索从粗到细尝试单参数和组合参数。应用接口会写入 `auto-match` 位姿，并在项目锁定时拒绝覆盖。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
后续继续优化自动配准时，要保持“人工旋转锁定、自动只微调平移/缩放”的边界，且必须复用导出/映射同一坐标系。评分函数可以继续替换为 Dice、Chamfer、距离变换或多线程 Worker，但移动惩罚、缩放惩罚、候选上限和锁定项目保护不能省；否则会出现匹配看似得分更高、实际位置漂移或覆盖锁定项目的问题。
|
||
|
||
## 2026-05-24-23-24-34 自动匹配采样切片要可调且真实参与评分
|
||
|
||
A. 具体问题
|
||
|
||
用户运行自动微调匹配后，结果中的平移和缩放变化都显示 `+0.000`，容易理解为算法没有运行；同时采样切片只能展示，不能人工加密或调整。
|
||
|
||
B. 产生问题原因
|
||
|
||
`+0.000` 的直接原因是本轮候选里“保持当前/初始位姿”的得分最高，最佳位姿没有超过当前位姿，所以相对变化为 0。另一个问题是后端虽然返回了 `sampleSlices`，但评分时仍遍历全部 STL 采样点，没有按用户关注的 DICOM 切片过滤，导致采样切片在第一版中更像结果说明而不是优化输入。
|
||
|
||
C. 解决问题方案
|
||
|
||
自动微调匹配工作区新增采样切片输入，按界面可见的 `1-N` 切片编号填写，支持离散切片和范围步长写法，运行前转换为接口内部的 `0-(N-1)`。后端 `AutoMatchContext` 增加 `sampleSlices`，评分时只统计落在采样切片附近的 STL 点，并用最近采样切片的 DICOM HU 骨窗值计算命中奖励和惩罚。结果面板新增最佳模式，并在最佳位姿无可见变化时提示“当前位姿得分最高，所以显示 +0.000”。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
凡是页面允许用户配置的优化条件，都要确认该条件确实进入评分函数，而不是只进入展示层。医学切片编号在 UI 中使用 `1-N`，服务端计算用 `0-(N-1)`，转换必须集中在请求边界。自动优化结果如果没有改变位姿，应明确解释“当前就是本轮最高分”，避免用户误以为按钮或算法没执行。
|
||
|
||
## 2026-05-25-00-07-30 自动匹配页应以映射对比为主，高精度预览要压缩传输
|
||
|
||
A. 具体问题
|
||
|
||
用户认为自动匹配页下方候选表格和若干统计卡片价值不大，希望直接看到逆向分割映射视图，并能用同一个切片进度条对比当前位姿和自动匹配结果。同时用户反馈公网请求 `sternum.stl/preview?limit=800000` 会报 `ERR_HTTP2_PROTOCOL_ERROR`。
|
||
|
||
B. 产生问题原因
|
||
|
||
自动匹配第一版偏调参和数值轨迹，缺少与逆向工作区一致的可视化闭环。高精度 STL preview 返回的是很大的 JSON，未压缩时在 HTTP/2 反向代理链路中更容易触发传输错误或代理缓冲限制。
|
||
|
||
C. 解决问题方案
|
||
|
||
自动匹配页移除候选轨迹表和低价值统计卡片，复用 `VoxelizationMappingView` 放置当前位姿/自动匹配结果两个对比画面，并新增共享横向切片条；视图只显示用户选中的骨骼构件，且骨骼区域默认空选。采样切片改为按数量均匀生成，默认 9 张。默认评分权重调整为非骨区域惩罚 `0.1`、移动惩罚 `0`、缩放惩罚 `0`。后端新增 JSON gzip 发送 helper，STL preview 大响应在浏览器支持 gzip 时压缩返回，缓解公网 HTTP/2 大响应失败。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
自动优化类页面应优先提供可视化验证，而不是只展示候选表格。高精度 STL preview 继续使用 JSON 时，必须关注响应大小、压缩和代理限制；若后续仍遇到大模型传输问题，应考虑二进制 preview、分块流式加载或按切片局部计算，而不是继续扩大单次 JSON。
|
||
|
||
## 2026-05-25-10-21-17 公网部署需要同时验证首页和 API
|
||
|
||
A. 具体问题
|
||
|
||
用户要求重新部署 `https://revoxel.huijutec.cn/`。本机 `4000` 服务启动后，公网 `/api/health` 返回 200，但公网首页返回 403：`Blocked request. This host ("revoxel.huijutec.cn") is not allowed.`
|
||
|
||
B. 产生问题原因
|
||
|
||
当前约定的 `npm run serve` 默认未设置 `NODE_ENV=production`，Express 会挂载 Vite middleware，而不是只走 `dist/` 静态文件。Vite 6 会校验 Host，请求从公网域名进入时不在 `server.allowedHosts` 中，因此首页被 Vite 拦截；API 路由位于 Vite 中间件之前，所以 `/api/health` 仍然正常。
|
||
|
||
C. 解决问题方案
|
||
|
||
在 `WebSite/server.ts` 的 `createViteServer` 配置和 `WebSite/vite.config.ts` 中加入 `allowedHosts: ['revoxel.huijutec.cn']`，重新执行 `npm run build`，再用 `tmux` 会话 `revoxelseg-dicom` 启动 `npm run serve -- --host 0.0.0.0 --port 4000`。验证本机首页、本机 `/api/health`、公网首页和公网 `/api/health` 均返回 200。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
部署验证不能只看 API 健康检查，还要同时验证首页 HTML，因为 Vite host 检查、静态资源路径和反代规则可能只影响页面入口。只要继续用 Vite middleware 方式提供公网访问，就要把公网域名写入 `allowedHosts`；如果后续改为 `NODE_ENV=production` 纯静态部署，也需要单独验证静态资源和 API 是否都通过同一反代链路。
|
||
|
||
## 2026-05-25-12-30-27 软著代码汇总应选完整连续源码文件
|
||
|
||
A. 具体问题
|
||
|
||
用户要求整理 `3. 代码汇总.docx`，原文档不能继续保留用三点字符表示删减的代码摘录；软著材料需要无省略、连续、逻辑完整的源程序内容，约 10000 行即可，不需要放入项目全部代码。
|
||
|
||
B. 产生问题原因
|
||
|
||
软著源程序材料关注的是完整连续的代码页。若为了节省篇幅在函数体、类定义或模块中间放置省略占位，即使整体看起来像代码汇总，也会被判断为摘录而不是完整源程序。项目中的 TypeScript/JavaScript 真实源码也可能包含扩展运算符等合法三点语法，需要和删减占位区分检查。
|
||
|
||
C. 解决问题方案
|
||
|
||
本次直接重写 `3. 代码汇总.docx`，选择 `WebSite/server.ts`、`WebSite/src/components/ReverseWorkspace.tsx`、`WebSite/src/components/ProjectLibrary.tsx` 三个完整源码文件，合计 10835 行，从每个文件第 1 行连续写入到末行。生成后用 `python-docx` 重新打开文档，逐行比对三个文件内容，确认连续匹配；同时检查独立省略占位数量为 0，并用 `unzip -t` 确认 docx 包结构正常。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
后续整理软著代码材料时，优先选择若干完整源码文件或连续页码区间，不要在函数体、类型定义、类定义和模块内部人工删减。校验时既要统计收录行数和文件连续性，也要专门检查独立省略占位；若源码语言自身有合法三点语法，应在材料说明或审核沟通中明确其不是省略占位。
|
||
|
||
## 2026-05-25-12-45-33 本地交付 docx 不应进入 Gitea 备份提交
|
||
|
||
A. 具体问题
|
||
|
||
用户明确要求不要将 `3. 代码汇总.docx` 做 Gitea commit，也不要推送该文件。此前本地 commit 尚未推送成功，但已经把 docx 纳入了本地待推送历史。
|
||
|
||
B. 产生问题原因
|
||
|
||
工作流默认要求对本次文档做 Git/Gitea 备份提交，而 `3. 代码汇总.docx` 是给用户本地交付的软著材料，不一定适合进入代码仓库。若只是不再推送而不修正未推送 commit，后续认证恢复后执行 `git push` 仍可能把该 docx 传到远程。
|
||
|
||
C. 解决问题方案
|
||
|
||
在远程推送失败且 commit 尚未进入 Gitea 的前提下，使用取消索引跟踪和 amend 的方式修正最后一个本地 commit：保留工作区里的 `3. 代码汇总.docx`，但从 Git 历史中移除。同步在 `.gitignore` 加入该文件名，避免后续 `git add .` 再次误提交。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
后续交付软著、合同、截图、压缩包等本地材料前，应先确认是否允许入库；如果用户要求不要提交或推送，应加入 `.gitignore` 或只保留在工作区。对已经生成但未推送的误提交，应优先修正未推送 commit，避免把敏感或本地交付材料带到 Gitea。
|
||
|
||
## 2026-05-25-12-48-00 代码汇总格式应避免额外行号和文件标题
|
||
|
||
A. 具体问题
|
||
|
||
用户要求 `3. 代码汇总.docx` 不需要每行最前方的行号编号，也不需要 `文件：XXX` 形式的文件标题。
|
||
|
||
B. 产生问题原因
|
||
|
||
上一版为了便于人工核对源码连续性，在 docx 中给每行增加了行号，并给每个完整源码文件增加了文件标题。该格式虽然便于审阅，但不符合用户希望直接呈现纯源码内容的材料样式。
|
||
|
||
C. 解决问题方案
|
||
|
||
重新生成本地 `3. 代码汇总.docx`，保留此前三个完整源码文件的连续内容，但写入段落时不再添加行号前缀，也不再插入 `文件：XXX` 标题。文件之间仅保留空行分隔。生成后用 `python-docx` 校验正文与源码逐行一致，`文件：` 文案数量为 0，行号前缀匹配数量为 0。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
整理软著代码汇总时，先确认用户要的是“带核对信息的审阅版”还是“纯源码版”。若目标是提交材料，默认减少额外说明、文件标题和行号，只保留源码文本；用于内部核对的行号应放在临时检查结果里，不直接写入最终 docx。
|
||
|
||
## 2026-05-25-13-42-13 自动匹配参数上限要前后端同步
|
||
|
||
A. 具体问题
|
||
|
||
用户要求自动微调匹配工作区“迭代轮次”最高变为 50 次。页面旧输入框最大值为 12，后端 `normalizeAutoMatchIterations` 也会把请求轮次截断到 12。
|
||
|
||
B. 产生问题原因
|
||
|
||
自动匹配的轮次上限同时存在于前端输入控件和后端请求归一化中。若只修改其中一侧，会出现界面可以输入但接口不执行，或接口支持但页面无法选择的状态。
|
||
|
||
C. 解决问题方案
|
||
|
||
将 `AutoMatchWorkspace.tsx` 中迭代轮次输入框的 `max` 和 `onChange` clamp 上限改为 50；同步将 `server.ts` 中 `normalizeAutoMatchIterations` 的服务端 clamp 上限改为 50。默认值仍保留 6，避免进入页面后默认运行变慢。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
后续调整自动匹配参数上限时，要同时检查前端控件、API 类型、服务端归一化、默认值和运行耗时提示。对可能显著增加耗时的参数，只提高上限不改变默认值；若用户常用高上限，应补充进度、取消和超时保护。
|
||
|
||
## 2026-05-25-14-00-24 项目导出包不应使用会暴露 PAX 头的 tar.gz
|
||
|
||
A. 具体问题
|
||
|
||
用户在 Windows 解压“导出项目及结果”压缩包时，只能看到 `entries`、`PaxHeaders` 和无扩展名编号文件，无法直接看到 JSON、分割类别映射和 `.nii.gz` 分割结果。同时分类分割导出的文件名带编号和 `-label` 后缀，不利于后续按类别处理。
|
||
|
||
B. 产生问题原因
|
||
|
||
旧导出包使用手写 tar.gz。tar 路径一旦包含中文项目名或较长路径，服务端会写入 PAX 扩展头；部分 Windows 解压工具会把 PAX 扩展头当成普通目录展示，并把真实文件显示成 `entries/000001` 之类的中转名。压缩包内部还额外套了项目名根目录，而下载文件名本身已经包含项目名。
|
||
|
||
C. 解决问题方案
|
||
|
||
将“项目及结果导出”改为 ZIP，包内不再套项目名根目录，固定输出 `manifest.json`、`pose/pose.json`、`segmentation/labels.json`、`segmentation/label.nii.gz` 或 `segmentation-parts/{类别名}.nii.gz`、`dicom/image.nii.gz`、`stl/{原文件名}`。前端下载改为 XHR blob 下载，接入顶部导出进度条。新增 `POST /api/reverse-pipeline`，支持上传 DICOM/STL、应用旋转/平移/缩放/镜像/轴向自动拉伸、可选自动匹配、可选导出、可选记录项目库和锁定。
|
||
|
||
D. 后续如何避免问题
|
||
|
||
面向 Windows 用户直接查看的复杂导出包优先使用 ZIP，不要用需要 PAX 扩展的 tar.gz；如果必须使用 tar.gz，必须避免非 ASCII 和长路径，或确认目标解压器正确隐藏 PAX。导出包内部结构应以机器可读和人工可读为准，分类分割文件名保持类别名，映射关系单独放入 `labels.json`。
|