TellmeRevitPluging/CLAUDE.md

CLAUDE.md

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

项目概述

这是一个针对Revit 2017的HTTP远程控制插件，通过RESTful API提供Revit模型的远程操作能力。项目采用模块化架构，支持文件操作、统计分析、薄壳优化和IFC导出等功能。

核心架构

技术栈

• .NET Framework 4.6 (x64架构，匹配Revit 2017要求)
• OWIN 自托管HTTP服务器 (端口9000)
• ASP.NET Web API (RESTful设计)
• Revit API 2017 (Autodesk.RevitAPI)
• 线程安全机制: ExternalEvent + ConcurrentQueue

项目结构

Controllers/     # 8个API控制器 (Health, File, Stats, Task, Overview, Shell, Export)
Models/         # 8个数据模型 (统一ApiResponse<T>格式)
Services/       # 6个业务服务 (RevitService, TaskManager, DocumentService等)
Common/         # 公共组件 (48个错误码定义, 扩展方法)
App.cs          # Revit插件主类 (IExternalApplication)
Startup.cs      # OWIN配置

API接口总览

• 基础功能: 健康检查、文件操作、统计分析
• 任务管理: 异步任务追踪、状态查询、取消操作
• 高级功能: 薄壳优化(3种模式)、IFC导出(4种版本)
• 总计: 16个REST API接口，支持同步/异步双模式

开发约束

架构稳定性 (不可更改)

• MVC分层结构: Controllers/Services/Models分离
• 统一响应格式: 所有API使用ApiResponse<T>
• 线程安全机制: Revit操作必须通过ExternalEvent
• 技术栈: .NET 4.6 + OWIN + Web API (不可升级)

线程安全要求

// 正确方式: 通过ExternalEvent调用Revit API
App.Instance.EnqueueCommand(new OpenFileCommand(filePath));

// 错误方式: 直接在HTTP线程调用Revit API
var doc = app.OpenDocumentFile(filePath); // 会导致线程异常

响应格式标准

// 统一使用ApiResponse<T>
return Extensions.CreateSuccessResponse(data, "操作成功");
return Extensions.CreateErrorResponse(ErrorCodes.FILE_NOT_FOUND, "文件不存在");

开发流程

添加新功能

1. Model: 在Models/目录创建数据模型
2. Service: 在Services/实现业务逻辑
3. Controller: 按现有模式创建API控制器
4. 错误处理: 使用ErrorCodes中定义的标准错误码
5. 测试: 使用Postman验证API接口

常用命令

# 编译项目 (必须使用x64配置)
msbuild "(.NET Framework).sln" /p:Configuration=Debug /p:Platform=x64
msbuild "(.NET Framework).sln" /p:Configuration=Release /p:Platform=x64

# 测试API (确保Revit已启动)
curl http://localhost:9000/api/health

部署方式

# 1. 创建插件目录 (如果不存在)
mkdir "%ProgramData%\Autodesk\Revit\Addins\2017\RevitHttpControl"

# 2. 拷贝项目debug文件夹下所有文件到插件目录
copy "bin\x64\Debug\*" "%ProgramData%\Autodesk\Revit\Addins\2017\RevitHttpControl\"

# 3. 拷贝插件清单文件到Revit插件根目录
copy "RevitHttpControl.addin" "%ProgramData%\Autodesk\Revit\Addins\2017\"

部署说明：

• 将项目编译输出目录下的所有文件复制到Revit插件专用目录
• 插件清单文件(.addin)必须放在Revit插件根目录
• 确保所有依赖的DLL文件都已复制到插件目录

错误排除

• 端口占用: 检查9000端口是否被占用
• 权限问题: 以管理员身份运行Revit
• 插件未加载: 检查.addin文件路径配置
• API调用失败: 确保有文档打开且未被锁定

扩展指南

添加新的统计类型

1. 在StatsType枚举中添加新类型
2. 在RevitService.GetBuiltInCategory()中添加映射
3. 更新GetStatsTypeDisplayName()添加中文名称

添加新的优化模式

1. 在ShellOptimizeMode枚举中定义
2. 在ShellAnalyzer.cs中实现分析逻辑
3. 在ShellOptimizer.cs中实现优化算法

重要约束

• 中文优先: 所有用户界面消息使用中文
• 向后兼容: 不得破坏现有API接口
• 单文档模式: 同时只能操作一个Revit文档
• 内网使用: 不建议暴露到公网环境