# CLAUDE.md

NavisworksTransport - Navisworks 2026 物流路径规划插件 (A* 算法、碰撞检测、动画)

**环境**: Windows 10+, .NET Framework 4.8, C# 7.3

**原则**: 专注 2026，不考虑向后兼容

## 编译与测试

```bash
./compile.bat  # 必须用 ./ 前缀

# 单元测试
powershell -Command "& 'C:\...\MSBuild.exe' AStarTestRunner.csproj /p:Configuration=Debug /p:Platform=AnyCPU"
bin\Debug\AStarTestRunner.exe
```

**调试**: 日志在 `"C:\ProgramData\Autodesk\Navisworks Manage 2026\plugins\NavisworksTransportPlugin\logs\debug.log"`

## 架构

### 插件类型

- **MainPlugin.cs**: AddInPlugin - Ribbon UI + 停靠面板
- **PathClickToolPlugin.cs**: ToolPlugin - 3D 鼠标交互
- **PathPointRenderPlugin.cs**: RenderPlugin - 3D 可视化

### 核心管理器

- PathPlanningManager - A* 路径规划
- LogisticsAnimationManager - 动画系统
- TimeLinerIntegrationManager - TimeLiner 集成
- CategoryAttributeManager - COM API 属性持久化
- VisibilityManager - 图层控制
- ModelSplitterManager - 模型导出

### 数据层

- PathPlanningModels - 事件驱动状态管理
- PathDataManager - JSON 序列化
- CoordinateConverter - 2D↔3D 坐标转换
- GeometryExtractor - 空间分析
- FloorDetector - 楼层检测

### UI

- WPF (MVVM): `src\UI\WPF\` - LogisticsControlPanel
- WinForms: 遗留对话框
- ElementHost 嵌入

## ⚠️ 模型单位系统 - 极其重要

**核心**: 网格地图和路径规划**统一使用模型单位**，不用米制。大量 bug 源于混淆单位。

### 转换原则

```csharp
// ✅ 函数入口一次性转换
public GridMap GenerateFromBIM(BoundingBox3D bounds, double cellSize, ...)
{
    double factor = UnitsConverter.GetMetersToUnitsConversionFactor(Application.ActiveDocument.Units);
    double cellSizeInModelUnits = cellSize * factor;
    // 之后全用模型单位
}

// ❌ 计算中混用单位
```

### 必须使用模型单位

GridMapGenerator 和 AutoPathFinder 中所有参数：CellSize, VehicleRadius, SafetyMargin, VehicleHeight, ScanHeight, InflationRadius, MaxHeightDiff

### 命名约定

- 米制: `xxxMeters` (如 `cellSizeMeters`)
- 模型单位: `xxxInModelUnits` (如 `cellSizeInModelUnits`)
- 转换系数: `metersToModelUnitsConversionFactor`

### 常见错误

```csharp
// ❌ 直接用米制常量
private const double MAX_HEIGHT_DIFF = 0.35; // 米！
if (heightDiff > MAX_HEIGHT_DIFF) // Bug!

// ✅ 转换后用
private const double MAX_HEIGHT_DIFF_METERS = 0.35;
double maxHeightDiffInModelUnits = MAX_HEIGHT_DIFF_METERS * factor;

// ❌ 循环中重复转换
for (...) { double v = x * UnitsConverter.Get...(); }

// ✅ 提前转换
double factor = UnitsConverter.Get...();
double v = x * factor;
for (...) { /* 用 v */ }
```

### API 约定

```csharp
BoundingBox3D bbox = modelItem.BoundingBox(); // 模型单位
Point3D worldPos = gridMap.GridToWorld3D(gridPos); // 模型单位

double cellSize = 0.5; // 米，需转换
```

### 日志规范

```csharp
// ✅ 标注单位
LogManager.Info($"网格: {cellSize}米 → {cellSizeInModelUnits:F2}模型单位");
```

**违反导致**: 路径失败、碰撞错误、网格异常

### 其他关键点

- **网格坐标**: 网格单元**左下角**，非中心
- **坐标转换**: 多层系统支持 2D→3D

## Navisworks API

### 双 API 策略

- Native API (`Autodesk.Navisworks.Api`) - 核心功能
- COM API (`Autodesk.Navisworks.ComApi`) - 属性持久化、TimeLiner

### 插件注册

```csharp
[Plugin("NavisworksTransport.MainPlugin", "YourDeveloperID")]
[AddInPlugin(AddInLocation.AddIn)]
public class MainPlugin : AddInPlugin { }
```

### 关键点

- GlobalExceptionHandler - MainPlugin 构造函数初始化
- UI 操作必须编组到主线程
- 实现前查阅 `doc\navisworks_api\`

## 核心系统

### 路径规划

- A*: RoyT.AStar 库
- 动画: Transform + 碰撞检测
- TimeLiner: 自定义动画同步
- 实时碰撞: ClashDetectiveIntegration

### 状态管理

- PathEditState: None, AddingPoints, EditingPath
- JSON 持久化 + LogisticsAttributeChangedEventArgs

### 物流分类

门、电梯、楼梯、通道、障碍物、装卸区、停车区、检查点

### 包管理

- 旧式 csproj: `<Reference Include>` + HintPath
- packages.config 手动管理 (**不用** `dotnet add package`)
- 路径: `packages\{PackageId}.{Version}\lib\{TargetFramework}\{Assembly}.dll`

## 开发原则

### 防御性编程

- ✅ 检测异常报错，让问题暴露
- ❌ 默认值掩盖问题

### 容错处理

- ✅ 错误日志 + 中断流程
- ❌ 自动"修复"继续执行

### 核心优先级

1. 快速暴露 > 看起来正常
2. 报错 > 静默失败
3. 数据一致性 > 宽松验证
4. 最小化修改 > 复杂逻辑

## API 文档查询

### CHM 搜索策略

```bash
# 类成员列表入口
AllMembers_T_Autodesk_Navisworks_Api_ClassName.htm

# 精确搜索
find . -name "*ClassName*" -o -name "*MethodName*"
grep -r "SaveFile\|Export.*nwd" --include="*.htm" doc/navisworks_api/
```

**常用路径**:

- Document: `AllMembers_T_Autodesk_Navisworks_Api_Document.htm`
- TimeLiner: `AllMembers_T_Autodesk_Navisworks_Api_Timeliner_*.htm`
- 插件基类: `AllMembers_T_Autodesk_Navisworks_Api_Plugins_*.htm`

**避免**: HTML 内容模糊搜索、GUID 文件名、宽泛搜索词

## 工作流程

- 使用中文交流和注释
- Agent 任务前 Plan 模式设计方案
- `src\Legacy\` 仅参考，不维护