# 升级提示功能使用指南

## 功能概述

新增的升级提示系统会在应用启动时自动检查更新，并在发现新版本时优雅地提示用户。整个体验流畅、专业，不打扰用户工作流。

## 主要特性

✅ **自动检测** - 应用启动后 5 秒自动检查更新
✅ **优雅提示** - 精美的弹窗设计，清晰的版本信息
✅ **实时进度** - 下载进度实时显示，包含速度和文件大小
✅ **灵活跳过** - 支持跳过非强制更新，下次不再提示
✅ **强制更新** - 重要安全更新强制安装，无法跳过
✅ **断点续传** - 下载支持断点续传，节省流量
✅ **安全安装** - 自动备份原程序，失败自动回滚

## 使用流程

### 1. 应用启动自动检查

```
应用启动
  ↓
等待 3 秒（避免阻塞启动）
  ↓
后台检查更新
  ↓
发现新版本？
  ├─ 是 → 延迟 2 秒显示升级提示弹窗
  └─ 否 → 不显示，正常使用应用
```

### 2. 升级提示弹窗

当检测到新版本时，会显示精美的升级提示弹窗：

**弹窗包含：**
- 📌 当前版本 → 最新版本对比
- 📅 发布日期
- 📁 文件大小
- 📖 更新日志（版本更新内容）
- 🎯 操作按钮（跳过/立即更新）
- ⏰ 稍后提醒选项

**三种状态：**
1. **初始状态** - 显示版本信息和更新日志
2. **下载状态** - 显示下载进度和速度
3. **完成状态** - 下载完成，提示点击安装

### 3. 用户选择

#### 选择 A：立即更新
```
点击"立即更新"
  ↓
开始下载（显示进度条）
  ↓
下载完成
  ↓
点击"安装"
  ↓
确认对话框
  ↓
自动重启应用
```

#### 选择 B：跳过此版本
```
点击"跳过此版本"
  ↓
勾选"提醒我稍后更新"？
  ├─ 是 → 下次启动继续提示
  └─ 否 → 记住选择，不再提示此版本
  ↓
关闭弹窗
```

### 4. 强制更新

对于重要的安全更新，弹窗会：
- 🔴 显示红色"重要更新"徽章
- ⚠️ 显示强制更新警告信息
- 🚫 禁用关闭按钮（无法跳过）
- ✅ 只提供"立即更新"按钮

## 配置选项

### 在"设置 → 版本更新"中配置：

#### 自动检查更新
- **开启** - 应用启动时自动检查（推荐）
- **关闭** - 不自动检查，需要手动检查

#### 检查间隔
- 范围：1-1440 分钟（1 分钟 - 24 小时）
- 推荐设置：60 分钟（1 小时）
- 说明：两次自动检查的最小间隔时间

#### 更新检查地址
- 系统配置，不可修改
- 当前地址：`https://img.1216.top/u-desk/last-version.json`

## 手动检查更新

如果关闭了自动检查，或者想立即检查：

1. 打开"设置"面板
2. 切换到"版本更新"标签
3. 点击"检查更新"按钮
4. 查看更新结果

## 版本信息文件

升级系统会读取远程的版本信息文件：

**文件地址：** `https://img.1216.top/u-desk/last-version.json`

**文件格式：**
```json
{
  "version": "0.1.1",
  "download_url": "https://img.1216.top/u-desk/go-desk-0.1.1-windows-amd64.exe",
  "changelog": "• 修复文件列表刷新问题\n• 优化启动性能\n• 新增暗色模式支持",
  "force_update": false,
  "release_date": "2026-01-28",
  "file_size": 45234567
}
```

**字段说明：**
- `version` - 最新版本号（格式：x.y.z）
- `download_url` - 安装包下载地址
- `changelog` - 更新日志（支持换行符 `\n`）
- `force_update` - 是否强制更新（true/false）
- `release_date` - 发布日期（格式：YYYY-MM-DD）
- `file_size` - 文件大小（字节，可选）

## 下载和安装

### 下载特性
- ✅ 支持断点续传（中断后可继续）
- ✅ 实时显示下载进度
- ✅ 显示下载速度和剩余时间
- ✅ 下载完成后自动计算 MD5 和 SHA256 哈希

### 安装特性
- ✅ 自动备份当前版本
- ✅ 安装失败自动回滚
- ✅ 安装成功自动重启
- ✅ 支持 .exe 和 .zip 格式

### 文件存储位置
- **配置文件**：`~/.u-desk/update_config.json`
- **下载目录**：`~/.u-desk/downloads/`
- **备份目录**：`~/.u-desk/backups/`

## 常见问题

### Q1: 为什么自动检查更新后没有弹窗？
**A:** 可能原因：
1. 已是最新版本（无更新）
2. 此版本已选择"跳过"且未勾选"稍后提醒"
3. 自动检查功能已关闭

**解决方法：**
- 手动点击"检查更新"按钮
- 检查配置中的"自动检查更新"开关

### Q2: 下载失败了怎么办？
**A:**
- 下载支持断点续传，可以点击重试
- 系统会自动从断点继续下载
- 如果多次失败，检查网络连接和下载地址

### Q3: 安装失败会怎样？
**A:**
- 系统会自动回滚到备份版本
- 不会影响当前使用
- 可以查看错误日志了解失败原因

### Q4: 如何恢复跳过的版本提示？
**A:**
方法 1：手动点击"检查更新"
方法 2：清除浏览器 localStorage 中的 `skipped_version`

### Q5: 强制更新可以跳过吗？
**A:**
- 不可以。强制更新是为了修复严重的安全问题或数据损坏问题
- 不安装强制更新可能会影响应用正常使用

### Q6: 下载中断后下次如何继续？
**A:**
- 系统会自动检测已下载的部分
- 重新点击"立即更新"会从断点继续
- 不会重复下载已完成的文件

## 技术实现

### 前端组件
- **UpdateNotification.vue** - 升级提示弹窗组件
- **App.vue** - 集成自动检查逻辑

### 后端接口
- **CheckUpdate()** - 检查更新
- **DownloadUpdate()** - 下载更新包
- **InstallUpdate()** - 安装更新
- **GetUpdateConfig()** - 获取更新配置
- **SetUpdateConfig()** - 保存更新配置

### 事件系统
- **download-progress** - 下载进度事件
- **download-complete** - 下载完成事件

### 配置文件
**~/.u-desk/update_config.json**
```json
{
  "current_version": "0.1.0",
  "last_check_time": "2026-01-28T18:51:00+08:00",
  "auto_check_enabled": true,
  "check_interval_minutes": 60,
  "check_url": "https://img.1216.top/u-desk/last-version.json"
}
```

## 最佳实践

### 对于用户
1. ✅ 保持自动检查开启，及时获取更新
2. ✅ 选择"稍后提醒"而非"跳过"，避免错过重要更新
3. ✅ 安装前保存当前工作，避免数据丢失
4. ✅ 遇到强制更新立即安装，确保安全性

### 对于开发者
1. ✅ 版本信息文件保持最新
2. ✅ 更新日志清晰详细
3. ✅ 重要更新标记为强制更新
4. ✅ 测试安装包的完整性

## 更新日志设计建议

### 好的更新日志
```
• 修复文件列表刷新后顺序错乱的问题
• 优化启动性能，加载时间减少 30%
• 新增暗色模式支持
• 修复 #123 问题：数据库连接失败

注意：此版本包含重要的安全修复，建议立即更新
```

### 不好的更新日志
```
bug fixes
performance improvements
new features
```

**建议：**
- ✅ 列出具体的改动
- ✅ 说明对用户的影响
- ✅ 标注重要性和紧急性
- ✅ 使用清晰的格式（项目符号）

---

## 总结

新的升级提示系统提供了专业、流畅、友好的更新体验：

🎯 **自动化** - 后台检查，无需人工干预
💎 **精美设计** - 现代化的 UI，清晰的信息层次
⚡ **高效流畅** - 断点续传，实时进度
🔒 **安全可靠** - 备份回滚，哈希验证
👍 **用户友好** - 灵活跳过，稍后提醒

享受无缝的更新体验！