116 lines
4.1 KiB
Markdown
116 lines
4.1 KiB
Markdown
# 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 (不可升级)
|
||
|
||
### 线程安全要求
|
||
```csharp
|
||
// 正确方式: 通过ExternalEvent调用Revit API
|
||
App.Instance.EnqueueCommand(new OpenFileCommand(filePath));
|
||
|
||
// 错误方式: 直接在HTTP线程调用Revit API
|
||
var doc = app.OpenDocumentFile(filePath); // 会导致线程异常
|
||
```
|
||
|
||
### 响应格式标准
|
||
```csharp
|
||
// 统一使用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接口
|
||
|
||
### 常用命令
|
||
```bash
|
||
# 编译项目 (必须使用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
|
||
```
|
||
|
||
### 部署方式
|
||
```bash
|
||
# 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文档
|
||
- **内网使用**: 不建议暴露到公网环境 |