# 升级提示交互设计文档

## 设计理念

### 核心价值
将升级从"干扰"转变为"期待"，创造专业、可信、流畅的更新体验。

### 设计原则
1. **无感检测** - 后台静默检查，不打扰工作流
2. **优雅提示** - 精美的弹窗设计，而非生硬的系统提示
3. **透明反馈** - 清晰的进度展示，让用户掌控全局
4. **安全信任** - 强调版本信息和安全性，建立信任

---

## 交互流程

### 1. 自动检查更新（后台）

```
应用启动
  ↓
等待 3 秒（避免阻塞启动）
  ↓
检查更新配置
  ↓
是否开启自动检查？
  ├─ 否 → 跳过
  └─ 是 → 请求版本信息
      ↓
    版本比较
      ├─ 无更新 → 记录日志
      └─ 有更新 → 检查是否已跳过
          ├─ 已跳过且非强制 → 跳过
          └─ 未跳过或强制更新 → 延迟 2 秒显示弹窗
```

**关键点：**
- ✅ 异步检查，不阻塞应用启动
- ✅ 3 秒延迟，优先显示应用界面
- ✅ 2 秒延迟显示弹窗，让用户先熟悉界面
- ✅ 支持跳过非强制更新

### 2. 升级提示弹窗

#### 弹窗触发时机
- **自动触发**：应用启动检测到新版本（延迟 5 秒）
- **手动触发**：用户在"版本更新"面板点击"检查更新"

#### 弹窗状态

**状态 1：初始显示**
```
┌─────────────────────────────────────────────┐
│ 🔍 发现新版本        v0.1.0 → v0.1.1  [✕]   │
├─────────────────────────────────────────────┤
│                                             │
│ 📅 发布日期    2026-01-28                   │
│ 📁 文件大小    45.2 MB                      │
│                                             │
│ 📖 更新内容                                 │
│ ┌─────────────────────────────────────────┐ │
│ │ • 修复文件列表刷新问题                  │ │
│ │ • 优化启动性能                          │ │
│ │ • 新增暗色模式支持                      │ │
│ └─────────────────────────────────────────┘ │
│                                             │
│  [ 跳过此版本 ]  [ 立即更新 ↓ ]             │
│                                             │
│ ☐ 提醒我稍后更新（下次启动时提醒）          │
└─────────────────────────────────────────────┘
```

**状态 2：下载中**
```
┌─────────────────────────────────────────────┐
│ 🔍 发现新版本        v0.1.0 → v0.1.1  [✕]   │
├─────────────────────────────────────────────┤
│                                             │
│ 📥 下载中...                                │
│ ████████████████░░░░░░░░  65%              │
│ 28.5 MB / 45.2 MB    2.3 MB/s              │
│                                             │
│  [ 跳过此版本 ]  [ 准备中... ]              │
└─────────────────────────────────────────────┘
```

**状态 3：下载完成**
```
┌─────────────────────────────────────────────┐
│ 🔍 发现新版本        v0.1.0 → v0.1.1  [✕]   │
├─────────────────────────────────────────────┤
│                                             │
│ ✅ 下载完成！                               │
│ 文件已保存到：                              │
│ C:\Users\xxx\.u-desk\downloads\update.exe │
│                                             │
│  [ ✓ 下载完成，点击安装 ]                   │
└─────────────────────────────────────────────┘
```

**状态 4：强制更新**
```
┌─────────────────────────────────────────────┐
│ ⚠ 重要更新         v0.1.0 → v0.1.1         │
├─────────────────────────────────────────────┤
│                                             │
│ ⚠️ 此版本包含重要的安全更新和修复，          │
│    建议立即更新以继续使用                   │
│                                             │
│ 📖 更新内容                                 │
│ ┌─────────────────────────────────────────┐ │
│ │ • 修复严重安全漏洞                      │ │
│ │ • 修复数据损坏问题                      │ │
│ └─────────────────────────────────────────┘ │
│                                             │
│  [ 立即更新 ↓ ]                             │
└─────────────────────────────────────────────┘
```

### 3. 用户操作流程

#### 立即更新流程
```
点击"立即更新"
  ↓
开始下载
  ↓
显示下载进度（实时更新）
  ↓
下载完成
  ↓
显示"点击安装"按钮
  ↓
点击"安装"
  ↓
确认对话框
  ↓
开始安装
  ↓
显示"安装中..."
  ↓
安装成功，延迟 2 秒重启应用
```

#### 跳过流程
```
点击"跳过此版本"
  ↓
检查"提醒我稍后更新"
  ├─ 选中 → 保存到 localStorage（skipped_version）
  └─ 未选中 → 清除 localStorage
  ↓
关闭弹窗
  ↓
下次启动时不再提示（除非是强制更新）
```

---

## 视觉设计

### 配色方案

**主要颜色**
- **主色调**：`#165dff` - 专业蓝，代表信任和稳定
- **成功色**：`#00b42a` - 下载成功、安装完成
- **警告色**：`#ff7d00` - 一般更新
- **错误色**：`#f53f3f` - 强制更新、下载失败

**渐变效果**
```css
/* 版本徽章渐变 */
background: linear-gradient(135deg, #165dff 0%, #4facfe 100%);

/* 强制更新徽章渐变 */
background: linear-gradient(135deg, #f53f3f 0%, #ff7875 100%);

/* 弹窗头部渐变 */
background: linear-gradient(135deg, #f0f5ff 0%, #ffffff 100%);
```

### 字体设计

**显示字体**：系统默认（保持一致性）
**代码字体**：`'Menlo', 'Monaco', 'Courier New', monospace`（更新日志）

**字号层级**
```css
版本徽章：15px / 600  /* 主要 CTA */
标题：14px / 600       /* 区块标题 */
正文：14px / 400       /* 内容文字 */
辅助文字：12px / 400   /* 标签、提示 */
小字：13px / 400       /* 代码、日志 */
```

### 间距系统

```css
弹窗内边距：24px
卡片间距：20px
区块间距：16px
元素间距：12px
小间距：8px
```

### 圆角系统

```css
弹窗：8px
卡片/容器：12px
按钮：8px
信息图标：8px
```

### 阴影系统

```css
版本徽章：0 2px 8px rgba(22, 93, 255, 0.3)
信息图标：0 2px 6px rgba(22, 93, 255, 0.2)
```

---

## 动画设计

### 弹窗动画
```css
@keyframes modalFadeIn {
  from {
    opacity: 0;
    transform: scale(0.95) translateY(-20px);
  }
  to {
    opacity: 1;
    transform: scale(1) translateY(0);
  }
}

/* 持续时间：0.3s */
/* 缓动函数：ease-out */
```

### 进度条动画
```css
@keyframes progressPulse {
  0%, 100% { opacity: 1; }
  50% { opacity: 0.8; }
}

/* 持续时间：1.5s */
/* 循环播放 */
```

### 按钮交互
- **Hover**：0.15s 背景色过渡
- **Active**：轻微缩放（scale: 0.98）

---

## 组件结构

```
UpdateNotification.vue
├── 模板层（Template）
│   ├── 弹窗容器（a-modal）
│   ├── 标题栏（自定义）
│   │   ├── 版本徽章（带图标）
│   │   └── 版本对比（当前 → 最新）
│   ├── 内容区域
│   │   ├── 版本信息卡片
│   │   │   ├── 发布日期
│   │   │   └── 文件大小
│   │   ├── 更新日志
│   │   ├── 强制更新提示（条件显示）
│   │   ├── 下载进度（条件显示）
│   │   ├── 操作按钮
│   │   └── 后台更新选项（条件显示）
│
├── 脚本层（Script）
│   ├── Props（modelValue, updateInfo）
│   ├── Emits（update:modelValue, download, install, skip）
│   ├── 状态管理
│   │   ├── 下载状态
│   │   ├── 安装状态
│   │   ├── 进度信息
│   │   └── 用户选择
│   ├── 方法
│   │   ├── handleDownload()
│   │   ├── handleInstall()
│   │   ├── handleSkip()
│   │   ├── 事件监听器（下载进度、完成）
│   │   └── 工具方法（文件大小格式化等）
│   └── 生命周期
│       ├── onMounted（设置事件监听）
│       └── onUnmounted（清理事件监听）
│
└── 样式层（Style）
    ├── 弹窗样式
    ├── 版本徽章
    ├── 信息卡片
    ├── 更新日志
    ├── 进度条
    ├── 按钮样式
    └── 动画效果
```

---

## 后端集成

### API 接口

```javascript
// 检查更新
await window.go.main.App.CheckUpdate()
// 返回: { success: true, data: { has_update, current_version, latest_version, ... } }

// 下载更新
await window.go.main.App.DownloadUpdate(downloadURL)
// 返回: { success: true, data: { message: "下载已开始" } }

// 安装更新
await window.go.main.App.InstallUpdate(filePath, autoRestart)
// 返回: { success: true, data: { success: true, message: "安装成功" } }
```

### 事件系统

```javascript
// 监听下载进度
window.runtime.EventsOn('download-progress', (event) => {
  const data = JSON.parse(event)
  // { progress: 65, speed: 2345678, downloaded: 28576892, total: 45234567 }
})

// 监听下载完成
window.runtime.EventsOn('download-complete', (event) => {
  const data = JSON.parse(event)
  // { success: true, file_path: "xxx", file_size: 45234567 }
})
```

---

## 配置选项

### 用户可配置

在 **设置 → 版本更新** 中：
- ✅ **自动检查更新**：开启/关闭
- ✅ **检查间隔**：1-1440 分钟
- 🔒 **检查地址**：只读（系统配置）

### 版本信息文件格式

```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
}
```

---

## 边界情况处理

### 1. 网络错误
```
检查更新失败 → 记录日志，不显示弹窗
下载失败 → 显示错误提示，允许重试
```

### 2. 下载中断
```
支持断点续传
下次下载从断点继续
```

### 3. 安装失败
```
显示错误信息
自动回滚到备份版本
```

### 4. 用户跳过
```
非强制更新 → 允许跳过
强制更新 → 不允许跳过（禁用关闭按钮）
```

### 5. 版本回退
```
不主动提示降级
如需降级，手动下载安装
```

---

## 可访问性

### 键盘导航
- ✅ Tab 键：切换焦点
- ✅ Enter 键：激活按钮
- ✅ Esc 键：关闭弹窗（非强制更新）

### 屏幕阅读器
- ✅ 语义化 HTML
- ✅ ARIA 标签
- ✅ 清晰的焦点指示器

### 对比度
- ✅ 文字与背景对比度 ≥ 4.5:1
- ✅ 重要信息使用高对比度颜色

---

## 性能优化

### 前端
- ✅ 异步加载组件（按需）
- ✅ 防抖处理（避免频繁更新）
- ✅ 事件监听器及时清理

### 后端
- ✅ 异步下载（不阻塞 UI）
- ✅ 流式下载（支持大文件）
- ✅ 断点续传（节省带宽）

---

## 测试要点

### 功能测试
- ✅ 自动检查更新正常触发
- ✅ 弹窗正确显示版本信息
- ✅ 下载进度实时更新
- ✅ 安装成功后重启
- ✅ 跳过功能正常工作
- ✅ 强制更新无法关闭

### 边界测试
- ✅ 网络断开时的处理
- ✅ 下载失败后的重试
- ✅ 安装失败后的回滚
- ✅ 跳过后不再提示
- ✅ 强制更新必须安装

### UI 测试
- ✅ 弹窗动画流畅
- ✅ 进度条更新平滑
- ✅ 按钮状态正确
- ✅ 响应式布局正常

---

## 未来改进方向

### 短期（1-2 周）
- [ ] 增量更新支持（仅下载差异包）
- [ ] 更新历史记录
- [ ] 更新统计（次数、节省时间）

### 中期（1-2 月）
- [ ] 多渠道更新（稳定版、测试版）
- [ ] 自动更新后台下载
- [ ] 更新预约（定时更新）

### 长期（3-6 月）
- [ ] 智能更新（根据使用习惯）
- [ ] A/B 测试更新策略
- [ ] 用户反馈收集

---

## 总结

这个升级提示系统设计遵循了现代 UX 最佳实践：

✨ **专业感** - 精美的视觉设计，建立用户信任
🚀 **流畅感** - 细腻的动画过渡，提升体验
🎯 **掌控感** - 清晰的进度反馈，用户有掌控权
🔒 **安全感** - 强制更新保护，跳过选项灵活
⚡ **高效感** - 后台检测，不干扰工作流

用户将从"被迫更新"的烦恼，转变为"期待更新"的积极体验。
