# TalkingQ OTA 固件升级流程

本文档详细描述了TalkingQ设备固件OTA升级的完整流程，涉及到APP、后台服务器和ESP32设备端三方的交互。

## 流程概述

```mermaid
sequenceDiagram
    participant APP
    participant 后台服务器
    participant ESP32设备端

    APP->>后台服务器: /api/ota/check/{device_id}: 检查更新
    后台服务器->>ESP32设备端: WebSocket: GET_FIRMWARE_VERSION
    ESP32设备端->>后台服务器: WebSocket: FIRMWARE_VERSION:{version}
    后台服务器->>后台服务器: 比较版本判断是否需要更新
    后台服务器->>APP: 返回检查结果与版本信息

    alt 不需要更新
        APP->>用户: 提示当前已是最新版本
    else 需要更新
        APP->>后台服务器: /api/ota/start/{device_id}: 发起升级请求
        后台服务器->>ESP32设备端: WebSocket: UPDATE_FIRMWARE:{url}
        ESP32设备端->>ESP32设备端: 下载固件并校验
        ESP32设备端->>后台服务器: WebSocket: FIRMWARE_UPDATE_STATUS
        
        loop 进度更新
            ESP32设备端->>后台服务器: FIRMWARE_UPDATE_STATUS:status=updating,progress=45.5,version=1.0.0
            后台服务器->>后台服务器: 数据库更新升级状态与进度
            APP->>后台服务器: /api/ota/status/{device_id}: 查询升级状态
            后台服务器->>APP: 返回当前升级状态、进度和设备在线状态
            APP->>用户: 显示升级进度
        end
        
        ESP32设备端->>ESP32设备端: 升级完成后重启
        ESP32设备端->>后台服务器: WebSocket重连后上报: FIRMWARE_VERSION:{new_version}
        后台服务器->>后台服务器: 更新设备固件版本记录
        APP->>后台服务器: /api/ota/status/{device_id}: 确认升级完成
        APP->>用户: 提示升级完成
    end
```

## 详细API说明

### 1. 检查更新

**APP → 后台服务器**

```
GET /api/ota/check/{device_id}
Headers:
  X-Device-ID: {device_id}
  X-Device-Serial: {serial_number}
```

**后台服务器 → APP**

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "status": "success",
    "need_update": true|false,
    "current_version": "x.y.z",
    "latest_version": "a.b.c"
  }
}
```

如果出错则返回：

```json
{
  "code": -1,
  "msg": "错误信息",
  "data": {}
}
```

### 2. 启动固件升级

**APP → 后台服务器**

```
POST /api/ota/start/{device_id}
Headers:
  X-Device-ID: {device_id}
  X-Device-Serial: {serial_number}
```

**后台服务器 → APP**

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "updating": true
  }
}
```

### 3. 获取升级状态和进度

**APP → 后台服务器**

```
GET /api/ota/status/{device_id}
Headers:
  X-Device-ID: {device_id}
  X-Device-Serial: {serial_number}
```

**后台服务器 → APP**

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "status": "updating|success|failed|unknown",
    "progress": 45.5,
    "version": "1.0.0",
    "device_online": true|false
  }
}
```

### 4. 管理固件配置信息（管理员接口）

**获取固件配置**

```
GET /api/ota/config/firmware
Headers:
  X-Device-ID: {device_id}
  X-Device-Serial: {serial_number}
```

**设置固件配置**

```
POST /api/ota/config/firmware
Headers:
  X-Device-ID: {device_id}
  X-Device-Serial: {serial_number}
Body:
{
  "version": "1.2.3",
  "url": "https://example.com/firmware/v1.2.3.bin"
}
```

## WebSocket消息格式

### 1. 服务器向设备请求固件版本

```
GET_FIRMWARE_VERSION
```

### 2. 设备返回固件版本

```
FIRMWARE_VERSION:1.0.0
```

### 3. 服务器向设备发送升级指令

```
UPDATE_FIRMWARE:https://example.com/firmware/v1.2.3.bin
```

### 4. 设备上报升级状态

```
FIRMWARE_UPDATE_STATUS:status=updating,progress=45.5,version=1.0.0
```

其中status可以是：
- `updating`: 升级进行中
- `success`: 升级成功完成
- `failed`: 升级失败
- `completed`: 升级完成（等效于success）

## 实现细节

### 固件管理机制

1. **自动扫描固件目录**：系统在启动时会自动扫描 `assets/firmware` 目录，识别所有格式为 `{version}.bin` 的固件文件。

2. **版本识别机制**：固件文件命名必须符合 `x.y.z.bin` 格式，其中 x.y.z 为版本号（例如：`1.2.3.bin`）。

3. **自动更新系统配置**：系统会自动识别最新版本的固件，并更新系统配置中的 `latest_firmware_version` 和 `update_firmware_url`。

4. **简化部署流程**：管理员只需将新固件上传到 `assets/firmware` 目录，系统会自动完成后续配置。

### 后台服务实现特点

1. **版本比较机制**：服务器代码使用特定的版本比较逻辑。当设备版本为`unknown`或`0.0.0`时，会被视为需要更新。

2. **数据库存储**：
   - 使用`DeviceFirmwareUpdate`表记录设备固件版本和更新状态
   - 使用`SystemConfig`表存储最新固件版本(`latest_firmware_version`)和下载URL(`update_firmware_url`)

3. **缓存机制**：设备固件信息使用内存缓存减少数据库查询，缓存有过期时间控制

4. **进度控制**：升级进度以0-100的浮点数表示，由设备上报，服务器保存

5. **设备在线状态**：status接口会返回设备是否在线，通过检查WebSocket连接状态判断

### 注意事项

1. **设备认证**：所有API请求需要设备ID和序列号认证

2. **重启后自动上报**：设备重启后，应在WebSocket连接建立后主动上报固件版本

3. **错误处理**：
   - 设备不在线时，服务器会返回相应的错误信息
   - 版本获取失败时，服务器会尝试等待一段时间后再判断升级状态

4. **进度报告**：
   - 设备应该定期上报升级进度，特别是在状态发生变化时
   - 每个百分比变化或每5%的进度变化应上报一次

5. **安全性**：
   - 固件URL应该是安全的HTTPS链接
   - 设备应验证固件的完整性和来源