5.7 KiB

Raw Blame History

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

概述

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

数据库变更

1. 修改表结构

执行 SQL 文件：add_dedicated_terminal.sql

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): 具体平台名称

示例请求：

# 获取 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"

返回示例：

{
  "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 字段

返回示例：

{
  "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：专用终端设备版本检查

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

// 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：后台管理界面展示

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

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

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

场景 3：固件更新服务器

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

// 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. 数据库测试

-- 验证表结构修改
DESCRIBE client_downloads;

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

2. API 测试

# 测试新接口
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"

注意事项

执行 SQL 前请备份数据库
ENUM 类型修改：ALTER TABLE 会修改表结构，请在低峰期执行
新接口优先：建议所有新开发使用 /downloads/latest/by-platform 接口
版本管理：上传新版本时记得设置 is_latest=TRUE 并将同平台旧版本设为 FALSE
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 - 本说明文档

5.7 KiB Raw Blame History Unescape Escape