imetting_backend/sql/README_terminal_update.md

# 客户端管理 - 专用终端类型添加说明

## 概述

本次更新在客户端管理系统中添加了"专用终端"（terminal）大类型，支持 Android 专用终端和单片机（MCU）平台。

## 数据库变更

### 1. 修改表结构

执行 SQL 文件：`add_dedicated_terminal.sql`

```bash
mysql -u [username] -p [database_name] < backend/sql/add_dedicated_terminal.sql
```

**变更内容：**
- 修改 `client_downloads` 表的 `platform_type` 枚举，添加 `terminal` 类型
- 插入两条示例数据：
  - Android 专用终端（platform_type: `terminal`, platform_name: `android`）
  - 单片机固件（platform_type: `terminal`, platform_name: `mcu`）

### 2. 新的平台类型

| platform_type | platform_name | 说明 |
|--------------|--------------|------|
| terminal | android | Android 专用终端 |
| terminal | mcu | 单片机（MCU）固件 |

## API 接口变更

### 1. 新增接口：通过平台类型和平台名称获取最新版本

**接口路径：** `GET /api/downloads/latest/by-platform`

**请求参数：**
- `platform_type` (string, required): 平台类型 (mobile, desktop, terminal)
- `platform_name` (string, required): 具体平台名称

**示例请求：**
```bash
# 获取 Android 专用终端最新版本
curl "http://localhost:8000/api/downloads/latest/by-platform?platform_type=terminal&platform_name=android"

# 获取单片机固件最新版本
curl "http://localhost:8000/api/downloads/latest/by-platform?platform_type=terminal&platform_name=mcu"
```

**返回示例：**
```json
{
  "code": "200",
  "message": "获取成功",
  "data": {
    "id": 7,
    "platform_type": "terminal",
    "platform_name": "android",
    "version": "1.0.0",
    "version_code": 1000,
    "download_url": "https://download.imeeting.com/terminals/android/iMeeting-Terminal-1.0.0.apk",
    "file_size": 25165824,
    "release_notes": "专用终端初始版本\n- 支持专用硬件集成\n- 优化的录音功能\n- 低功耗模式\n- 自动上传同步",
    "is_active": true,
    "is_latest": true,
    "min_system_version": "Android 5.0",
    "created_at": "2025-01-15T10:00:00",
    "updated_at": "2025-01-15T10:00:00",
    "created_by": 1
  }
}
```

### 2. 更新接口：获取所有平台最新版本

**接口路径：** `GET /api/downloads/latest`

**变更：** 返回数据中新增 `terminal` 字段

**返回示例：**
```json
{
  "code": "200",
  "message": "获取成功",
  "data": {
    "mobile": [...],
    "desktop": [...],
    "terminal": [
      {
        "id": 7,
        "platform_type": "terminal",
        "platform_name": "android",
        "version": "1.0.0",
        ...
      },
      {
        "id": 8,
        "platform_type": "terminal",
        "platform_name": "mcu",
        "version": "1.0.0",
        ...
      }
    ]
  }
}
```

### 3. 已有接口说明

**原有接口：** `GET /api/downloads/{platform_name}/latest`

- 此接口标记为【已废弃】，建议使用新接口 `/downloads/latest/by-platform`
- 原因：只通过 `platform_name` 查询可能产生歧义（如 mobile 的 android 和 terminal 的 android）
- 保留此接口是为了向后兼容，但新开发应使用新接口

## 使用场景

### 场景 1：专用终端设备版本检查

专用终端设备（如会议室固定录音设备、单片机硬件）启动时检查更新：

```javascript
// Android 专用终端
const response = await fetch(
  '/api/downloads/latest/by-platform?platform_type=terminal&platform_name=android'
);
const { data } = await response.json();

if (data.version_code > currentVersionCode) {
  // 发现新版本，提示更新
  showUpdateDialog(data);
}
```

### 场景 2：后台管理界面展示

管理员查看所有终端版本：

```javascript
const response = await fetch('/api/downloads?platform_type=terminal');
const { data } = await response.json();

// data.clients 包含所有 terminal 类型的客户端版本
renderClientList(data.clients);
```

### 场景 3：固件更新服务器

单片机设备定期轮询更新：

```c
// MCU 固件代码示例
char url[] = "http://api.imeeting.com/downloads/latest/by-platform?platform_type=terminal&platform_name=mcu";
http_get(url, response_buffer);

// 解析 JSON 获取 download_url 和 version_code
if (new_version > FIRMWARE_VERSION) {
    download_and_update(download_url);
}
```

## 测试建议

### 1. 数据库测试
```sql
-- 验证表结构修改
DESCRIBE client_downloads;

-- 验证数据插入
SELECT * FROM client_downloads WHERE platform_type = 'terminal';
```

### 2. API 测试
```bash
# 测试新接口
curl "http://localhost:8000/api/downloads/latest/by-platform?platform_type=terminal&platform_name=android"

curl "http://localhost:8000/api/downloads/latest/by-platform?platform_type=terminal&platform_name=mcu"

# 测试获取所有最新版本
curl "http://localhost:8000/api/downloads/latest"

# 测试列表接口
curl "http://localhost:8000/api/downloads?platform_type=terminal"
```

## 注意事项

1. **执行 SQL 前请备份数据库**
2. **ENUM 类型修改**：ALTER TABLE 会修改表结构，请在低峰期执行
3. **新接口优先**：建议所有新开发使用 `/downloads/latest/by-platform` 接口
4. **版本管理**：上传新版本时记得设置 `is_latest=TRUE` 并将同平台旧版本设为 `FALSE`
5. **platform_name 唯一性**：如果 mobile 和 terminal 都有 android，建议：
   - mobile 的保持 `android`
   - terminal 的改为 `android_terminal` 或其他区分名称
   - 或者始终使用新接口同时传递 platform_type 和 platform_name

## 文件清单

- `backend/sql/add_dedicated_terminal.sql` - 数据库迁移 SQL
- `backend/app/api/endpoints/client_downloads.py` - API 接口代码
- `backend/sql/README_terminal_update.md` - 本说明文档