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

# 固件管理 API 接口文档

## 基本信息

- **Base URL**: `http://localhost:8080`
- **接口前缀**: `/firmware`
- **请求头**:
  - `Accept-Language`: `zh_CN` 或 `en_US`（可选，默认中文）

## 统一响应格式

所有接口返回格式统一为：

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

**字段说明：**
- `code`: 状态码（200-成功，500-失败）
- `message`: 提示消息（支持中英文国际化）
- `data`: 返回的数据
- `success`: 是否成功（true/false）

---

## 1. 根据ID查询固件

**接口描述：** 根据固件ID查询固件详细信息

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

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

**路径参数：**

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

**请求示例：**

```bash
curl -X GET "http://localhost:8080/firmware/1" \
  -H "Accept-Language: zh_CN"
```

**成功响应示例：**

```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "id": 1,
    "firmwareName": "固件 v2.0.0",
    "firmwareSize": 2097152,
    "firmwareDescription": "新版本固件，优化性能",
    "firmwareType": "主控固件",
    "downloadUrl": "https://example.com/firmware/v2.0.0.bin",
    "createTime": "2025-01-15 10:30:00",
    "updateTime": "2025-01-15 10:30:00"
  },
  "success": true
}
```

**失败响应示例：**

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

---

## 2. 分页查询固件列表

**接口描述：** 分页查询固件列表，支持按固件名称和固件类型筛选

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

**请求路径：** `/firmware/page`

**请求参数（Query）：**

| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| current | Long | 否 | 1 | 当前页码 |
| size | Long | 否 | 10 | 每页大小 |
| firmwareName | String | 否 | - | 固件名称（模糊查询） |
| firmwareType | String | 否 | - | 固件类型（精确查询） |

**请求示例：**

```bash
# 查询第1页，每页10条
curl -X GET "http://localhost:8080/firmware/page?current=1&size=10" \
  -H "Accept-Language: zh_CN"

# 按固件名称模糊查询
curl -X GET "http://localhost:8080/firmware/page?current=1&size=10&firmwareName=v2"

# 按固件类型查询
curl -X GET "http://localhost:8080/firmware/page?current=1&size=10&firmwareType=主控固件"

# 组合查询
curl -X GET "http://localhost:8080/firmware/page?current=1&size=10&firmwareName=v2&firmwareType=主控固件"
```

**成功响应示例：**

```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "records": [
      {
        "id": 1,
        "firmwareName": "固件 v2.0.0",
        "firmwareSize": 2097152,
        "firmwareDescription": "新版本固件，优化性能",
        "firmwareType": "主控固件",
        "downloadUrl": "https://example.com/firmware/v2.0.0.bin",
        "createTime": "2025-01-15 10:30:00",
        "updateTime": "2025-01-15 10:30:00"
      },
      {
        "id": 2,
        "firmwareName": "固件 v1.0.1",
        "firmwareSize": 1049600,
        "firmwareDescription": "修复了若干 bug 的版本",
        "firmwareType": "主控固件",
        "downloadUrl": "https://example.com/firmware/v1.0.1.bin",
        "createTime": "2025-01-14 09:20:00",
        "updateTime": "2025-01-14 09:20:00"
      }
    ],
    "total": 2,
    "size": 10,
    "current": 1,
    "pages": 1
  },
  "success": true
}
```

**响应字段说明：**
- `records`: 当前页的数据列表
- `total`: 总记录数
- `size`: 每页大小
- `current`: 当前页码
- `pages`: 总页数

---

## 3. 查询所有固件

**接口描述：** 查询所有固件列表（不分页）

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

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

**请求示例：**

```bash
curl -X GET "http://localhost:8080/firmware/list" \
  -H "Accept-Language: zh_CN"
```

**成功响应示例：**

```json
{
  "code": 200,
  "message": "操作成功",
  "data": [
    {
      "id": 1,
      "firmwareName": "固件 v2.0.0",
      "firmwareSize": 2097152,
      "firmwareDescription": "新版本固件，优化性能",
      "firmwareType": "主控固件",
      "downloadUrl": "https://example.com/firmware/v2.0.0.bin",
      "createTime": "2025-01-15 10:30:00",
      "updateTime": "2025-01-15 10:30:00"
    },
    {
      "id": 2,
      "firmwareName": "固件 v1.0.1",
      "firmwareSize": 1049600,
      "firmwareDescription": "修复了若干 bug 的版本",
      "firmwareType": "主控固件",
      "downloadUrl": "https://example.com/firmware/v1.0.1.bin",
      "createTime": "2025-01-14 09:20:00",
      "updateTime": "2025-01-14 09:20:00"
    }
  ],
  "success": true
}
```

---

## 错误码说明

| 错误码 | 说明 |
|--------|------|
| 200 | 请求成功 |
| 500 | 服务器内部错误 |

---

## 国际化支持

接口支持中英文双语，通过请求头 `Accept-Language` 或 `lang` 指定语言：

- `zh_CN` - 中文（默认）
- `en_US` - 英文

**示例：**

```bash
# 中文响应
curl -X GET "http://localhost:8080/firmware/1" \
  -H "Accept-Language: zh_CN"

# 英文响应
curl -X GET "http://localhost:8080/firmware/1" \
  -H "Accept-Language: en_US"
```

---

## 注意事项

1. **文件大小单位**：`firmwareSize` 字段的单位是字节（Byte）
2. **时间格式**：`createTime` 和 `updateTime` 的格式为 `yyyy-MM-dd HH:mm:ss`
3. **分页默认排序**：分页查询默认按创建时间倒序排列（最新的在前面）
4. **模糊查询**：分页查询中的 `firmwareName` 参数支持模糊匹配
5. **类型查询**：分页查询中的 `firmwareType` 参数是精确匹配
6. **国际化**：通过 `Accept-Language` 请求头可切换中英文响应消息