MianyVue/CAD_API_集成文档.md

# CAD 软件模型处理 API 集成文档

本文档详细说明了不同 CAD 软件（Creo, Revit, PDMS）在本项目中的 API 接入规范，包括基础配置、核心模型操作以及类似 Shrink Wrap（几何优化轻量化）功能的接口文档。请按照以下说明进行前后端集成。

---

## 1. Creo Parametric

- **CAD 软件名称**: Creo Parametric (版本 9.0)
- **Base URL**: `http://localhost:12345`
- **端口**: `12345`

### 1.0. 插件可用性探活 API (Health Check)
- **接口路径**: `/api/health` (或 `/api/status`)
- **请求方式**: `GET`
- **基础描述**: 用于队列执行前快速判活，检测 Creo 插件是否正常启动并可以接收任务，减少无效重试。
- **接入说明**: 
  - **请求参数**: 无
  - **响应格式**:
    ```json
    {
      "status": "success", 
      "message": "Creo 插件在线就绪",
      "data": {
        "isBusy": false // 是否正忙于处理其他任务
      }
    }
    ```
  - **异常响应**: 如插件未启动、断联或崩溃，通常表现为连接超时或 HTTP 50x 错误。

### 1.1. 打开模型 API
- **接口路径**: `/api/model/open`
- **请求方式**: `POST`
- **基础描述**: 在 Creo 软件中加载指定的模型文件。
- **接入说明**: 
  - **请求头**: `Content-Type: application/json`
  - **请求体 (Body)**:
    ```json
    {
      "filePath": "C:\\path\\to\\your\\model.prt" // 字符串，必须是绝对路径
    }
    ```
  - **响应格式**:
    ```json
    {
      "status": "success", // 或 "error"
      "message": "模型加载成功",
      "data": null
    }
    ```
  - **常见错误**: 若路劲不存在或 Creo 实例未启动，status 会返回 error。

### 1.2. 几何优化分析 API (类似 Shrink Wrap 功能)
- **接口路径**: `/api/creo/shrinkwrap/shell` (及 `/api/analysis/shell-analysis`)
- **请求方式**: `POST`
- **基础描述**: 对打开的模型执行几何外壳提取或包络处理，用于轻量化。
- **接入说明**: 
  - **请求头**: `Content-Type: application/json`
  - **请求体 (Body - 参数示例)**:
    ```json
    {
      "method": "outer_shell",        // 提取方法：外壳
      "quality": 5,                   // 提取质量 (1-10)
      "chord_height": 0.15,           // 弦高公差
      "fill_holes": false,            // 是否填充孔洞
      "ignore_small_surfaces": false, // 是否忽略小曲面
      "output_type": "solid_surface"  // 输出类型
    }
    ```
  - **响应格式**:
    ```json
    {
      "status": "success",
      "message": "几何优化完成",
      "data": {
        "output_file": "C:\\path\\to\\optimized_model.prt"
      }
    }
    ```

### 1.3. 关闭模型 API
- **接口路径**: `[占位待实现] /api/model/close`
- **请求方式**: `POST`
- **基础描述**: 关闭当前在 Cero 中处于激活状态的模型，释放内存。
- **接入说明**:
  - 当前后端尚未提供明确的单独关闭接口。
  - **未来预期请求体**: 
    ```json
    {
      "clearMemory": true // 是否连带清除缓存
    }
    ```

---

## 2. Revit

- **CAD 软件名称**: Revit (版本 2024)
- **Base URL**: `http://localhost:9000`
- **端口**: `9000`

### 2.0. 插件可用性探活 API (Health Check)
- **接口路径**: `/api/health` (或 `/api/status`)
- **请求方式**: `GET`
- **基础描述**: 用于队列执行前快速判活，检测 Revit 插件是否正常启动并可以接收任务，减少无效重试。
- **接入说明**: 
  - **请求参数**: 无
  - **响应格式**:
    ```json
    {
      "status": "success", 
      "message": "Revit 插件在线就绪",
      "data": {
        "isBusy": false
      }
    }
    ```
  - **异常响应**: 如插件未启动、断联或崩溃，通常表现为连接超时或 HTTP 50x 错误。

### 2.1. 打开模型 API
- **接口路径**: `/api/open`
- **请求方式**: `POST`
- **基础描述**: 打开指定的 Revit 项目文件 (.rvt)。
- **接入说明**:
  - **请求格式**: `application/json`
  - **请求体 (Body)**:
    ```json
    {
      "filePath": "C:\\path\\to\\project.rvt"
    }
    ```

### 2.2. 轻量化提取外壳 API (类似 Shrink Wrap 功能)
- **接口路径**: `/api/shell/analyze` (提取分析) / `/api/shell/execute` (执行处理)
- **请求方式**: `POST`
- **基础描述**: 分析 Revit 建筑模型并剥离内部不需要的实体细节。
- **接入说明**:
  - **请求体 (Body)**:
    ```json
    {
      "detailLevel": "coarse", // 粗略级别
      "removeInternal": true   // 是否移除内部构件
    }
    ```
  - **响应格式**:
    ```json
    {
      "status": "success",
      "data": {
        "taskId": "task-123456" // 大模型处理可能较慢，建议通过 /api/task 轮询进度
      }
    }
    ```

### 2.3. 关闭模型 API
- **接口路径**: `[占位待实现] /api/close`
- **请求方式**: `POST`
- **基础描述**: 关闭 Revit 当前工程并释放资源。
- **接入说明**:
  - 当前未列出明确接口，前端可作为占位按钮。

---

## 3. PDMS

- **CAD 软件名称**: PDMS (版本 12.1)
- **Base URL**: `http://localhost:9001`
- **端口**: `9001`

### 3.0. 插件可用性探活 API (Health Check)
- **接口路径**: `/api/health` (或 `/api/status`)
- **请求方式**: `GET`
- **基础描述**: 用于队列执行前快速判活，检测 PDMS 插件是否正常启动并可以接收任务，减少无效重试。
- **接入说明**: 
  - **请求参数**: 无
  - **响应格式**:
    ```json
    {
      "status": "success", 
      "message": "PDMS 插件在线就绪",
      "data": {
        "isBusy": false
      }
    }
    ```
  - **异常响应**: 如插件未启动、断联或崩溃，通常表现为连接超时或 HTTP 50x 错误。

### 3.1. 打开模型 API
- **接口路径**: `/api/project/open` (打开工程) / `/api/mdb/open` (打开 MDB 数据库)
- **请求方式**: `POST`
- **基础描述**: 载入 PDMS 的工程或特定 MDB 库。
- **接入说明**:
  - **请求体 (Body)**:
    ```json
    {
      "projectName": "SAM",
      "username": "SYSTEM",
      "password": "XXXXXX",
      "systemName": "CATA"
    }
    ```

### 3.2. 模型简化与包裹 API (类似 Shrink Wrap 功能)
- **接口路径**: `/api/model/shrinkwrap` (包裹) / `/api/model/simplify` (参数化简化)
- **请求方式**: `POST`
- **基础描述**: 将复杂的管道、设备利用包围盒或简化几何进行替代。
- **接入说明**:
  - **请求体 (Body) - Simplify 示例**:
    ```json
    {
      "targetElements": ["/EQUIP-1", "/PIPE-2"], 
      "simplifyMethod": "bounding_box" 
    }
    ```
  - **响应**: 处理成功后通常会通过 WebSocket 推送更新或直接返回简化的模型状态数据。

### 3.3. 关闭模型 API
- **接口路径**: `[占位待实现] /api/project/close`
- **请求方式**: `POST`
- **基础描述**: 退出工程并回收当前资源。
- **接入说明**: 
  - 占位状态，开发集成时需要确保该请求不会导致整个 PDMS 进程意外崩溃。