# RevitHttpControl API 接口文档

## 概述

RevitHttpControl 是一个 Revit 2017 远程控制插件，提供 HTTP API 接口来实现 Revit 模型的远程操作。

**基本信息：**
- 服务器地址：`http://localhost:9000`
- 数据格式：JSON
- 字符编码：UTF-8

## 统一响应格式

所有接口都遵循统一的响应格式：

```json
{
  "success": true,           // 操作是否成功
  "code": 200,              // 状态码
  "message": "操作成功",     // 状态消息
  "data": {},               // 响应数据
  "timestamp": "2025-01-27T10:30:00Z"  // 时间戳（自动生成）
}
```

## 接口列表

### 1. 服务器状态检查 ✅

**接口地址：** `GET /api/health`

**功能描述：** 检查 Revit 服务器状态和当前文档信息

**实现状态：** ✅ 已完成并测试通过

**请求示例：**
```
GET /api/health
```

**响应示例：**
```json
// 有文档打开时
{
  "success": true,
  "code": 200,
  "message": "服务正常",
  "data": {
    "serverStatus": "running",
    "revitVersion": "2017",
    "currentDocument": {
      "isOpen": true,
      "fileName": "MyProject.rvt",
      "filePath": "C:\\Projects\\MyProject.rvt"
    }
  },
  "timestamp": "2025-01-27T10:30:00.000Z"
}

// 无文档打开时
{
  "success": true,
  "code": 200,
  "message": "服务正常",
  "data": {
    "serverStatus": "running",
    "revitVersion": "2017",
    "currentDocument": {
      "isOpen": false,
      "fileName": null,
      "filePath": null
    }
  },
  "timestamp": "2025-01-27T10:30:00.000Z"
}
```

**状态说明：**
- `serverStatus`: 服务器状态（running/stopped）
- `currentDocument.isOpen`: 是否有打开的文档
- `fileName`: 当前文档名称（无文档时为 null）
- `filePath`: 当前文档路径（无文档时为 null）

---

### 2. 打开文件（同步） ✅

**接口地址：** `POST /api/open`

**实现状态：** ✅ 已完成

**功能描述：** 同步打开 Revit 文件

**请求参数：**
```json
{
  "filePath": "string",  // 文件路径（必填）
  "detached": "boolean"  // 是否分离模式（可选，默认false）
}
```

**参数说明：**
- `filePath`: Revit 文件的完整路径，支持 .rvt 格式
- `detached`: 
  - `true`: 分离模式（保留工作集）
  - `false`: 正常模式（丢弃工作集）

**请求示例：**
```json
{
  "filePath": "C:\\Projects\\MyProject.rvt",
  "detached": false
}
```

**响应示例：**
```json
// 成功
{
  "success": true,
  "code": 200,
  "message": "文件打开成功",
  "data": {
    "result": "文件打开成功",
    "fileName": "MyProject.rvt",
    "filePath": "C:\\Projects\\MyProject.rvt"
  },
  "timestamp": "2025-01-27T10:30:00Z"
}

// 失败
{
  "success": false,
  "code": 404,
  "message": "文件不存在或路径无效",
  "data": {
    "error": "FILE_NOT_FOUND"
  },
  "timestamp": "2025-01-27T10:30:00Z"
}
```

---

### 3. 打开文件（异步） ✅

**接口地址：** `POST /api/open/async`

**实现状态：** ✅ 已完成

**功能描述：** 异步打开 Revit 文件，返回任务ID

**请求参数：** 与同步接口相同

**响应示例：**
```json
{
  "success": true,
  "code": 202,
  "message": "文件打开任务已创建",
  "data": {
    "taskId": "123e4567-e89b-12d3-a456-426614174000",
    "statusUrl": "/api/task/123e4567-e89b-12d3-a456-426614174000"
  },
  "timestamp": "2025-01-27T10:30:00Z"
}
```

---

### 4. 获取统计信息（同步） ✅

**接口地址：** `POST /api/stats/sync`

**实现状态：** ✅ 已完成

**功能描述：** 同步获取当前打开模型的元素统计信息

**请求参数：**
```json
{
  "type": "integer"  // 统计类型（必填）
}
```

**统计类型说明：**
| 值 | 类型 | 说明 |
|---|---|---|
| 0 | Wall | 墙体 |
| 1 | Door | 门 |
| 2 | Window | 窗 |
| 3 | Floor | 地板 |
| 4 | Ceiling | 天花板 |
| 5 | Roof | 屋顶 |
| 6 | Column | 柱子 |
| 7 | Beam | 梁 |
| 8 | Furniture | 家具 |
| 9 | Room | 房间 |

**请求示例：**
```json
{
  "type": 0  // 统计墙体数量
}
```

**响应示例：**
```json
// 成功
{
  "success": true,
  "code": 200,
  "message": "统计数据获取成功",
  "data": {
    "elementType": "Wall",
    "count": 25,
    "details": {
      "typeName": "墙体",
      "typeId": -2000011
    }
  },
  "timestamp": "2025-01-27T10:30:00Z"
}

// 失败 - 无文档打开
{
  "success": false,
  "code": 409,
  "message": "没有打开的文档",
  "data": {
    "error": "NO_DOCUMENT_OPEN"
  },
  "timestamp": "2025-01-27T10:30:00Z"
}
```

---

### 5. 获取统计信息（异步） ✅

**接口地址：** `POST /api/stats/async`

**实现状态：** ✅ 已完成

**功能描述：** 异步获取当前打开模型的元素统计信息

**请求参数：**
```json
{
  "type": "integer"  // 统计类型（必填）
}
```

**请求示例：**
```json
{
  "type": 0  // 统计墙体数量
}
```

**响应示例：**
```json
{
  "success": true,
  "code": 202,
  "message": "统计任务已创建",
  "data": {
    "taskId": "12345678-1234-1234-1234-123456789abc",
    "statusUrl": "/api/task/12345678-1234-1234-1234-123456789abc"
  },
  "timestamp": "2025-01-27T10:30:00Z"
}
```

---

### 6. 查询任务状态 ✅

**接口地址：** `GET /api/task/{taskId}`

**实现状态：** ✅ 已完成

**功能描述：** 查询异步任务的执行状态和结果

**路径参数：**
- `taskId`: 任务ID（从异步统计接口返回）

**请求示例：**
```
GET /api/task/12345678-1234-1234-1234-123456789abc
```

**响应示例：**
```json
// 进行中
{
  "success": true,
  "code": 200,
  "message": "获取任务状态成功",
  "data": {
    "taskId": "12345678-1234-1234-1234-123456789abc",
    "status": "Running",
    "createdAt": "2025-01-27T10:30:00Z",
    "completedAt": null,
    "result": null,
    "errorMessage": null
  },
  "timestamp": "2025-01-27T10:30:15Z"
}

// 完成
{
  "success": true,
  "code": 200,
  "message": "获取任务状态成功",
  "data": {
    "taskId": "12345678-1234-1234-1234-123456789abc",
    "status": "Completed",
    "createdAt": "2025-01-27T10:30:00Z",
    "completedAt": "2025-01-27T10:30:45Z",
    "result": {
      "elementType": "Wall",
      "count": 25,
      "details": {
        "typeName": "墙体",
        "typeId": -2000011
      }
    },
    "errorMessage": null
  },
  "timestamp": "2025-01-27T10:30:45Z"
}

// 失败
{
  "success": true,
  "code": 200,
  "message": "获取任务状态成功",
  "data": {
    "taskId": "12345678-1234-1234-1234-123456789abc",
    "status": "Failed",
    "createdAt": "2025-01-27T10:30:00Z",
    "completedAt": "2025-01-27T10:30:30Z",
    "result": null,
    "errorMessage": "没有打开的文档"
  },
  "timestamp": "2025-01-27T10:30:30Z"
}

// 任务不存在
{
  "success": false,
  "code": 404,
  "message": "任务不存在",
  "data": {
    "error": "TASK_NOT_FOUND"
  },
  "timestamp": "2025-01-27T10:30:30Z"
}
```

**任务状态说明：**
- `Pending`: 等待中
- `Running`: 运行中  
- `Completed`: 已完成
- `Failed`: 失败
- `Cancelled`: 已取消

---

### 7. 旧版任务状态查询（兼容） ✅

**接口地址：** `GET /api/status/{taskId}`

**实现状态：** ✅ 已完成（向后兼容）

**功能描述：** 兼容旧版的简化任务状态查询

**响应示例：**
```json
// 完成时
{ "result": 25 }

// 处理中
{ "status": "processing" }

// 失败时  
{ "error": "没有打开的文档" }
```

---

### 8. 取消任务 ✅

**接口地址：** `DELETE /api/task/{taskId}`

**实现状态：** ✅ 已完成

**功能描述：** 取消正在进行的任务

**响应示例：**
```json
{
  "success": true,
  "code": 200,
  "message": "任务已取消",
  "data": {
    "taskId": "12345678-1234-1234-1234-123456789abc"
  },
  "timestamp": "2025-01-27T10:30:00Z"
}
```

---

### 9. 任务管理器状态 ✅

**接口地址：** `GET /api/tasks/status`

**实现状态：** ✅ 已完成

**功能描述：** 获取任务管理器整体状态

**响应示例：**
```json
{
  "success": true,
  "code": 200,
  "message": "获取任务管理器状态成功",
  "data": {
    "totalTasks": 15,
    "pendingTasks": 2,
    "runningTasks": 1,
    "completedTasks": 10,
    "failedTasks": 1,
    "cancelledTasks": 1
  },
  "timestamp": "2025-01-27T10:30:00Z"
}
```

---

### 10. 薄壳优化 - 获取优化模式配置 ✅

**接口地址：** `GET /api/shell/modes`

**功能描述：** 获取所有薄壳优化模式的配置说明

**请求示例：**
```
GET /api/shell/modes
```

**响应示例：**
```json
{
  "success": true,
  "code": 200,
  "message": "优化模式配置获取成功",
  "data": [
    {
      "mode": "Conservative",
      "name": "保守模式",
      "description": "仅删除装饰元素，减少约30%文件大小",
      "estimatedReduction": "30%",
      "deletedElements": ["配景", "植物", "装饰元素"]
    },
    {
      "mode": "Standard",
      "name": "标准模式",
      "description": "删除家具和部分内墙，减少约65%文件大小",
      "estimatedReduction": "65%",
      "deletedElements": ["家具", "橱柜", "配景", "植物", "部分灯具"]
    },
    {
      "mode": "Aggressive",
      "name": "激进模式",
      "description": "删除所有内部元素，减少约80%文件大小",
      "estimatedReduction": "80%",
      "deletedElements": ["家具", "设备", "天花板", "配景", "植物", "灯具", "内部装饰"]
    }
  ],
  "timestamp": "2025-01-27T10:30:00Z"
}
```

---

### 11. 薄壳优化 - 分析模型薄壳优化方案 ✅

**接口地址：** `POST /api/shell/analyze`

**功能描述：** 分析当前模型在指定优化模式下的薄壳优化效果（仅分析，不做实际删除）

**请求参数：**
```json
{
  "mode": "Standard" // 优化模式，必填，取值：Conservative/Standard/Aggressive
}
```

**请求示例：**
```json
{
  "mode": "Standard"
}
```

**响应示例：**
```json
{
  "success": true,
  "code": 200,
  "message": "薄壳分析完成",
  "data": {
    "analysis": {
      "totalElements": 1250,
      "keepElements": 875,
      "removeElements": 375,
      "estimatedReduction": "65%"
    },
    "categories": [
      {
        "name": "墙",
        "total": 120,
        "keep": 95,
        "remove": 25,
        "keepPercentage": "79%"
      },
      {
        "name": "家具",
        "total": 180,
        "keep": 0,
        "remove": 180,
        "keepPercentage": "0%"
      }
    ]
  },
  "timestamp": "2025-01-27T10:30:00Z"
}
```

---

### 12. 薄壳优化 - 执行薄壳优化（异步） ✅

**接口地址：** `POST /api/shell/execute`

**功能描述：** 按指定模式异步执行薄壳优化，返回任务ID，适合大型模型

**请求参数：**
```json
{
  "mode": "Standard",         // 优化模式，必填
  "backupOriginal": true       // 是否备份原文件，建议true
}
```

**请求示例：**
```json
{
  "mode": "Standard",
  "backupOriginal": true
}
```

**响应示例：**
```json
{
  "success": true,
  "code": 202,
  "message": "薄壳优化任务已创建",
  "data": {
    "taskId": "123e4567-e89b-12d3-a456-426614174000",
    "statusUrl": "/api/task/123e4567-e89b-12d3-a456-426614174000"
  },
  "timestamp": "2025-01-27T10:30:00Z"
}
```

**任务进度查询：**
```
GET /api/task/{taskId}
```

**完成后响应示例：**
```json
{
  "success": true,
  "code": 200,
  "message": "任务查询成功",
  "data": {
    "taskId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "Completed",
    "result": {
      "removedCount": 342,
      "originalSize": "156.8 MB",
      "optimizedSize": "54.9 MB",
      "reduction": "65.0%",
      "backupPath": "D:\\Projects\\Building_backup_20241230_143052.rvt",
      "processingTimeSeconds": 45.2
    }
  },
  "timestamp": "2025-01-27T10:30:00Z"
}
```

---

### 13. 薄壳优化 - 执行薄壳优化（同步） ✅

**接口地址：** `POST /api/shell/execute/sync`

**功能描述：** 按指定模式同步执行薄壳优化，适合小型模型或测试

**请求参数：**
```json
{
  "mode": "Conservative",    // 优化模式，必填
  "backupOriginal": true      // 是否备份原文件，建议true
}
```

**请求示例：**
```json
{
  "mode": "Conservative",
  "backupOriginal": true
}
```

**响应示例：**
```json
{
  "success": true,
  "code": 200,
  "message": "薄壳优化执行完成",
  "data": {
    "removedCount": 120,
    "originalSize": "156.8 MB",
    "optimizedSize": "109.8 MB",
    "reduction": "30.0%",
    "backupPath": "D:\\Projects\\Building_backup_20241230_143052.rvt",
    "processingTimeSeconds": 12.5
  },
  "timestamp": "2025-01-27T10:30:00Z"
}
```

---

### 14. 获取支持的导出格式 ✅

**接口地址：** `GET /api/export/formats`

**实现状态：** ✅ 已完成

**功能描述：** 获取系统支持的所有导出格式列表

**请求示例：**
```
GET /api/export/formats
```

**响应示例：**
```json
{
  "Success": true,
  "Code": 200,
  "Message": "获取支持的导出格式成功",
  "Data": [
    {
      "Name": "IFC",
      "Description": "Industry Foundation Classes - 建筑信息模型交换格式",
      "FileExtension": ".ifc",
      "SupportedVersions": ["IFC2x3", "IFC4", "IFC4RV", "IFC4DTV"],
      "IsAsync": true
    }
  ],
  "timestamp": "2025-01-27T10:30:00Z"
}
```

---

### 15. 同步导出IFC格式 ✅

**接口地址：** `POST /api/export/ifc`

**实现状态：** ✅ 已完成

**功能描述：** 同步导出当前打开的Revit模型为IFC格式，适合小文件或快速导出

**请求参数：**
```json
{
  "IfcVersion": "IFC4",                           // IFC版本，必填
  "OutputPath": "C:\\Export\\model.ifc",         // 输出路径，可选
  "ExportRange": "VisibleElements",              // 导出范围，可选
  "IncludeSpaceBoundaries": true,                // 包含空间边界，可选
  "SplitWallsAndColumns": false,                 // 分离墙和柱，可选
  "Include2DElements": false,                    // 包含2D元素，可选
  "ExportBaseQuantities": true,                  // 导出基本数量，可选
  "ExportSchedulesAsTables": false,              // 导出明细表，可选
  "ExportUserDefinedPsets": true,                // 导出用户属性集，可选
  "ExportInternalRevitPropertySets": false,     // 导出内部属性集，可选
  "ExportIFCCommonPropertySets": true,          // 导出IFC通用属性集，可选
  "ExportPartsAsBuildingElements": false,        // 导出部件为建筑元素，可选
  "ExportBoundingBox": false,                    // 导出边界框，可选
  "ExportSolidModelRep": false,                  // 导出实体模型，可选
  "ExportLinkedFiles": false                     // 导出链接文件，可选
}
```

**参数说明：**
- `IfcVersion`: IFC版本，支持 "IFC2x3", "IFC4", "IFC4RV", "IFC4DTV"
- `OutputPath`: 输出文件路径，不提供则自动生成到当前文档目录
- `ExportRange`: 导出范围
  - `"AllElements"`: 所有元素
  - `"VisibleElements"`: 可见元素（默认）
  - `"SelectedElements"`: 选中元素
- 其他参数均为可选的导出选项，默认值为false

**请求示例：**
```json
{
  "IfcVersion": "IFC4",
  "OutputPath": "C:\\Export\\MyProject.ifc",
  "ExportRange": "VisibleElements",
  "IncludeSpaceBoundaries": true,
  "ExportBaseQuantities": true,
  "ExportUserDefinedPsets": true,
  "ExportIFCCommonPropertySets": true
}
```

**成功响应：**
```json
{
  "Success": true,
  "Code": 200,
  "Message": "IFC导出成功",
  "Data": {
    "FilePath": "C:\\Export\\MyProject.ifc",
    "FileSize": 1024000,
    "ExportTime": "2024-01-01T10:30:00",
    "Statistics": {
      "TotalElements": 1500,
      "ExportedElements": 1450,
      "SkippedElements": 50
    }
  },
  "timestamp": "2025-01-27T10:30:00Z"
}
```

**错误响应示例：**
```json
// 无文档打开
{
  "Success": false,
  "Code": 409,
  "Message": "没有打开的文档",
  "Data": {
    "error": "NO_DOCUMENT_OPEN"
  },
  "timestamp": "2025-01-27T10:30:00Z"
}

// 路径无效
{
  "Success": false,
  "Code": 400,
  "Message": "导出路径无效",
  "Data": {
    "error": "EXPORT_PATH_INVALID"
  },
  "timestamp": "2025-01-27T10:30:00Z"
}
```

---

### 16. 异步导出IFC格式 ✅

**接口地址：** `POST /api/export/ifc/async`

**实现状态：** ✅ 已完成

**功能描述：** 异步导出当前打开的Revit模型为IFC格式，适合大文件或长时间导出

**请求参数：** 与同步接口相同

**请求示例：**
```json
{
  "IfcVersion": "IFC4",
  "OutputPath": "C:\\Export\\LargeProject.ifc",
  "ExportRange": "AllElements",
  "IncludeSpaceBoundaries": true,
  "ExportBaseQuantities": true
}
```

**立即响应：**
```json
{
  "Success": true,
  "Code": 202,
  "Message": "IFC导出任务已创建",
  "Data": {
    "TaskId": "12345678-1234-1234-1234-123456789abc",
    "StatusUrl": "/api/task/12345678-1234-1234-1234-123456789abc",
    "EstimatedCompletionTime": "2024-01-01T10:35:00"
  },
  "timestamp": "2025-01-27T10:30:00Z"
}
```

**任务状态查询：**
```
GET /api/task/12345678-1234-1234-1234-123456789abc
```

**完成后响应示例：**
```json
{
  "success": true,
  "code": 200,
  "message": "获取任务状态成功",
  "data": {
    "taskId": "12345678-1234-1234-1234-123456789abc",
    "status": "Completed",
    "createdAt": "2025-01-27T10:30:00Z",
    "completedAt": "2025-01-27T10:35:30Z",
    "result": {
      "FilePath": "C:\\Export\\LargeProject.ifc",
      "FileSize": 5120000,
      "ExportTime": "2024-01-01T10:35:30",
      "Statistics": {
        "TotalElements": 8500,
        "ExportedElements": 8200,
        "SkippedElements": 300
      }
    },
    "errorMessage": null
  },
  "timestamp": "2025-01-27T10:35:30Z"
}
```

---

#### IFC导出注意事项

1. **必须有打开的Revit文档**，否则接口会返回409错误。
2. **IFC版本选择**：
   - `IFC2x3`: 兼容性最好，适合旧版软件
   - `IFC4`: 新标准，功能更丰富（推荐）
   - `IFC4RV`: Revit视图专用版本
   - `IFC4DTV`: 设计传输视图版本
3. **导出路径**：
   - 不提供OutputPath时，自动生成到当前文档同目录
   - 路径必须是绝对路径，且目录必须存在
   - 文件扩展名必须是.ifc
4. **导出范围建议**：
   - 小模型：使用同步接口，选择VisibleElements
   - 大模型：使用异步接口，选择AllElements
5. **性能优化**：
   - 大文件建议使用异步接口避免超时
   - 可通过ExportRange控制导出元素数量
6. **Revit 2017兼容性**：
   - 某些高级选项可能不支持（如SplitWallsAndColumns）
   - 系统会自动忽略不支持的选项

---

#### 薄壳优化注意事项

1. **必须有打开的Revit文档**，否则接口会返回400错误。
2. **建议始终设置 `backupOriginal: true`**，系统会自动创建带时间戳的备份文件。
3. **模式选择建议**：首次使用建议选择保守模式，避免误删。
4. **大型模型建议使用异步接口**，小型模型可用同步接口。
5. **接口参数区分大小写**，mode参数必须为Conservative/Standard/Aggressive。
6. **所有薄壳接口均有详细错误码和说明，见统一响应格式和错误码表。

---

## 错误码定义

| 错误码 | 描述 | 解决方案 |
|---|---|---|
| `FILE_NOT_FOUND` | 文件不存在 | 检查文件路径是否正确 |
| `FILE_ACCESS_DENIED` | 文件访问被拒绝 | 检查文件权限或文件是否被占用 |
| `NO_DOCUMENT_OPEN` | 没有打开的文档 | 先使用 `/api/open` 打开文件 |
| `INVALID_ELEMENT_TYPE` | 无效的元素类型 | 检查统计类型参数是否在 0-9 范围内 |
| `REVIT_NOT_READY` | Revit 未就绪 | 等待 Revit 完全启动后重试 |
| `OPERATION_TIMEOUT` | 操作超时 | 重试操作或增加超时时间 |
| `PROCESSING_ERROR` | 处理过程中发生错误 | 查看详细错误信息并重试 |
| `INTERNAL_ERROR` | 内部服务器错误 | 联系技术支持 |
| `EXPORT_FAILED` | 导出失败 | 检查模型和导出参数 |
| `EXPORT_PATH_INVALID` | 导出路径无效 | 检查路径格式和权限 |
| `EXPORT_PATH_ACCESS_DENIED` | 导出路径访问被拒绝 | 检查目录权限 |
| `EXPORT_NO_ELEMENTS` | 没有可导出的元素 | 检查导出范围设置 |
| `EXPORT_UNSUPPORTED_FORMAT` | 不支持的导出格式 | 使用支持的格式 |
| `EXPORT_CONFIGURATION_ERROR` | 导出配置错误 | 检查导出参数设置 |
| `IFC_EXPORT_FAILED` | IFC导出失败 | 检查IFC版本和参数 |
| `IFC_VERSION_NOT_SUPPORTED` | IFC版本不支持 | 使用支持的IFC版本 |
| `EXPORT_CANCELLED_BY_USER` | 用户取消导出 | 重新发起导出请求 |
| `EXPORT_DISK_SPACE_INSUFFICIENT` | 磁盘空间不足 | 清理磁盘空间 |

---

## 使用流程

### 推荐使用流程：

1. **检查服务器状态**
2. **打开文件**
3. **获取统计信息**

### 前端使用示例

```javascript
class RevitApi {
  constructor() {
    this.baseUrl = 'http://localhost:9000/api';
  }
  
  // 检查服务器状态
  async checkHealth() {
    try {
      const response = await fetch(`${this.baseUrl}/health`);
      const result = await response.json();
      return result;
    } catch (error) {
      return {
        success: false,
        code: 500,
        message: '服务器连接失败',
        data: { error: 'CONNECTION_ERROR' }
      };
    }
  }
  
  // 打开文件
  async openFile(filePath, detached = false) {
    const response = await fetch(`${this.baseUrl}/open`, {
      method: 'POST',
      headers: {'Content-Type': 'application/json'},
      body: JSON.stringify({filePath, detached})
    });
    return await response.json();
  }
  
  // 获取统计信息（同步）
  async getStatsSync(type) {
    const response = await fetch(`${this.baseUrl}/stats/sync`, {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
      body: JSON.stringify({type})
});
    return await response.json();
  }

  // 获取统计信息（异步）
  async getStatsAsync(type) {
    const response = await fetch(`${this.baseUrl}/stats/async`, {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
      body: JSON.stringify({type})
});
    return await response.json();
  }
  
  // 查询任务状态
  async getTaskStatus(taskId) {
    const response = await fetch(`${this.baseUrl}/task/${taskId}`);
    return await response.json();
  }

  // 获取支持的导出格式
  async getSupportedFormats() {
    const response = await fetch(`${this.baseUrl}/export/formats`);
    return await response.json();
  }

  // 同步导出IFC
  async exportIfcSync(exportRequest) {
    const response = await fetch(`${this.baseUrl}/export/ifc`, {
      method: 'POST',
      headers: {'Content-Type': 'application/json'},
      body: JSON.stringify(exportRequest)
    });
    return await response.json();
  }

  // 异步导出IFC
  async exportIfcAsync(exportRequest) {
    const response = await fetch(`${this.baseUrl}/export/ifc/async`, {
      method: 'POST',
      headers: {'Content-Type': 'application/json'},
      body: JSON.stringify(exportRequest)
    });
    return await response.json();
  }
}

// 使用示例
const api = new RevitApi();

async function example() {
  // 1. 检查服务器状态
  const health = await api.checkHealth();
  if (!health.success) {
    console.error('服务器未就绪:', health.message);
    return;
  }
  
  // 2. 打开文件
  const openResult = await api.openFile('C:\\Projects\\MyProject.rvt');
  if (!openResult.success) {
    console.error('文件打开失败:', openResult.data.errorDescription);
    return;
  }
  
  console.log('文件打开成功:', openResult.data.fileName);
  
  // 3. 获取墙体统计（同步）
  const statsResult = await api.getStatsSync(0);
  if (statsResult.success) {
    console.log('墙体数量:', statsResult.data.count);
  } else {
    console.error('统计失败:', statsResult.data.errorDescription);
  }

  // 4. 导出IFC文件（同步）
  const exportRequest = {
    IfcVersion: "IFC4",
    OutputPath: "C:\\Export\\MyProject.ifc",
    ExportRange: "VisibleElements",
    IncludeSpaceBoundaries: true,
    ExportBaseQuantities: true
  };

  const exportResult = await api.exportIfcSync(exportRequest);
  if (exportResult.Success) {
    console.log('IFC导出成功:', exportResult.Data.FilePath);
    console.log('文件大小:', exportResult.Data.FileSize, 'bytes');
    console.log('导出元素数:', exportResult.Data.Statistics.ExportedElements);
  } else {
    console.error('导出失败:', exportResult.Message);
  }
}

// 异步导出示例
async function exportLargeModel() {
  const api = new RevitApi();

  // 检查服务器状态
  const health = await api.checkHealth();
  if (!health.success) {
    console.error('服务器未就绪');
    return;
  }

  // 异步导出大模型
  const exportRequest = {
    IfcVersion: "IFC4",
    OutputPath: "C:\\Export\\LargeProject.ifc",
    ExportRange: "AllElements",
    IncludeSpaceBoundaries: true,
    ExportBaseQuantities: true,
    ExportUserDefinedPsets: true
  };

  const asyncResult = await api.exportIfcAsync(exportRequest);
  if (!asyncResult.Success) {
    console.error('导出任务创建失败:', asyncResult.Message);
    return;
  }

  console.log('导出任务已创建:', asyncResult.Data.TaskId);

  // 轮询任务状态
  const taskId = asyncResult.Data.TaskId;
  let completed = false;

  while (!completed) {
    await new Promise(resolve => setTimeout(resolve, 2000)); // 等待2秒

    const status = await api.getTaskStatus(taskId);
    if (status.success) {
      console.log('任务状态:', status.data.status);

      if (status.data.status === 'Completed') {
        console.log('导出完成!');
        console.log('文件路径:', status.data.result.FilePath);
        console.log('文件大小:', status.data.result.FileSize, 'bytes');
        completed = true;
      } else if (status.data.status === 'Failed') {
        console.error('导出失败:', status.data.errorMessage);
        completed = true;
      }
    }
  }
}
```

---

## 状态码说明

| HTTP 状态码 | 含义 | 使用场景 |
|---|---|---|
| 200 | 成功 | 操作成功完成 |
| 202 | 已接受 | 异步任务已创建 |
| 400 | 请求错误 | 参数错误、文件不存在等 |
| 404 | 未找到 | 任务不存在 |
| 500 | 服务器错误 | 内部处理错误 |

---

## 注意事项

1. **前置条件：** 确保 Revit 2017 已启动且插件已加载
2. **文件路径：** 必须使用完整的绝对路径，路径中的反斜杠需要转义
3. **同步 vs 异步：** 
   - 同步接口适用于快速操作，直接返回结果
   - 异步接口适用于耗时操作，返回任务ID需要轮询
4. **错误处理：** 所有错误都有详细的错误码和描述
5. **网络安全：** 仅限内网使用，不建议暴露到公网

---

## 测试工具

### Postman 测试配置

1. **导入基本配置**
   - Base URL: `http://localhost:9000/api`
   - Content-Type: `application/json`

2. **测试顺序**
   - 先测试 `GET /health` 确认服务正常
   - 然后测试 `POST /open` 打开文件
   - 最后测试 `POST /stats/sync` 获取统计

3. **示例测试数据**
   ```json
   // 打开文件
   {
     "filePath": "C:\\temp\\test.rvt",
     "detached": false
   }

   // 统计墙体
   {
     "type": 0
   }

   // 同步导出IFC
   {
     "IfcVersion": "IFC4",
     "OutputPath": "C:\\Export\\test.ifc",
     "ExportRange": "VisibleElements",
     "IncludeSpaceBoundaries": true,
     "ExportBaseQuantities": true
   }

   // 异步导出IFC（大文件）
   {
     "IfcVersion": "IFC4",
     "OutputPath": "C:\\Export\\large_model.ifc",
     "ExportRange": "AllElements",
     "IncludeSpaceBoundaries": true,
     "ExportBaseQuantities": true,
     "ExportUserDefinedPsets": true,
     "ExportIFCCommonPropertySets": true
   }
   ```

4. **导出接口测试顺序**
   - 先测试 `GET /api/export/formats` 获取支持格式
   - 确保有文档打开后测试 `POST /api/export/ifc`
   - 测试异步导出 `POST /api/export/ifc/async` 并轮询任务状态