core_wing_web/docs/API接口说明-Sirius固件版本管理.md

# Sirius 固件 API 接口文档

## 基本信息

- **Base URL**: `https://api.corewing.com`
- **接口前缀**: `/sirius_firmware`

## 统一响应格式

```json
{
  "code": 200,
  "message": "操作成功",
  "data": {},
  "success": true
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| code | Integer | 状态码（200 成功，500 失败） |
| message | String | 提示消息 |
| data | Object | 返回数据 |
| success | Boolean | 是否成功 |

## 枚举说明

### 固件类型（firmwareType）

| 值 | 说明 |
|----|------|
| 1 | 高频头 |
| 2 | 接收机 |
| 3 | 背包 |

### 协议类型（protocolType）

| 值 | 说明 |
|----|------|
| 1 | ELRS |
| 2 | CWLink |

## 固件对象字段说明

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Integer | 主键ID |
| firmwareType | Integer | 固件类型：1-高频头，2-接收机，3-背包 |
| protocolType | Integer | 协议类型：1-ELRS，2-CWLink |
| versionNumber | String | 版本号，如 v3.0.1 |
| fileName | String | 文件名 |
| filePath | String | 文件存储路径 |
| fileSize | Long | 文件大小（字节） |
| md5Hash | String | MD5 校验值 |
| releaseNotes | String | 版本更新说明（可能为 null） |
| createTime | String | 创建时间 |
| updateTime | String | 更新时间 |

---

## 1. 查询最新固件版本

**接口描述：** 根据固件类型和协议类型查询最新版本，用于设备端检查更新。

**请求方式：** `GET`

**请求路径：** `/sirius_firmware/latest`

**请求参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| firmwareType | Integer | 是 | 固件类型：1-高频头，2-接收机，3-背包 |
| protocolType | Integer | 是 | 协议类型：1-ELRS，2-CWLink |

**请求示例：**

```bash
curl -X GET "http://your-server-host:8080/sirius_firmware/latest?firmwareType=1&protocolType=1"
```

**成功响应示例：**

```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "id": 1,
    "firmwareType": 1,
    "protocolType": 1,
    "versionNumber": "v3.0.1",
    "fileName": "sirius_hf_elrs_v3.0.1.bin",
    "filePath": "https://oss.corewing.com/sirius_firmware/sirius_hf_elrs_v3.0.1.bin",
    "fileSize": 1048576,
    "md5Hash": "d41d8cd98f00b204e9800998ecf8427e",
    "releaseNotes": "优化信号连接稳定性",
    "createTime": "2026-03-10 10:30:00",
    "updateTime": "2026-03-10 10:30:00"
  },
  "success": true
}
```

**失败响应示例：**

```json
{
  "code": 500,
  "message": "固件不存在",
  "data": null,
  "success": false
}
```

---

## 2. 根据固件类型查询版本列表

**接口描述：** 查询指定固件类型下所有版本，按时间倒序排列。

**请求方式：** `GET`

**请求路径：** `/sirius_firmware/type/{firmwareType}`

**路径参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| firmwareType | Integer | 是 | 固件类型：1-高频头，2-接收机，3-背包 |

**请求示例：**

```bash
curl -X GET "http://your-server-host:8080/sirius_firmware/type/1"
```

**成功响应示例：**

```json
{
  "code": 200,
  "message": "操作成功",
  "data": [
    {
      "id": 3,
      "firmwareType": 1,
      "protocolType": 2,
      "versionNumber": "v2.1.0",
      "fileName": "sirius_hf_cwlink_v2.1.0.bin",
      "filePath": "https://oss.corewing.com/sirius_firmware/sirius_hf_cwlink_v2.1.0.bin",
      "fileSize": 2097152,
      "md5Hash": "098f6bcd4621d373cade4e832627b4f6",
      "releaseNotes": "新增CWLink协议支持",
      "createTime": "2026-03-12 14:00:00",
      "updateTime": "2026-03-12 14:00:00"
    },
    {
      "id": 1,
      "firmwareType": 1,
      "protocolType": 1,
      "versionNumber": "v3.0.1",
      "fileName": "sirius_hf_elrs_v3.0.1.bin",
      "filePath": "https://oss.corewing.com/sirius_firmware/sirius_hf_elrs_v3.0.1.bin",
      "fileSize": 1048576,
      "md5Hash": "d41d8cd98f00b204e9800998ecf8427e",
      "releaseNotes": "优化信号连接稳定性",
      "createTime": "2026-03-10 10:30:00",
      "updateTime": "2026-03-10 10:30:00"
    }
  ],
  "success": true
}
```

---

## 3. 根据固件类型和协议类型查询版本列表

**接口描述：** 查询指定固件类型和协议类型下所有版本，按时间倒序排列。

**请求方式：** `GET`

**请求路径：** `/sirius_firmware/type/{firmwareType}/protocol/{protocolType}`

**路径参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| firmwareType | Integer | 是 | 固件类型：1-高频头，2-接收机，3-背包 |
| protocolType | Integer | 是 | 协议类型：1-ELRS，2-CWLink |

**请求示例：**

```bash
curl -X GET "http://your-server-host:8080/sirius_firmware/type/1/protocol/1"
```

**成功响应示例：**

```json
{
  "code": 200,
  "message": "操作成功",
  "data": [
    {
      "id": 5,
      "firmwareType": 1,
      "protocolType": 1,
      "versionNumber": "v3.0.1",
      "fileName": "sirius_hf_elrs_v3.0.1.bin",
      "filePath": "https://oss.corewing.com/sirius_firmware/sirius_hf_elrs_v3.0.1.bin",
      "fileSize": 1048576,
      "md5Hash": "d41d8cd98f00b204e9800998ecf8427e",
      "releaseNotes": "优化信号连接稳定性",
      "createTime": "2026-03-12 14:00:00",
      "updateTime": "2026-03-12 14:00:00"
    },
    {
      "id": 2,
      "firmwareType": 1,
      "protocolType": 1,
      "versionNumber": "v3.0.0",
      "fileName": "sirius_hf_elrs_v3.0.0.bin",
      "filePath": "https://oss.corewing.com/sirius_firmware/sirius_hf_elrs_v3.0.0.bin",
      "fileSize": 1024000,
      "md5Hash": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
      "releaseNotes": null,
      "createTime": "2026-03-01 08:00:00",
      "updateTime": "2026-03-01 08:00:00"
    }
  ],
  "success": true
}
```

---

## 4. 查询所有固件

**接口描述：** 查询所有固件记录。

**请求方式：** `GET`

**请求路径：** `/sirius_firmware/list`

**请求示例：**

```bash
curl -X GET "http://your-server-host:8080/sirius_firmware/list"
```

**成功响应示例：**

```json
{
  "code": 200,
  "message": "操作成功",
  "data": [
    {
      "id": 1,
      "firmwareType": 1,
      "protocolType": 1,
      "versionNumber": "v3.0.1",
      "fileName": "sirius_hf_elrs_v3.0.1.bin",
      "filePath": "https://oss.corewing.com/sirius_firmware/sirius_hf_elrs_v3.0.1.bin",
      "fileSize": 1048576,
      "md5Hash": "d41d8cd98f00b204e9800998ecf8427e",
      "releaseNotes": "优化信号连接稳定性",
      "createTime": "2026-03-10 10:30:00",
      "updateTime": "2026-03-10 10:30:00"
    }
  ],
  "success": true
}
```

---

## 5. 根据ID查询固件

**接口描述：** 根据固件ID查询详情。

**请求方式：** `GET`

**请求路径：** `/sirius_firmware/{id}`

**路径参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | Integer | 是 | 固件ID |

**请求示例：**

```bash
curl -X GET "http://your-server-host:8080/sirius_firmware/1"
```

**成功响应示例：**

```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "id": 1,
    "firmwareType": 1,
    "protocolType": 1,
    "versionNumber": "v3.0.1",
    "fileName": "sirius_hf_elrs_v3.0.1.bin",
    "filePath": "https://oss.corewing.com/sirius_firmware/sirius_hf_elrs_v3.0.1.bin",
    "fileSize": 1048576,
    "md5Hash": "d41d8cd98f00b204e9800998ecf8427e",
    "releaseNotes": "优化信号连接稳定性",
    "createTime": "2026-03-10 10:30:00",
    "updateTime": "2026-03-10 10:30:00"
  },
  "success": true
}
```

**失败响应示例：**

```json
{
  "code": 500,
  "message": "固件不存在",
  "data": null,
  "success": false
}
```

---

## 接口总览

| 方法 | 路径 | 说明 | 使用场景 |
|------|------|------|----------|
| GET | `/sirius_firmware/latest?firmwareType=&protocolType=` | 查询最新版本 | 设备端检查更新 |
| GET | `/sirius_firmware/type/{firmwareType}` | 按固件类型查版本列表 | 查看某类固件所有版本 |
| GET | `/sirius_firmware/type/{firmwareType}/protocol/{protocolType}` | 按类型+协议查版本列表 | 精确筛选版本列表 |
| GET | `/sirius_firmware/list` | 查询所有固件 | 管理端展示全部数据 |
| GET | `/sirius_firmware/{id}` | 按ID查询固件 | 查看固件详情 |

---