# 建模文件管理 API 接口说明

## 📋 概述

本文档描述了建模文件管理系统的REST API接口，提供3D模型文件的上传、查询、删除和下载功能。支持GLB、GLTF、B3DM和3D Tiles格式的3D模型文件，集成MinIO对象存储服务。

## 🏗️ 系统架构

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Controller    │    │     Service     │    │   MinIO存储     │
│                 │    │                 │    │                 │
│ ┌─────────────┐ │    │ ┌─────────────┐ │    │ ┌─────────────┐ │
│ │文件上传接口  │ │◄──►│ │文件管理服务  │ │◄──►│ │3D模型文件   │ │
│ │列表查询接口  │ │    │ │             │ │    │ │             │ │
│ │删除文件接口  │ │    │ │- 文件验证   │ │    │ │- GLB格式    │ │
│ │下载文件接口  │ │    │ │- 存储管理   │ │    │ │- GLTF格式   │ │
│ └─────────────┘ │    │ │- 数据库操作 │ │    │ │- B3DM格式   │ │
└─────────────────┘    │ └─────────────┘ │    │ │- 3D Tiles   │ │
                       └─────────────────┘    │ └─────────────┘ │
                                              └─────────────────┘
```

## 🔧 基础信息

- **基础路径**: `/dji/api/modeling/models`
- **Content-Type**: `multipart/form-data` (上传接口), `application/json` (其他接口)
- **认证方式**: 基于租户ID的多租户架构
- **存储服务**: MinIO对象存储

## 📚 API接口详情

### 1. 上传模型文件

**接口地址**: `POST /dji/api/modeling/models/upload`

**功能描述**: 上传3D模型文件到指定工作空间

**请求参数**:
| 参数名 | 类型 | 必填 | 描述 | 示例值 |
|--------|------|------|------|--------|
| file | MultipartFile | 是 | 上传的文件 | building.glb |
| workspaceId | String | 是 | 工作空间ID | "default" |
| description | String | 否 | 文件描述 | "建筑模型文件" |

**支持的文件格式**:
- GLB (`.glb`)
- GLTF (`.gltf`)
- B3DM (`.b3dm`)
- 3D Tiles (`.json`)

**文件大小限制**: 最大100MB

**请求示例**:
```bash
curl -X POST "http://localhost:8080/dji/api/modeling/models/upload" \
  -F "file=@building.glb" \
  -F "workspaceId=default" \
  -F "description=建筑模型文件"
```

**响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": "a1b2c3d4e5f6g7h8",
    "fileName": "building.glb",
    "fileType": "glb",
    "fileSize": 2048576,
    "uploadTime": "2024-01-15T10:30:00",
    "url": "http://27.11.11.30:9000/3d-model/default/2024/01/a1b2c3d4e5f6g7h8_building.glb",
    "workspaceId": "default",
    "description": "建筑模型文件"
  }
}
```

**错误响应**:
```json
{
  "code": 400,
  "message": "文件上传失败: 不支持的文件格式",
  "data": null
}
```

---

### 2. 获取模型文件列表

**接口地址**: `GET /dji/api/modeling/models`

**功能描述**: 分页查询指定工作空间的模型文件列表

**请求参数**:
| 参数名 | 类型 | 必填 | 默认值 | 描述 | 示例值 |
|--------|------|------|--------|------|--------|
| page | Integer | 否 | 1 | 页码 | 1 |
| pageSize | Integer | 否 | 10 | 每页大小 | 20 |
| fileType | String | 否 | "all" | 文件类型过滤 | "glb" |
| workspaceId | String | 是 | - | 工作空间ID | "default" |

**文件类型过滤选项**:
- `all`: 所有类型
- `glb`: GLB格式
- `gltf`: GLTF格式
- `b3dm`: B3DM格式
- `3dtiles`: 3D Tiles格式

**请求示例**:
```bash
curl -X GET "http://localhost:8080/dji/api/modeling/models?page=1&pageSize=10&fileType=glb&workspaceId=default"
```

**响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "records": [
      {
        "id": "a1b2c3d4e5f6g7h8",
        "fileName": "building.glb",
        "fileType": "glb",
        "fileSize": 2048576,
        "uploadTime": "2024-01-15T10:30:00",
        "url": "http://27.11.11.30:9000/3d-model/default/2024/01/a1b2c3d4e5f6g7h8_building.glb",
        "workspaceId": "default",
        "description": "建筑模型文件"
      },
      {
        "id": "b2c3d4e5f6g7h8i9",
        "fileName": "tree.gltf",
        "fileType": "gltf",
        "fileSize": 1024000,
        "uploadTime": "2024-01-15T11:00:00",
        "url": "http://27.11.11.30:9000/3d-model/default/2024/01/b2c3d4e5f6g7h8i9_tree.gltf",
        "workspaceId": "default",
        "description": "树木模型"
      }
    ],
    "total": 25,
    "page": 1,
    "pageSize": 10
  }
}
```

---

### 3. 删除模型文件

**接口地址**: `DELETE /dji/api/modeling/models/{id}`

**功能描述**: 删除指定的模型文件

**路径参数**:
| 参数名 | 类型 | 必填 | 描述 | 示例值 |
|--------|------|------|------|--------|
| id | String | 是 | 文件ID | "a1b2c3d4e5f6g7h8" |

**请求参数**:
| 参数名 | 类型 | 必填 | 描述 | 示例值 |
|--------|------|------|------|--------|
| workspaceId | String | 是 | 工作空间ID | "default" |

**请求示例**:
```bash
curl -X DELETE "http://localhost:8080/dji/api/modeling/models/a1b2c3d4e5f6g7h8?workspaceId=default"
```

**响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": null
}
```

**错误响应**:
```json
{
  "code": 404,
  "message": "删除文件失败: 文件不存在",
  "data": null
}
```

---

### 4. 获取模型下载URL

**接口地址**: `GET /dji/api/modeling/models/{id}/download`

**功能描述**: 获取模型文件的下载链接

**路径参数**:
| 参数名 | 类型 | 必填 | 描述 | 示例值 |
|--------|------|------|------|--------|
| id | String | 是 | 文件ID | "a1b2c3d4e5f6g7h8" |

**请求参数**:
| 参数名 | 类型 | 必填 | 描述 | 示例值 |
|--------|------|------|------|--------|
| workspaceId | String | 是 | 工作空间ID | "default" |

**请求示例**:
```bash
curl -X GET "http://localhost:8080/dji/api/modeling/models/a1b2c3d4e5f6g7h8/download?workspaceId=default"
```

**响应示例**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "downloadUrl": "http://27.11.11.30:9000/3d-model/default/2024/01/a1b2c3d4e5f6g7h8_building.glb?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=..."
  }
}
```

**错误响应**:
```json
{
  "code": 404,
  "message": "获取下载URL失败: 文件不存在",
  "data": null
}
```

---

## 📊 数据模型

### ModelFileDTO - 模型文件信息

| 字段名 | 类型 | 描述 | 示例值 |
|--------|------|------|--------|
| id | String | 文件唯一标识 | "a1b2c3d4e5f6g7h8" |
| fileName | String | 原始文件名 | "building.glb" |
| fileType | String | 文件类型 | "glb" |
| fileSize | Long | 文件大小(字节) | 2048576 |
| uploadTime | LocalDateTime | 上传时间 | "2024-01-15T10:30:00" |
| url | String | 文件访问URL | "http://27.11.11.30:9000/..." |
| workspaceId | String | 工作空间ID | "default" |
| description | String | 文件描述 | "建筑模型文件" |

### ModelListResponse - 模型列表响应

| 字段名 | 类型 | 描述 | 示例值 |
|--------|------|------|--------|
| records | List<ModelFileDTO> | 模型文件列表 | [...] |
| total | Long | 总记录数 | 25 |
| page | Integer | 当前页码 | 1 |
| pageSize | Integer | 每页大小 | 10 |

### DownloadUrlResponse - 下载URL响应

| 字段名 | 类型 | 描述 | 示例值 |
|--------|------|------|--------|
| downloadUrl | String | 下载链接 | "http://27.11.11.30:9000/..." |

---

## 🔒 错误码说明

| 错误码 | 描述 | 解决方案 |
|--------|------|----------|
| 200 | 成功 | - |
| 400 | 请求参数错误 | 检查请求参数格式和必填项 |
| 404 | 资源不存在 | 检查文件ID和工作空间ID |
| 413 | 文件过大 | 文件大小不能超过100MB |
| 415 | 不支持的文件类型 | 只支持glb、gltf、b3dm、3dtiles格式 |
| 500 | 服务器内部错误 | 联系技术支持 |

---

## 🚀 使用示例

### JavaScript/前端示例

```javascript
// 上传文件
async function uploadModel(file, workspaceId, description) {
  const formData = new FormData();
  formData.append('file', file);
  formData.append('workspaceId', workspaceId);
  formData.append('description', description);
  
  const response = await fetch('/dji/api/modeling/models/upload', {
    method: 'POST',
    body: formData
  });
  
  return await response.json();
}

// 获取文件列表
async function getModelList(workspaceId, page = 1, pageSize = 10, fileType = 'all') {
  const params = new URLSearchParams({
    workspaceId,
    page: page.toString(),
    pageSize: pageSize.toString(),
    fileType
  });
  
  const response = await fetch(`/dji/api/modeling/models?${params}`);
  return await response.json();
}

// 删除文件
async function deleteModel(id, workspaceId) {
  const response = await fetch(`/dji/api/modeling/models/${id}?workspaceId=${workspaceId}`, {
    method: 'DELETE'
  });
  
  return await response.json();
}

// 获取下载URL
async function getDownloadUrl(id, workspaceId) {
  const response = await fetch(`/dji/api/modeling/models/${id}/download?workspaceId=${workspaceId}`);
  return await response.json();
}
```

### Java/后端示例

```java
@RestController
public class ModelController {
    
    @Autowired
    private ModelingFileService modelingFileService;
    
    @PostMapping("/upload")
    public HttpResultResponse<ModelFileDTO> upload(
            @RequestParam("file") MultipartFile file,
            @RequestParam("workspaceId") String workspaceId,
            @RequestParam(value = "description", required = false) String description) {
        
        try {
            ModelFileDTO result = modelingFileService.uploadModel(file, workspaceId, description);
            return HttpResultResponse.success(result);
        } catch (Exception e) {
            return HttpResultResponse.errorWithType("上传失败: " + e.getMessage());
        }
    }
}
```

---

## 📝 注意事项

1. **文件格式限制**: 只支持GLB、GLTF、B3DM和3D Tiles格式
2. **文件大小限制**: 单个文件最大100MB
3. **工作空间隔离**: 不同工作空间的文件相互隔离
4. **租户隔离**: 基于租户ID的多租户架构
5. **URL有效期**: 下载URL有时效性，建议及时使用
6. **并发限制**: 建议控制并发上传数量，避免服务器压力过大

---

## 🔧 配置说明

### MinIO配置
```yaml
modeling:
  minio:
    endpoint: http://27.11.11.30:9000
    access-key: your-access-key
    secret-key: your-secret-key
    bucket-name: 3d-model
```

### 数据库配置
```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/drone_p?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai
    username: root
    password: your-password
```

---

## 📞 技术支持

如有问题，请联系开发团队或查看系统日志获取详细错误信息。

**最后更新时间**: 2024-01-15
**版本**: v1.0.0