imetting/docs/CLIENT_DOWNLOADS_MODULE.md

# 客户端下载管理模块

## 概述

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

## 功能特性

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

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

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

## 数据库设计

### 表结构: `client_downloads`

```sql
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. 数据库初始化

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

### 2. 后端启动

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

### 3. 前端使用

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

```jsx
import ClientManagement from './pages/ClientManagement';

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

#### 在首页添加下载组件:

```jsx
import ClientDownloads from './components/ClientDownloads';

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

## 使用示例

### 管理员创建新版本

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

### 用户下载客户端

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

### 客户端版本检查

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

```javascript
// 检查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