NavisworksTransport/doc/bugfixes/数据库兼容性_剖面盒导出修复报告.md

数据库兼容性 / 剖面盒导出修复报告

修复目标

1. 打开旧版本数据库时崩溃（schema 不兼容）
2. NWF 多文档剖面盒导出时，无命中子树泄露到导出文件
3. 反复剖面盒导出后崩溃（COM 跨线程访问）
4. 导出后剖面盒被关闭，状态栏按钮不同步

---

问题一：数据库 schema 不兼容导致启动崩溃

现象

打开带有旧版本 .db 文件的模型时，插件初始化报错：

SQL logic error: no such column: DetectionRecordId

根因

CreateTables() 使用 CREATE TABLE IF NOT EXISTS + CREATE INDEX IF NOT EXISTS 组合。旧数据库表已存在但 schema 是旧版（缺 DetectionRecordId 列），CREATE TABLE IF NOT EXISTS 静默跳过，紧随的 CREATE INDEX ... ON ...(DetectionRecordId) 直接炸。

同时 PathDatabase.InitializeDatabase() 还有以下问题：

• PRAGMA user_version 只写入、从未读取
• CreateTables() 无异常保护
• BatchQueueItems 的 ALTER TABLE ADD COLUMN 用裸 try-catch 吞异常
• PathPlanningManager.DatabaseInitialize() 的 catch 里 throw; 导致同一错误双重日志

修复

PathDatabase.cs：

• 新增 SafeCreateIndex() 方法：建索引前用 PRAGMA table_info 检查列是否存在，缺列记 warning 跳过，不崩
• 新增 EnsureColumnExists() 方法：用 PRAGMA table_info 检查列，缺了才 ALTER TABLE ADD COLUMN，不吞其他异常
• 删除无用的 PRAGMA user_version 写入
• InitializeDatabase() 内用 try-catch 包裹 CreateTables() + EnsurePathRoutesTableExtended()，失败时关闭连接
• 清理注释中重复/杂乱的编号
• CollisionDetectionRecords 建表处加外键依赖注释

PathPlanningManager.cs：

• 去掉 catch 后的 throw;，外层 OnModelsCollectionChanged 已有独立日志

---

问题二：NWF 多文档剖面盒导出时空白子树泄露

现象

NWF 文件引用多个 NWD（各为一个独立 Model），剖面盒只覆盖其中一个子树的元素，导出后其他平行子树仍然出现在 NWD 中。

根因

SectionBoxExporter.CalculateHiddenItems() 通过"兄弟节点算法"确定隐藏项：收集可见项（剖面盒内元素及其祖先）的父节点，隐藏同父节点下的不可见兄弟。当模型有多个平行 RootItem（来自不同 Model）时，完全空白的子树没有任何节点进入 visibleSet，其 RootItem 不会出现在 uniqueParents 中，整棵子树被遗漏。

修复

SectionBoxExporter.GetObjectsAndHiddenItems()： 在 CalculateHiddenItems() 之后补一步——遍历所有 document.Models 的 RootItem，不在 visibleSet 中的直接加入 ItemsToHide。SetHidden 会级联隐藏所有后代，无需递归。

---

问题三：反复剖面盒导出崩溃

现象

连续多次"设置剖面盒 → 导出"操作，前几次正常，后续某次崩溃（无 managed 异常日志）。

根因

LayerManagementViewModel 中有两处不必要的 await Task.Run()：

• GetObjectsAndHiddenItems() 被包在 Task.Run 中，在后台线程调用 Navisworks COM API（Model.HasGeometry、BoundingBox() 等）
• NwdExportHelper.ExportToNwdWithPrecomputedHiddenItems() 同样被包在 Task.Run 中

Navisworks COM API 要求 STA 线程访问，跨线程调用在少量使用时不崩，多次使用后触发 STA 违规导致进程崩溃。

修复

LayerManagementViewModel.cs：

• 去掉 GetObjectsAndHiddenItems 外的 await Task.Run() 包装，直接在 UI 线程调用
• 去掉 ExportToNwdWithPrecomputedHiddenItems 外的 await Task.Run() 包装，该方法内部已有 Dispatcher.Invoke，无需外层再切换线程

---

涉及文件

文件	改动
src/Core/PathDatabase.cs	新增 SafeCreateIndex、EnsureColumnExists；InitializeDatabase 加 try-catch；删除 user_version；清理注释
src/Core/PathPlanningManager.cs	去掉 DatabaseInitialize catch 中的 re-throw
src/Core/SectionBoxExporter.cs	GetObjectsAndHiddenItems 补空白 RootItem 隐藏逻辑
src/Utils/NwdExportHelper.cs	调试日志（已清理）
src/Utils/VisibilityHelper.cs	调试日志（已清理）
src/UI/WPF/ViewModels/LayerManagementViewModel.cs	去掉两处 Task.Run
deploy-plugin.bat	powershell → pwsh（兼容环境）
AGENTS.md	补充编译/部署调用方式说明
src/Utils/SectionClipHelper.cs	新增 RestoreClipBox 公开方法

---

问题四：导出后剖面盒被关闭，状态栏按钮不同步

现象

导出剖面盒后，Navisworks ExportToNwd 内部会关闭剖分功能，但状态栏两个剖面盒图标按钮仍保持激活状态。

根因

ExportToNwd 是 Navisworks 内部行为，绕过我们的 SetClipBoxState。ViewModel 的 IsClipBoxEnabled/IsSelectionClipBoxEnabled 未感知到变化。

修复

VisibilityHelper.ExecuteWithPrecomputedHiddenItems： 导出前用 SectionClipHelper.IsClipBoxEnabled + TryGetCurrentClipBox 保存剖面盒状态，导出后检查并在被关闭时恢复。

SectionClipHelper： 新增 RestoreClipBox(BoundingBox3D) 公开方法。