mula
/
imetting
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
imetting/docs/CLIENT_DOWNLOADS_MODULE.md

7.2 KiB
Raw Permalink Blame History

客户端下载管理模块

概述

本模块实现了一个完整的客户端下载管理系统,支持移动端(iOS/Android)和桌面端(Windows/Mac/Linux)的版本管理和下载。

功能特性

1. 管理员功能

  • ✅ 创建/编辑/删除客户端版本
  • ✅ 管理版本号和版本代码
  • ✅ 设置最新版本标记
  • ✅ 启用/禁用特定版本
  • ✅ 添加更新说明和系统要求
  • ✅ 平台分类管理(移动端/桌面端)
  • ✅ 搜索和过滤功能

2. 用户功能

  • ✅ 查看所有平台的最新客户端
  • ✅ 按平台分类展示
  • ✅ 显示版本信息和文件大小
  • ✅ 一键下载

3. API功能

  • ✅ 获取所有客户端列表(支持分页和过滤)
  • ✅ 获取最新版本客户端
  • ✅ 按平台获取最新版本(用于客户端版本检查)
  • ✅ CRUD操作(仅管理员)

数据库设计

表结构: client_downloads

CREATE TABLE client_downloads (
    id INT AUTO_INCREMENT PRIMARY KEY,
    platform_type ENUM('mobile', 'desktop') NOT NULL,
    platform_name VARCHAR(50) NOT NULL,
    version VARCHAR(50) NOT NULL,
    version_code INT NOT NULL DEFAULT 1,
    download_url TEXT NOT NULL,
    file_size BIGINT,
    release_notes TEXT,
    is_active BOOLEAN DEFAULT TRUE,
    is_latest BOOLEAN DEFAULT FALSE,
    min_system_version VARCHAR(50),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    created_by INT,
    FOREIGN KEY (created_by) REFERENCES users(user_id) ON DELETE SET NULL,
    INDEX idx_platform (platform_type, platform_name),
    INDEX idx_version (version_code),
    INDEX idx_active (is_active, is_latest)
);

字段说明

  • platform_type: 平台类型(mobile/desktop)
  • platform_name: 具体平台(ios/android/windows/mac_intel/mac_m/linux)
  • version: 版本号字符串(如: 1.0.0)
  • version_code: 版本代码数字(用于版本比较,如: 1000)
  • download_url: 下载链接
  • file_size: 文件大小(字节)
  • release_notes: 更新说明
  • is_active: 是否启用
  • is_latest: 是否为最新版本
  • min_system_version: 最低系统版本要求

API接口

公开接口(无需认证)

1. 获取客户端列表

GET /api/clients/downloads
Query参数:
  - platform_type: mobile|desktop (可选)
  - platform_name: ios|android|windows|mac_intel|mac_m|linux (可选)
  - is_active: true|false (可选)
  - page: 页码 (默认1)
  - size: 每页数量 (默认50)

2. 获取所有最新版本

GET /api/clients/downloads/latest
返回: { mobile: [...], desktop: [...] }

3. 获取指定平台最新版本

GET /api/clients/downloads/{platform_name}/latest
示例: GET /api/clients/downloads/ios/latest

4. 获取指定ID的客户端

GET /api/clients/downloads/{id}

管理员接口(需要管理员权限)

5. 创建客户端版本

POST /api/clients/downloads
Body: {
  "platform_type": "mobile",
  "platform_name": "ios",
  "version": "1.0.0",
  "version_code": 1000,
  "download_url": "https://...",
  "file_size": 52428800,
  "release_notes": "初始版本...",
  "is_active": true,
  "is_latest": false,
  "min_system_version": "iOS 13.0"
}

6. 更新客户端版本

PUT /api/clients/downloads/{id}
Body: {
  "version": "1.0.1",
  "version_code": 1001,
  "is_latest": true,
  ...
}

7. 删除客户端版本

DELETE /api/clients/downloads/{id}

前端组件

1. ClientManagement (管理员页面)

位置: frontend/src/pages/ClientManagement.jsx

功能:

  • 客户端版本CRUD操作
  • 平台筛选和搜索
  • 版本状态管理
  • 响应式卡片布局

2. ClientDownloads (用户下载组件)

位置: frontend/src/components/ClientDownloads.jsx

功能:

  • 展示最新客户端版本
  • 按平台分类
  • 一键下载
  • 可嵌入任何页面

安装和部署

1. 数据库初始化

# 执行SQL文件
mysql -u your_user -p your_database < backend/sql/client_downloads.sql

2. 后端启动

后端会自动加载新的路由,无需额外配置。

3. 前端使用

在管理员页面添加客户端管理:

import ClientManagement from './pages/ClientManagement';

// 在管理员路由中添加
<Route path="/admin/clients" element={<ClientManagement user={user} />} />

在首页添加下载组件:

import ClientDownloads from './components/ClientDownloads';

// 在Dashboard或任何页面中添加
<ClientDownloads />

使用示例

管理员创建新版本

  1. 访问管理后台的"客户端管理"页面
  2. 点击"新增客户端"按钮
  3. 填写版本信息:
    • 选择平台类型和具体平台
    • 输入版本号和版本代码
    • 填写下载链接
    • 添加更新说明
    • 勾选"设为最新版本"(如果是最新)
  4. 点击"创建"保存

用户下载客户端

  1. 在首页查看"下载客户端"区域
  2. 选择对应平台
  3. 点击卡片即可下载

客户端版本检查

客户端可以调用API检查是否有新版本:

// 检查iOS最新版本
const response = await fetch('/api/clients/downloads/ios/latest');
const latest = await response.json();

if (latest.data.version_code > currentVersionCode) {
  // 提示用户更新
  showUpdateDialog(latest.data);
}

版本号规范

  • 版本号: 采用语义化版本(Semantic Versioning),格式: 主版本.次版本.修订号

    • 例如: 1.0.0, 1.2.3, 2.0.0

  • 版本代码: 纯数字,用于程序化比较

    • 推荐格式: 主版本(2位) + 次版本(2位) + 修订号(2位)
    • 例如: 1.0.0 -> 10000, 1.2.3 -> 10203, 2.0.0 -> 20000

平台支持

移动端

  • iOS: App Store链接或企业分发链接
  • Android: Google Play链接或APK直接下载

桌面端

  • Windows: .exe安装包
  • Mac (Intel): Intel架构的.dmg安装包
  • Mac (M系列): Apple Silicon原生支持的.dmg安装包
  • Linux: .AppImage或.deb/.rpm包

注意事项

  1. 下载链接: 确保下载链接长期有效,建议使用CDN或对象存储
  2. 文件大小: 建议填写准确的文件大小,方便用户了解下载时间
  3. 版本管理:
    • 同一平台只能有一个"最新版本"
    • 设置新版本为最新时,会自动将旧版本的最新标记<E6A087><E8AEB0>除
  4. 权限控制: CRUD操作仅管理员可执行,查询接口公开访问

扩展建议

  1. 统计功能: 添加下载次数统计
  2. 发布计划: 支持定时发布新版本
  3. 灰度发布: 按百分比或用户组逐步推送新版本
  4. 更新检查: 提供SDK方便客户端集成版本检查
  5. 更新强制: 支持强制更新标记

文件清单

后端

  • backend/sql/client_downloads.sql - 数据库表结构和初始数据
  • backend/app/models/models.py - Pydantic数据模型
  • backend/app/api/endpoints/client_downloads.py - API路由和业务逻辑
  • backend/main.py - 路由注册

前端

  • frontend/src/pages/ClientManagement.jsx - 管理员管理页面
  • frontend/src/pages/ClientManagement.css - 管理页面样式
  • frontend/src/components/ClientDownloads.jsx - 用户下载组件
  • frontend/src/components/ClientDownloads.css - 下载组件样式
  • frontend/src/config/api.js - API配置

技术栈

后端

  • FastAPI
  • MySQL
  • Pydantic

前端

  • React
  • Lucide React Icons
  • CSS3

作者

Generated with Claude Code