GameServerManager/开发.md

# API 对接使用指南

## 🚀 快速开始

### 1️⃣ **创建构建任务**

```bash
POST http://localhost:3000/api/build
```

**请求头：**
```json
{
  "Content-Type": "application/json",
  "X-API-Key": "dev-api-key-change-in-production"
}
```

**请求体（Modrinth 整合包）：**
```json
{
  "coreName": "AANobbMI",
  "version": "5.2.5",
  "type": "modrinth"
}
```

或者使用完整 URL：
```json
{
  "coreName": "https://modrinth.com/modpack/fabulously-optimized",
  "version": "latest",
  "type": "modrinth"
}
```

**响应示例：**
```json
{
  "success": true,
  "message": "构建任务已创建",
  "data": {
    "taskId": "e2a4d9f2-2637-4e02-af21-980a44910e44",
    "status": "PROCESSING",
    "message": "任务已创建,正在处理"
  }
}
```

### 2️⃣ **轮询查询任务状态**

```bash
GET http://localhost:3000/api/build/{taskId}
```

**请求头：**
```json
{
  "X-API-Key": "dev-api-key-change-in-production"
}
```

**建议：** 每 3-5 秒查询一次

**响应示例（处理中）：**
```json
{
  "success": true,
  "data": {
    "taskId": "e2a4d9f2-2637-4e02-af21-980a44910e44",
    "status": "PROCESSING",
    "progress": 50,
    "message": "正在下载文件...",
    "activeBuilds": 1,
    "queueSize": 0
  }
}
```

**响应示例（完成）：**
```json
{
  "success": true,
  "data": {
    "taskId": "e2a4d9f2-2637-4e02-af21-980a44910e44",
    "status": "COMPLETED",
    "progress": 100,
    "downloadUrl": "/api/download/47d0y7u45dq",
    "expireTime": "2025-10-27 10:30:55",
    "message": "构建完成"
  }
}
```

### 3️⃣ **下载文件**

**直接使用返回的 downloadUrl：**
```bash
GET http://localhost:3000/api/download/47d0y7u45dq
```

**重要：**
- ✅ **自动缓存**：文件已自动下载并缓存到本地
- ✅ **直接下载**：无需额外 API 调用
- ⏱️ **有效期**：下载链接有效期 24 小时
- 📦 **缓存时间**：Modrinth 整合包缓存 48 小时

---