# NavisworksTransport 项目上下文 (QWEN.md)

## 项目概述

NavisworksTransport 是一个针对 Autodesk Navisworks Manage 2026 开发的插件。其核心目标是简化在 Navisworks 环境中进行物流路径规划、动画仿真和碰撞检测的工作流程。

该插件旨在通过自动化 Animator 动画创建、Clash Detective 碰撞测试配置与运行，并提供直观的图形化碰撞结果显示，大大提高工作效率，为用户提供一个快速验证施工物流和设备移动可行性的工具。

### 核心功能

1. **类别属性分配**：
    * 为模型项目添加预定义的物流类别属性（门、电梯、楼梯、通道、障碍物、装卸区、停车位、检查点）。
    * 支持批量处理和用户友好的界面（按钮式对话框）。
    * 通过 Navisworks COM API 确保属性正确添加。

2. **路径规划与编辑**：
    * 允许用户在3D视图中交互式地定义移动对象的路径点。
    * 管理多条路径，支持路径的创建、编辑、删除、导入、导出和历史记录。
    * 提供路径可视化（3D标记）和基础验证（如点数、长度）。

3. **动画仿真**：
    * 集成 Navisworks Timeliner API，根据规划的路径自动创建对象动画。
    * 提供动画控制界面，允许用户设置播放速度、持续时间、帧率、循环等参数。

4. **碰撞检测**：
    * 集成 Navisworks Clash API，自动配置并运行基于路径动画的动态碰撞测试。
    * 提供碰撞检测状态和摘要信息。

5. **可见性控制**：
    * 提供模型分层拆分和仅显示物流相关元素的功能，以优化视图和性能。

6. **用户界面**：
    * 通过 Navisworks 的 Ribbon 界面添加自定义按钮启动插件。
    * 提供一个停靠窗格 (DockPane) 作为主控制面板，使用 WPF 构建。
    * 控制面板包含多个 Tab 页：类别设置、路径编辑、检测动画、系统管理。

## 技术架构

### 编程语言与框架

* **语言**: C#
* **框架**: .NET Framework 4.8
* **UI框架**: Windows Forms (部分遗留) 和 Windows Presentation Foundation (WPF)
* **API**: Autodesk Navisworks API (包括 COM API, Timeliner API, Clash API)

### 项目结构

```
NavisworksTransportPlugin/
├── src/
│   ├── Core/                  # 核心业务逻辑
│   │   ├── Animation/         # 动画管理 (LogisticsAnimationManager, TimeLinerIntegrationManager)
│   │   ├── Collision/         # 碰撞检测 (ClashDetectiveIntegration)
│   │   ├── Properties/        # 属性管理 (CategoryAttributeManager)
│   │   ├── MainPlugin.cs      # 插件主入口和旧版UI
│   │   ├── PathPlanningManager.cs # 路径规划核心逻辑
│   │   ├── PathPlanningModels.cs # 路径数据模型
│   │   ├── VisibilityManager.cs # 可见性控制
│   │   └── ...                # 其他核心组件
│   ├── UI/
│   │   └── WPF/               # 新版WPF UI
│   │       ├── ViewModels/    # MVVM ViewModels
│   │       ├── Views/         # MVVM Views (UserControls)
│   │       ├── LogisticsControlPanel.xaml # 主停靠面板
│   │       └── ...
│   ├── Utils/                 # 工具类 (日志、几何、坐标转换等)
│   └── Legacy/                # 为兼容性保留的旧代码
├── Properties/
│   └── AssemblyInfo.cs
├── NavisworksTransportPlugin.csproj # 项目文件
└── ...
```

### 核心组件

1. **`MainPlugin` (`MainPlugin.cs`)**:
    * 插件的入口点，继承自 `Autodesk.Navisworks.Api.Plugins.DockPanePlugin`。
    * 负责初始化插件、创建和管理主停靠窗格。
    * 包含旧版的 Windows Forms UI 逻辑（已部分迁移到 WPF）。

2. **`LogisticsControlPanel` (`LogisticsControlPanel.xaml`, `LogisticsControlPanel.xaml.cs`)**:
    * WPF 用户控件，作为主停靠窗格的内容。
    * 使用 MVVM 模式，通过 `DataContext` 绑定到 `LogisticsControlViewModel`。

3. **`LogisticsControlViewModel` (`LogisticsControlViewModel.cs`)**:
    * WPF UI 的核心逻辑处理中心。
    * 管理 UI 状态、数据绑定、用户命令（ICommand）。
    * 与 Core 层（如 `PathPlanningManager`）交互，驱动业务逻辑。

4. **`PathPlanningManager` (`PathPlanningManager.cs`)**:
    * 路径规划的核心业务逻辑。
    * 管理路径 (`PathRoute`) 和路径点 (`PathPoint`) 的创建、编辑、验证。
    * 管理路径编辑状态（查看、创建、编辑）。
    * 处理与 Navisworks 模型的交互（选择、边界计算）。
    * 提供事件供 UI 层订阅。

5. **`CategoryAttributeManager` (`CategoryAttributeManager.cs`)**:
    * 负责通过 Navisworks COM API 为模型项添加、更新、删除自定义物流属性。
    * 定义了物流类别 (`LogisticsCategories`) 和属性 (`LogisticsProperties`)。
    * 提供了筛选模型项的方法。

6. **`LogisticsAnimationManager`, `TimeLinerIntegrationManager`**:
    * 负责与 Navisworks Timeliner 集成，根据路径数据创建动画。

7. **`ClashDetectiveIntegration`**:
    * 负责与 Navisworks Clash Detective 集成，配置和运行碰撞测试。

8. **`VisibilityManager`**:
    * 管理模型元素的可见性，实现"仅显示物流元素"等功能。

9. **`LogManager`**:
    * 统一日志管理工具。

## 开发与构建

### 系统要求

* Windows 10 或更高版本
* Navisworks Manage 2026
* .NET Framework 4.8
* Visual Studio (推荐)

### 构建过程

1. 使用 Visual Studio 打开 `NavisworksTransport.sln` 解决方案文件。
2. 确保项目引用指向正确的 Navisworks 2026 API DLL 文件（路径在 `.csproj` 文件中定义）。
3. 选择 "Debug" 或 "Release" 配置。
4. 构建项目 (`Ctrl+Shift+B`)。
5. 输出文件为 `NavisworksTransportPlugin.dll`，位于 `bin\Debug\` 或 `bin\Release\` 目录下。

### 部署与安装

1. 编译生成 `NavisworksTransportPlugin.dll`。
2. 插件会自动安装到 Navisworks 插件目录：
    `[Navisworks安装路径]\Plugins\NavisworksTransportPlugin\`
3. 重启 Navisworks 即可在 "附加模块" 选项卡中找到插件。

### 运行与调试

* 在 Visual Studio 中可以直接调试插件，方法是设置 Navisworks 可执行文件（如 `NwAddinDev.exe` 或 `Navisworks.exe`）为启动外部程序。
* 插件运行时会在 `%AppData%\Autodesk Navisworks Manage 2026\PluginsData\NavisworksTransportPlugin` 目录下生成日志文件。

## 开发约定与实践

* **MVVM 模式**: 新的 UI 开发强烈推荐使用 WPF 和 MVVM 模式，将 UI 逻辑 (`ViewModel`) 与 UI 呈现 (`View`) 分离。
* **全局异常处理**: 使用 `GlobalExceptionHandler` 类来捕获和处理未处理的异常，提供用户友好的错误提示。
* **日志记录**: 使用 `LogManager` 进行统一的日志记录，便于调试和问题追踪。
* **安全执行**: 关键操作包装在 `GlobalExceptionHandler.SafeExecute` 方法中，以提高稳定性。
* **COM API 使用**: 在需要与 Navisworks 属性系统深度交互时，谨慎使用 COM API，并注意处理缓存和刷新问题。