新增：文档体系重构+CHANGELOG补充+发布产物清理

2026-05-01 22:22:06 +08:00
parent 3e1a540b83
commit 6eaaa56eb6
164 changed files with 40346 additions and 64 deletions
--- a/docs/03-模块文档/更新通知/update-notification-design.md
+++ b/docs/03-模块文档/更新通知/update-notification-design.md
@@ -0,0 +1,490 @@
+# 升级提示交互设计文档
+
+## 设计理念
+
+### 核心价值
+将升级从"干扰"转变为"期待"，创造专业、可信、流畅的更新体验。
+
+### 设计原则
+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 最佳实践：
+
+✨ **专业感** - 精美的视觉设计，建立用户信任
+🚀 **流畅感** - 细腻的动画过渡，提升体验
+🎯 **掌控感** - 清晰的进度反馈，用户有掌控权
+🔒 **安全感** - 强制更新保护，跳过选项灵活
+⚡ **高效感** - 后台检测，不干扰工作流
+
+用户将从"被迫更新"的烦恼，转变为"期待更新"的积极体验。