NavisworksTransport/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

NavisworksTransport is a Navisworks 2026 plugin for logistics path planning and transportation conflict detection in 3D building models. The plugin supports route optimization, collision detection, and animated object movement along defined paths.

**Current Status**: Navisworks 2026 exclusive development - no legacy 2017 compatibility required. Leverages 2026-specific features for enhanced animation and A* pathfinding capabilities.

## Build Commands

### 标准编译方式 (Windows)

- **推荐编译命令**: `./compile.bat` - 在项目根目录下运行的标准方式
- **重要说明**: 在Windows系统下必须使用 `./` 前缀来运行批处理文件，不要使用 `cmd /c compile.bat` 或其他复杂方式

## Architecture Overview

### Dual Plugin Architecture

The system implements multiple Navisworks plugin types working together:

- **MainPlugin.cs**: Primary AddInPlugin with ribbon UI and DockPanePlugin integration  
- **PathClickToolPlugin.cs**: ToolPlugin for 3D mouse interaction and point placement
- **PathPointRenderPlugin.cs**: RenderPlugin for 3D visualization overlay

### Core Management Layer

- **PathPlanningManager.cs**: Central coordinator for route planning with A* pathfinding support
- **LogisticsAnimationManager.cs**: Enhanced animation system targeting Navisworks 2026 native components
- **TimeLinerIntegrationManager.cs**: Bridge between custom animations and Navisworks TimeLiner
- **CategoryAttributeManager.cs**: COM API wrapper for persistent logistics attribute management
- **VisibilityManager.cs**: Model layer control and filtering
- **ModelSplitterManager.cs**: Model export and layer separation

### Data and Coordinate Systems

- **PathPlanningModels.cs**: Core data structures with event-driven state management
- **PathDataManager.cs**: JSON serialization with migration support
- **CoordinateConverter.cs**: 2D map overlay to 3D world coordinate transformation chains
- **GeometryExtractor.cs**: Spatial analysis and bounding box calculations
- **FloorDetector.cs**: Automatic floor/level detection for multi-story logistics

### UI Architecture: WPF + WinForms Hybrid

- **WPF Components**: Modern MVVM-based controls in `src\UI\WPF\`
  - LogisticsControlPanel: Main docked interface
  - ViewModels with INotifyPropertyChanged pattern
  - Separated Views for different functional areas
- **WinForms Dialogs**: Legacy property editing interfaces
- **Integration**: ElementHost for WPF in Navisworks environment

## Key Technical Details

### Navisworks API Integration Pattern

- **Dual API Strategy**: Native API (`Autodesk.Navisworks.Api`) for core functionality + COM API (`Autodesk.Navisworks.ComApi`) for attribute persistence and TimeLiner operations
- **Plugin Architecture**: Three distinct plugin types registered in single assembly
- **Event-Driven Design**: Global exception handling with `GlobalExceptionHandler` class
- **Navisworks 2026 Focus**: Utilizes 2026-specific API features without backward compatibility constraints

### Pathfinding and Animation System

- **A* Algorithm**: RoyT.AStar library integration for optimal path calculation
- **Animation Pipeline**: Transform-based movement with collision detection integration
- **TimeLiner Bridge**: Synchronization between custom path animations and Navisworks timeline
- **Real-time Collision**: ClashDetectiveIntegration for dynamic conflict detection during animation

### State Management and Persistence

- **Session State**: PathEditState enum (None, AddingPoints, EditingPath) with event callbacks
- **Data Serialization**: JSON-based persistence with LogisticsAttributeChangedEventArgs for tracking
- **Coordinate Mapping**: Multi-layer coordinate system supporting 2D overlay on 3D models

### Logistics Classification System

Eight predefined categories with inheritance from parent to child nodes:

- 门 (Doors), 电梯 (Elevators), 楼梯 (Stairs), 通道 (Channels)  
- 障碍物 (Obstacles), 装卸区 (Loading Zones), 停车区 (Parking), 检查点 (Checkpoints)

## Development Guidelines

### Claude Code Work Delegation Principle

- **任何具体的开发工作，全部让子代理完成** - All concrete development work must be delegated to specialized sub-agents
- Claude Code主要负责需求理解、任务分解和工作协调，不直接进行代码编写
- 使用专业子代理处理具体实现：`navisworks-feature-developer`、`navisworks-api-researcher`、`navisworks-ui-designer`、`technical-architect`、`project-task-manager`

### Language and Communication

- **使用中文进行所有交流和代码注释** - Primary language for user interaction and code documentation
- 代码注释和文档说明使用中文 - All technical documentation in Chinese

### Package Management (Legacy Format)

- **Old-style csproj**: Uses `<Reference Include>` with HintPath instead of PackageReference
- **packages.config**: Manual NuGet package management (do NOT use `dotnet add package`)
- **Manual package installation**: Download .nupkg files and extract to packages/ directory
- **Path format**: `packages\{PackageId}.{Version}\lib\{TargetFramework}\{Assembly}.dll`

### Plugin Registration Patterns

```csharp
// Multi-plugin registration in single assembly
[Plugin("NavisworksTransport.MainPlugin", "YourDeveloperID")]
[AddInPlugin(AddInLocation.AddIn)]
public class MainPlugin : AddInPlugin { }

[Plugin("NavisworksTransport.PathClickTool", "YourDeveloperID")]  
[ToolPluginAttribute("NavisworksTransport.PathClickTool", "YourDeveloperID")]
public class PathClickToolPlugin : ToolPlugin { }
```

### Development Principles

- **不考虑向后兼容性**: 直接修改现有代码逻辑，无需保持向后兼容性，专注于解决当前问题和改进现有功能
- **最小化修改原则**: 进行任何代码修改时，必须遵循最小化原则，只修改必要的部分，不添加额外的功能或逻辑，以确保问题能够清晰暴露和定位

### Critical API Usage Patterns

- **Always reference Navisworks API documentation**: Check `doc\navisworks_api\` before implementing any Navisworks functionality
- **COM API for persistence**: Use COM API for attribute operations that need to persist across sessions
- **GlobalExceptionHandler**: Initialize in MainPlugin constructor for application-wide error handling
- **Thread safety**: UI operations must be marshaled to main thread when called from background processes

### Navisworks 2026 Development Focus

- **Exclusive 2026 targeting**: No backward compatibility required - leverage 2026-specific features freely
- **Legacy artifacts**: `src\Legacy\` contains reference code from 2017 version but is not actively maintained
- **Modern animation system**: Use Navisworks 2026 native animation components instead of manual Transform manipulation
- **Enhanced APIs**: Take advantage of improved 2026 APIs for collision detection, animation, and model management

## API Documentation Search Strategy

### CHM文档搜索最佳实践

**问题**：CHM解压后产生大量HTML文件（数千个），标准搜索工具效果有限

**解决策略**：

1. **使用文档结构入口点**：

   ```bash
   # 优先访问类成员列表
   AllMembers_T_Autodesk_Navisworks_Api_ClassName.htm
   ```

2. **精确文件名搜索**：

   ```bash
   find . -name "*ClassName*" -o -name "*MethodName*"
   ```

3. **分层搜索方法**：
   - 先定位到类级别文档
   - 从类成员列表找到方法链接
   - 利用文档间超链接导航

4. **搜索模式示例**：

   ```bash
   # 搜索特定API
   grep -r "SaveFile\|Export.*nwd" --include="*.htm" doc/navisworks_api/
   
   # 查找特定类的所有成员
   find . -name "AllMembers_T_Autodesk_Navisworks_Api_Document.htm"
   ```

5. **常用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格式的文件名
- 避免使用过于宽泛的搜索词

## Testing and Deployment

- **Testing environment**: Navisworks Manage 2026 exclusively - 2017 support discontinued
- **Plugin deployment**: Build output automatically copies to Navisworks 2026 plugin directory
- **Hot reload**: Restart Navisworks required after compilation to load new plugin version
- **Debugging**: Use LogManager for centralized logging and the built-in log viewer dialog for log analysis
- **2026 Features**: Test advanced animation capabilities, enhanced collision detection, and improved model handling