NavisworksTransport/doc/design/Design_Plan.md

# NavisworksTransport 正式设计方案（Design Plan）

版本：v1.0  
作者：Agent Mode  
日期：2025-08-29

本方案依据以下输入编制：

- 需求文档：doc/requirement/user_requiement.md（以 Navisworks 2017/Windows 7 为基线）
- 项目上下文与结构参考：QWEN.md（包含 Navisworks 2026 的说明，仅作补充参考）
- 源代码：src 目录（核心模块：Core、PathPlanning、UI/WPF、Utils 等）

重要说明：如需求文档与 QWEN.md 在版本目标存在差异（2017 vs 2026），本方案默认以需求文档为准（Navisworks 2017）。若需面向 Navisworks 2026 的兼容性与增强功能，请在部署与验证环节中选配“2026 兼容模式”。

一、总体设计

1.1 背景与目标

- 背景：在 Autodesk Navisworks 环境中进行物流路径规划、动画仿真与碰撞检查，需高效的交互式工具，支持路径点编辑、自动路径规划（复杂场景）、导航输出与结构化结果文件（XML/JSON/CSV）。
- 目标：
  - 快速完成通道选择与路径点规划（起点/路径点/终点），支持多路径管理与编辑；
  - 支持模型切分与层级可见性管理，聚焦物流相关构件；
  - 支持物流“类别属性”批量设置、识别与筛选；
  - 集成动画和碰撞检测能力，支持结果导出和路径分析；
  - 支持结构化结果文件输出，并满足 DELMIA 导入（按需求文档约束）。

1.2 需求综述（与需求文档对应）

- 通道选择及路径点规划：模型切分、通道选择、路径点规划、多路径管理、编辑保存与导入、路径点自动贴合；
- 物流“类别”设置：新增物流属性类别、设置可通行性/速度/宽度/优先级等属性，筛选与清除；
- 层级创建与显示：自动隐藏/淡化非关键层，物流元素筛选，路径时间标签；
- 交互式导航：交互式导航控件、结果输出（视频或图片）、输出格式（XML/JSON/CSV，可导入 DELMIA）；
- 碰撞检查：动画生成与播放、碰撞检查/记录导出、路径规划分析与最优路径建议。

1.3 设计原则

- 实用优先：在 Navisworks 2017 环境中保证稳定运行与较好性能；
- 解耦分层：UI（WPF+MVVM）与核心逻辑（Core、PathPlanning）分离，便于后续扩展；
- 向后兼容：在自动规划/碰撞集成等关键能力上提供降级路径（如 BoundingBox 模式回退）；
- 可观察性：统一日志 LogManager，异常采用 GlobalExceptionHandler；
- 数据可移植：路径/结果提供 XML/JSON/CSV 序列化能力（JSON 加载简化，建议 XML 为主）。

1.4 核心用例流程概览

- 路径编辑（手动）：
  1) 用户通道选择（手动/属性筛选/自动查找可通行），计算通道边界；
  2) 进入编辑模式，3D 点击添加“起点/路径点/终点”，路线渲染与校验；
  3) 保存/导入/导出路径文件，维护历史记录；
- 自动路径规划：
  1) 依据通道与模型生成网格（优先 ChannelBased 2.5D，失败回退 BoundingBox）；
  2) A* 求解路径并高度修正（贴合通道表面），渲染与事件广播；
- 动画与碰撞：
  1) 基于路径生成 TimeLiner 动画；
  2) 动画过程缓存碰撞，结束后统一生成 Clash 测试与报告，高亮冲突对象；
- 导航输出：
  1) 导航控件交互产生路径；
  2) 输出视频/图片与结构化结果（XML/JSON/CSV），满足 DELMIA 导入约束。

二、系统架构

2.1 分层架构与模块

- UI 层（WPF + MVVM，少量 WinForms 遗留）：
  - Views: UI/WPF/Views/*（含 PathEditingView、AnimationControlView 等）
  - ViewModels: UI/WPF/ViewModels/*（LogisticsControlViewModel、PathEditingViewModel 等）
  - 主控面板：UI/WPF/LogisticsControlPanel.xaml
- Core 业务层：
  - PathPlanningManager：路径规划主控（事件驱动、状态机、路径可视化）
  - CategoryAttributeManager：物流属性管理（COM API + .NET API）
  - VisibilityManager：可见性与层级控制
  
  - Animation：TimeLinerIntegrationManager、PathAnimationManager（动画控制）
  - Collision：ClashDetectiveIntegration（碰撞集成，动画期缓存 + 结束时统一测试）
  - ModelSplitterManager：模型切分（含简化实现）
- PathPlanning 算法层：
  - GridMapGenerator：网格生成（ChannelBased 2.5D/BoundingBox），车辆膨胀优化
  - AutoPathFinder：A* 路径搜索、路径优化/插值、高度贴合
  - ChannelBasedGridBuilder、VerticalScanProcessor、TriangleSpatialHash 等支撑
- Utils：日志、坐标/单位转换、Navisworks API 辅助

2.2 系统架构图（截图占位）

- [截图占位] 系统架构图
  - 要求：体现 UI（WPF+MVVM）/Core/PathPlanning/Utils 分层，以及 TimeLiner、Clash 的集成位置与事件流（PathPlanningManager 事件：StatusChanged、EditStateChanged、RouteGenerated 等）。

2.3 模块关系与数据流

- UI 通过 ViewModel 调用 PathPlanningManager 与其他 Core 服务；
- PathPlanningManager 根据通道选择与编辑状态，驱动网格生成与 A* 求解，并渲染路径标记；
- Animation/Collision 订阅路径与动画状态，按批次创建 TimeLiner 任务与 Clash 测试；
- CategoryAttributeManager 负责属性新增/更新/移除与筛选；
- VisibilityManager 提供“仅显示物流元素/隔离显示”等能力。

2.4 技术路线与选型

- 语言/框架：C#，.NET Framework 4.8；
- UI：WPF + MVVM（WinForms 仅用于部分对话框/遗留界面）；
- 外部 API：Autodesk Navisworks API（2017 目标），COM API（属性写入）、TimeLiner API、Clash API；
- 路径算法：RoyT.AStar（格网 A*），自研 2.5D 高度约束与车辆膨胀优化；
- 序列化：XML（主）、JSON（简化加载）/CSV（结果）；
- 日志/异常：LogManager、GlobalExceptionHandler。

2.5 关键数据模型（摘自源码）

- PathPoint、PathRoute：路径点/路径集合，支持类型（Start/End/WayPoint）、长度/时间统计、XML/JSON 序列化；
- ChannelBounds：通道边界与 2D 投影；
- PathHistoryEntry/Manager：路径历史；
- 事件模型：PathPlanningStatusChangedEventArgs、PathEditStateChangedEventArgs、RouteGeneratedEventArgs 等。

三、功能设计方案（逐模块）

3.1 模型切分

- 目标：对大型模型按楼层/属性进行切分，提升性能与操作体验；
- UI：ModelSplitterDialog（WinForms）；
- Core：ModelSplitterManager、SimplifiedModelSplitterManager；
- 设计：
  - 基于模型层级与属性枚举进行分层导出；
  - 提供环境检查与测试导出入口；
  - 与可见性/筛选配合以限定工作区域。

3.2 通道选择

- 能力：
  - 手动选择：基于 Navisworks 选择；
  - 属性筛选：通过 CategoryAttributeManager.FilterByLogisticsType(FilterTraversableItems)；
  - 自动选择：Search API 扫描“可通行”物流元素；
- PathPlanningManager.SelectChannels：计算组合边界 CombinedChannelBounds 并事件广播。

3.3 路径点规划（手动 + 自动）

- 手动规划：
  - 工具：PathClickToolPlugin（精确拾取），PathPointRenderPlugin（3D 渲染）；
  - 流程：切换到 Creating/Editing 状态 -> 添加点 -> 渲染 -> 校验；
  - 路径点自动贴合：高度修正在 AutoPathFinder.ApplyPreciseHeightCorrection 中贴合通道表面（有通道数据时）；
- 自动规划（复杂环境）：
  - 网格生成：GridMapGenerator.GenerateFromBIM
    - First 尝试 ChannelBased2_5D（通道优先、垂直扫描高度区间、车辆高度校验）；
    - Fallback 到 BoundingBox 模式（保持向后兼容）；
  - A*：AutoPathFinder.FindPath/ExecuteAStarAlgorithm
    - 路径优化（去冗余点、直线可达校验）、2.5D 高度插值与起终点原位修正；

3.4 路径管理、编辑、保存与导入

- 编辑：创建/编辑/取消/完成编辑（FinishEditing 自动将末点设为终点并触发渲染与事件）；
- 文件：PathFileSerializer（XML 主，JSON 简化，不建议作为主格式），支持多路径容器；
- 历史：PathHistoryManager（Created/Edited/ManualSave 等），提供查看历史 UI；
- 导入：DetectFileFormat -> LoadFromXml/LoadFromJson（JSON 加载简化，优先 XML）。

3.5 物流“类别”设置

- 类别：为模型添加“物流属性”类别（类型、可通行、优先级、车辆尺寸、速度限制、宽度限制等）；
- 批量处理：Add/Update/Remove，使用 COM API 正确索引方式避免覆盖错误；
- 识别筛选：FilterTraversableItems/FilterByLogisticsType/FilterPassableAreas，供通道选择与可见性使用。

3.6 层级创建与显示

- 隐藏/淡化非关键层：VisibilityManager.HideNonLogisticsItems/ShowAllItems/IsolateSpecificItems；
- 物流元素筛选：ShowLogisticsItemsOnly；
- 路径时间标签：在 PathPlanningManager.CalculateEstimatedTime（当前简单估算，后续可接入速度限制）。

3.7 交互式导航

- 交互控件：UI/WPF 侧的主面板与路径/起终点选择；
- 导出：支持视频/图片占位（由用户录屏或快照）、结构化文件（XML/JSON/CSV）；
- DELMIA 导入：以 XML/CSV 为主，JSON 仅作参考（需要与 DELMIA 侧字段约定）。

3.8 动画生成与播放

- TimeLinerIntegrationManager：创建运输任务（将路径关联到对象）、更新进度与状态文本、清理任务；
- PathAnimationManager：具体的路径关键帧/移动输出（见 Core/Animation）；
- 设计要点：
  - 以 TimelinerTask 为主线（Navisworks 2017 可用 API 能力有限，使用显示名/选择集传递状态）。

3.9 碰撞检查

- ClashDetectiveIntegration：
  - 动画过程“实时缓存”碰撞（包围盒快速判定 + 去重 + 位置快照）；
  - 动画结束“统一创建并运行”测试（避免过程频繁创建）；
  - 高亮冲突对象、刷新 UI、导出报告；
- 兼容性：优先 .NET Clash API，必要时绕过繁重的 COM 插件枚举。

3.10 路径规划分析

- 汇总多条路径的碰撞结果，统计次数/距离/受影响对象；
- 以“最小碰撞/最短距离/最小转弯次数”等指标推荐最优路径；
- 输出分析报告（可选 CSV/XML）。

3.11 结果输出

- 地图/路径可视化：3D 渲染 + 可截屏；
- 结构化结果：XML/JSON/CSV（建议 XML/CSV 作为主导入格式到 DELMIA）。

四、系统部署方案

4.1 部署环境要求

- 操作系统：Windows 7（需求文档基准），建议 Windows 10 及以上（更佳兼容性与性能）；
- Autodesk Navisworks：Manage 2017（需求基线）。如需 2026，请切换引用与验证用例（见下文兼容模式）；
- .NET Framework：4.8；
- 开发工具：Visual Studio（建议 2019/2022）。

4.2 构建与产物

- 解决方案：NavisworksTransport.sln；
- 项目：NavisworksTransportPlugin.csproj；
- 产物：NavisworksTransportPlugin.dll（bin/Debug 或 bin/Release）。

4.3 安装与部署流程

- 自动安装（一键安装）：
  1) 识别 Navisworks 安装目录；
  2) 将插件 DLL 与必要资源复制到 [Navisworks安装路径]\Plugins\NavisworksTransportPlugin\；
  3) 注册菜单/配置（如需）；
- 手动安装：
  1) 复制 NavisworksTransportPlugin.dll 至上述目录；
  2) 重启 Navisworks，在“附加模块”中查看“物流路径规划”。

4.4 运行配置

- 日志输出：%AppData%\Autodesk Navisworks Manage 2017\PluginsData\NavisworksTransportPlugin（按 QWEN 中 2026 路径作适配）；
- 配置切换：
  - 自动路径规划模式网格参数（cellSize、vehicleSize、safetyMargin、vehicleHeight）；
  - 2.5D/BoundingBox 模式选择（自动/强制选项）。

4.5 验证计划

- 功能验证（最小可行用例）：
  - 通道选择（手动/自动），边界计算；
  - 路径编辑：起点/若干路径点/终点，渲染正确；
  - 路径保存/导入/导出（XML 主）、历史记录查看；
  - 物流属性设置：批量标注、筛选/清除、颜色高亮检查；
  - 层级显示：仅显示物流元素/隔离显示/恢复显示；
  - 自动规划：A* 成功求解、路径高度贴合、优化去冗余；
  - 动画：任务创建、播放/停止、进度状态变更；
  - 碰撞：动画期缓存、结束后创建测试与高亮、导出记录；
  - 导航输出：视频/图片占位与结构化结果（XML/CSV）；
- 性能验证：
  - 大模型下网格生成耗时（ChannelBased 2.5D 与 BoundingBox 比对）；
  - 车辆膨胀优化（距离变换算法）前后对比；
  - PathPoint 渲染与状态事件对 UI 延迟的影响；
- 兼容性验证：
  - Navisworks NWD/NWF/NWC 模型；
  - 不同单位（mm/cm/m/ft/in）下的单位换算正确性；
  - 如需 Navisworks 2026，切换引用并复测 TimeLiner/Clash API 行为差异。

4.6 2026 兼容模式（可选）

- 若目标为 Navisworks 2026：
  - 切换引用到 2026 API；
  - 复核 QWEN.md 所述运行路径与日志输出位置；
  - 回归 TimeLiner 与 Clash API 可用性和接口差异；
  - 扩展安装器适配多版本并行安装。

五、非功能与质量保证

5.1 日志与异常处理

- GlobalExceptionHandler：应用级异常捕获（线程/任务/未处理），尝试恢复组件，提供用户友好提示；
- LogManager：Info/Warning/Error/Debug 统一记录，关键路径设充分日志（网格生成、A*、碰撞快照）。

5.2 性能优化要点

- 网格生成：
  - ChannelBased 2.5D 优先（垂直扫描、空间哈希、通道优先），失败回退 BoundingBox；
  - 车辆膨胀：距离变换 O(n*m) 优化，跳过无障碍场景；
- UI：
  - UIStateManager/QueueUIUpdate 降低 UI 阻塞；
  - WPF 绑定优化与虚拟化集合；
- 搜索：
  - Search API 替代全量遍历，尤其在通道/楼层检索时。

5.3 可维护性

- 分层清晰，事件驱动，保留向后兼容事件（_Legacy）；
- 路径文件以 XML 为主，便于第三方集成；
- 关键类职责单一（PathPlanningManager/CategoryAttributeManager/GridMapGenerator 等）。

六、风险与边界

- Navisworks 版本差异：2017 与 2026 API 行为差异需要回归验证；
- JSON 加载功能简化：建议以 XML 为主格式；
- 大场景极大网格：需调大 cellSize 或范围裁剪以避免内存/耗时过大；
- COM 属性写入：需严格使用相对索引覆盖逻辑（源码已修复），防止属性覆盖错乱；
- 动画碰撞“位置恢复”：测试期间会短暂移动对象做验证，并在结束后恢复。

七、里程碑建议（示例）

- M1（1 周）：路径编辑闭环（手动）、物流属性标注、可见性隔离；
- M2（1-2 周）：自动路径（2.5D/回退）、XML 存取、历史；
- M3（1 周）：动画与碰撞缓存 + 结束测试、报告与高亮；
- M4（1 周）：导航输出与 DELMIA 结果结构；
- M5（1 周）：性能与兼容性回归（2017 基线，若选 2026 追加一轮）。

八、截图占位与要求

- [截图占位] 系统架构图：
  - 要求：展示 UI/Core/PathPlanning/Utils 分层与 TimeLiner/Clash 集成及事件流；
- [截图占位] 主停靠面板（WPF）：
  - 要求：展示“类别设置/路径编辑/检测动画/系统管理”四个页签；
- [截图占位] 路径编辑过程：
  - 要求：3D 视图中路径点（起点/路径点/终点）与线段渲染、状态提示；
- [截图占位] 自动路径规划网格示意：
  - 要求：对比 ChannelBased 2.5D 与 BoundingBox 的可通行网格差异；
- [截图占位] TimeLiner 任务与播放控制：
  - 要求：任务创建、播放、进度显示；
- [截图占位] 碰撞检查结果：
  - 要求：高亮冲突对象、Clash 测试列表与数量统计；
- [截图占位] 结果文件样例：
  - 要求：XML/CSV 字段示意，可用于 DELMIA 导入对齐。

附录 A：代码与模块清单（节选）

- Core/MainPlugin、UI/WPF/LogisticsControlPanel.xaml：主入口与面板；
- Core/PathPlanningManager：路径规划主控（状态、事件、可视化、导入导出）
- PathPlanning/GridMapGenerator、AutoPathFinder：网格生成与 A* 路径；
- Core/Properties/CategoryAttributeManager：物流属性管理（COM API 正确索引覆盖）；
- Core/Animation/TimeLinerIntegrationManager：TimeLiner 任务集成；
- Core/Collision/ClashDetectiveIntegration：动画期缓存 + 结束创建测试；
- Core/VisibilityManager：可见性隔离与统计；
- UI/WPF/ViewModels/*：MVVM 视图模型与命令绑定。