.

2026-01-14 14:17:38 +08:00
commit f1e2ff6563
126 changed files with 13636 additions and 0 deletions
--- a/docs/04-功能迭代/版本更新/last-version.json
+++ b/docs/04-功能迭代/版本更新/last-version.json
@@ -0,0 +1,7 @@
+{
+  "version": "0.1.1",
+  "download_url": "https://img.1216.top/ssq/releases/ssq-desk-0.1.1.exe",
+  "changelog": "更新日志内容",
+  "force_update": false,
+  "release_date": "2026-01-07"
+}
--- a/docs/04-功能迭代/版本更新/任务规划.md
+++ b/docs/04-功能迭代/版本更新/任务规划.md
@@ -0,0 +1,347 @@
+# 版本更新功能任务规划
+
+> 设计文档请参考：[版本更新设计.md](./版本更新设计.md)
+
+---
+
+## 2. 任务分解与实现检查
+
+### 2.1 版本号管理
+
+#### T2.1.1 版本号定义和解析
+- **任务描述**：定义版本号格式和解析逻辑
+- **技术要点**：
+  - 版本号格式：`v1.0.0` 或 `1.0.0`（语义化版本）
+  - 版本号比较逻辑（主版本号.次版本号.修订号）
+  - 当前版本号读取（从 `wails.json` 或编译时注入）
+- **依赖**：无
+- **优先级**：P0
+- **实现状态**：✅ 已实现
+- **实现位置**：`internal/service/version.go`
+- **检查结果**：
+  - ✅ 版本号解析：`ParseVersion()` 支持 `v1.0.0` 或 `1.0.0` 格式
+  - ✅ 版本比较：`Version.Compare()` 实现语义化版本比较
+
+#### T2.1.2 版本信息存储
+- **任务描述**：本地存储版本信息
+- **技术要点**：
+  - 当前版本号存储
+  - 上次检查更新时间记录
+  - 更新检查配置（自动检查开关）
+- **依赖**：T2.1.1
+- **优先级**：P0
+- **实现状态**：✅ 已实现
+- **实现位置**：`internal/service/update_config.go`
+
+### 2.2 更新检查功能
+
+#### T2.2.1 远程版本检查服务
+- **任务描述**：实现远程版本检查接口
+- **技术要点**：
+  - 远程版本信息接口（JSON 格式）
+  - 版本号比较逻辑
+  - 网络请求和错误处理
+  - 超时控制
+- **依赖**：T2.1.1
+- **优先级**：P0
+- **实现状态**：✅ 已实现
+- **实现位置**：`internal/service/update_service.go`
+- **检查结果**：
+  - ✅ 远程版本信息接口：`fetchRemoteVersionInfo()` 通过 HTTP GET 获取 JSON
+  - ✅ 检查频率控制：`UpdateConfig.ShouldCheckUpdate()` 基于时间间隔判断
+
+#### T2.2.2 更新检查触发机制
+- **任务描述**：实现更新检查触发方式
+- **技术要点**：
+  - **启动时检查**：应用启动时立即检查一次（已实现）
+  - **自动检查**：根据配置的检查间隔自动检查（已实现）
+  - **手动检查**：用户手动触发检查更新按钮
+  - **检查频率控制**：避免频繁请求，支持可配置间隔（已实现）
+- **依赖**：T2.2.1
+- **优先级**：P0
+- **实现状态**：✅ 已实现
+- **实现位置**：`internal/module/update_module.go`
+- **检查结果**：
+  - ✅ 启动检查：`update_module.go` 在 `Start()` 方法中触发检查
+
+#### T2.2.3 更新提示界面
+- **任务描述**：前端展示更新提示
+- **技术要点**：
+  - 发现新版本时弹窗提示
+  - 显示当前版本和最新版本号
+  - 更新日志预览
+  - 立即更新/稍后提醒按钮
+- **依赖**：T2.2.2
+- **优先级**：P0
+- **实现状态**：✅ 已实现
+- **实现位置**：`web/src/composables/useVersion.ts`
+
+### 2.3 更新下载功能
+
+#### T2.3.1 更新包下载服务
+- **任务描述**：实现更新包下载逻辑
+- **技术要点**：
+  - 更新包下载 URL 获取
+  - 文件下载（支持断点续传）
+  - 下载进度计算和回调
+  - 下载文件校验（MD5/SHA256）
+- **依赖**：T2.2.1
+- **优先级**：P0
+- **实现状态**：✅ 已实现
+- **实现位置**：`internal/service/update_download.go`
+- **检查结果**：
+  - ✅ 断点续传：使用 HTTP `Range` 头，支持从断点继续下载
+  - ✅ 文件完整性验证：`calculateFileHashes()` 计算 MD5 和 SHA256
+  - ✅ 下载目录管理：使用 `~/.ssq-desk/downloads` 目录
+- **代码优化**（2026-01-08）：
+  - ✅ 提取 `getRemoteFileSize()` 函数，消除重复的 HEAD 请求逻辑
+  - ✅ 提取 `normalizeProgress()` 函数，统一进度值标准化
+  - ✅ 精简日志输出，仅保留关键错误日志
+  - ✅ 代码量减少约 45%
+
+#### T2.3.2 下载进度展示
+- **任务描述**：前端展示下载进度
+- **技术要点**：
+  - 下载进度条显示
+  - 下载速度显示
+  - 下载状态提示（下载中/暂停/完成/失败）
+  - 进度值安全控制（确保在 0-100% 之间）
+- **依赖**：T2.3.1
+- **优先级**：P0
+- **实现状态**：✅ 已实现（2026-01-08 优化：添加多层进度值保护）
+- **实现位置**：`web/src/composables/useVersion.ts`
+- **检查结果**：
+  - ✅ 进度反馈：`DownloadProgress` 回调函数，每 0.3 秒更新一次
+  - ✅ 进度值控制：多层防护确保进度值严格在 0-100% 之间
+    - 后端 `normalizeProgress()` 函数标准化进度值
+    - API 层最后一道防线检查
+    - 前端 `clampProgress()` 函数确保显示值合法
+- **代码优化**（2026-01-08）：
+  - ✅ 提取 `clampProgress()` 辅助函数，统一进度值标准化
+  - ✅ 提取 `resetDownloadState()` 函数，消除重复代码
+  - ✅ 提取 `installUpdate()` 函数，简化安装逻辑
+  - ✅ 代码量从 485 行减少到约 300 行（减少约 40%）
+
+### 2.4 更新安装功能
+
+#### T2.4.1 更新包安装逻辑
+- **任务描述**：实现更新包安装
+- **技术要点**：
+  - 更新包解压/安装
+  - 安装前备份当前版本
+  - 安装后重启应用
+  - 安装失败回滚机制
+- **依赖**：T2.3.1
+- **优先级**：P0
+- **实现状态**：✅ 已实现
+- **实现位置**：`internal/service/update_install.go`
+- **检查结果**：
+  - ✅ 安装前备份：`BackupApplication()` 在安装前创建备份
+  - ✅ 安装失败回滚：`rollbackFromBackup()` 在安装失败时恢复备份
+  - ✅ 多格式支持：支持 `.exe` 和 `.zip` 两种格式
+  - ✅ 自动重启：`restartApplication()` 支持 Windows/macOS/Linux
+- **潜在问题**：
+  - ⚠️ Windows 下替换正在运行的可执行文件：当前实现使用重命名方式（`.old` 后缀），但可能在某些情况下失败
+- **代码优化**（2026-01-08）：
+  - ✅ 移除所有调试日志
+  - ✅ 代码量减少约 30%
+
+#### T2.4.2 安装方式选择
+- **任务描述**：支持自动和手动安装
+- **技术要点**：
+  - 自动安装：下载完成后自动安装
+  - 手动安装：用户确认后安装
+  - 安装时机选择（立即安装/退出时安装）
+- **依赖**：T2.4.1
+- **优先级**：P1
+- **实现状态**：✅ 已实现（自动安装）
+
+### 2.5 更新日志展示
+
+#### T2.5.1 更新日志获取
+- **任务描述**：获取和解析更新日志
+- **技术要点**：
+  - 更新日志接口（Markdown 或 HTML 格式）
+  - 日志版本关联
+  - 日志内容解析和格式化
+- **依赖**：T2.2.1
+- **优先级**：P1
+- **实现状态**：✅ 已实现（从版本信息接口获取）
+
+#### T2.5.2 更新日志界面
+- **任务描述**：前端展示更新日志
+- **技术要点**：
+  - 更新日志弹窗/页面
+  - Markdown 渲染（如需要）
+  - 版本历史列表
+  - 日志内容展示
+- **依赖**：T2.5.1
+- **优先级**：P1
+- **实现状态**：✅ 已实现（在更新提示对话框中显示）
+
+### 2.6 更新配置管理
+
+#### T2.6.1 更新配置界面
+- **任务描述**：更新相关配置管理
+- **技术要点**：
+  - 自动检查更新开关
+  - 检查频率设置
+  - 更新通道选择（稳定版/测试版）
+- **依赖**：T2.1.2
+- **优先级**：P2
+- **实现状态**：✅ 已实现（自动检查开关、检查间隔配置）
+
+---
+
+## 3. 实现检查与改进建议
+
+### 3.1 符合行业最佳实践 ✅
+- ✅ 版本检查机制：远程接口、语义化版本、检查频率控制
+- ✅ 下载机制：断点续传、进度反馈、文件完整性验证
+- ✅ 安装机制：备份回滚、多格式支持、自动重启
+- ✅ 安全性：文件哈希验证、HTTPS 传输、进度值安全
+- ⚠️ 数字签名验证：未实现（建议增强）
+
+### 3.2 优势
+1. **完整的备份和回滚机制**：安装前备份，失败时自动回滚
+2. **多格式支持**：同时支持 `.exe` 安装程序和 `.zip` 压缩包
+3. **详细的进度反馈**：实时显示下载进度、速度、大小
+4. **灵活的配置管理**：支持自定义检查间隔和检查地址
+5. **代码质量**：遵循 DRY 原则，代码简洁易维护
+
+### 3.3 不足与改进建议
+
+#### 高优先级 🔴
+1. **添加数字签名验证**
+   - Windows: 验证 `.exe` 文件的 Authenticode 签名
+   - macOS: 验证 `.app` 的代码签名
+   - 在安装前验证签名，确保更新包来源可信
+
+2. **改进 Windows 文件替换机制**
+   - 使用 `MoveFileEx` API 的 `MOVEFILE_DELAY_UNTIL_REBOOT` 标志
+   - 或者使用临时文件名 + 原子替换的方式
+
+#### 中优先级 ⚠️
+1. **添加下载 URL 白名单验证**
+   - 在配置中维护允许的下载域名列表
+   - 下载前验证 URL 是否在白名单中
+
+2. **优化下载超时机制**
+   - 根据文件大小动态调整超时时间
+   - 添加网络状态检测，网络断开时暂停下载
+
+3. **添加增量更新支持**
+   - 服务器提供增量更新包（仅包含差异部分）
+   - 客户端支持增量更新包的下载和安装
+
+#### 低优先级 💡
+1. **添加更新包压缩**
+   - 服务器提供压缩的更新包（`.zip` 或 `.7z`）
+   - 客户端下载后自动解压
+
+2. **优化进度更新频率**
+   - 将进度更新频率改为可配置
+   - 根据下载速度动态调整更新频率
+
+---
+
+## 4. 代码优化记录
+
+### 5.1 优化时间线
+- **2026-01-08**：代码重构和精简
+  - 后端代码量减少 40-50%
+  - 前端代码量减少约 40%（485行 → 300行）
+  - 添加多层进度值保护机制
+  - 遵循 DRY 原则，提高代码质量
+
+### 5.2 后端优化详情
+
+#### update_download.go（减少约 45%）
+- ✅ 提取 `getRemoteFileSize()` 函数，消除重复的 HEAD 请求逻辑
+- ✅ 提取 `normalizeProgress()` 函数，统一进度值标准化
+- ✅ 移除大量调试日志，仅保留关键错误日志
+- ✅ 优化文件大小获取逻辑，支持多种方式获取
+
+#### update_api.go（减少约 50%）
+- ✅ 移除所有不必要的 `log.Printf` 调试日志
+- ✅ 简化错误处理逻辑
+- ✅ 优化进度回调函数，减少重复检查
+
+#### update_install.go（减少约 30%）
+- ✅ 移除所有调试日志
+- ✅ 保留关键错误返回
+
+### 5.3 前端优化详情
+
+#### useVersion.ts（减少约 40%）
+- ✅ 提取 `clampProgress()` 辅助函数，统一进度值标准化
+- ✅ 提取 `resetDownloadState()` 函数，消除重复代码
+- ✅ 提取 `installUpdate()` 函数，简化安装逻辑
+- ✅ 优化事件处理，减少重复的 `nextTick` 调用
+- ✅ 遵循 DRY 原则，提高代码可维护性
+
+### 5.4 关键改进
+1. **进度值安全**：多层防护确保进度值严格在 0-100% 之间
+   - 后端 `normalizeProgress()` 函数
+   - 后端 API 层检查
+   - 前端 `clampProgress()` 函数
+   - 组件内 `Math.max(0, Math.min(100, ...))` 限制
+
+2. **代码质量**：
+   - 遵循 DRY 原则，消除重复代码
+   - 单一职责原则，每个函数只做一件事
+   - 减少日志输出，提高性能
+   - 代码更简洁易读，易于维护
+
+---
+
+## 5. 开发顺序建议
+
+### 第一阶段（核心功能）✅ 已完成
+1. T2.1.1 → T2.1.2（版本号管理）
+2. T2.2.1 → T2.2.2 → T2.2.3（更新检查）
+3. T2.3.1 → T2.3.2（更新下载）
+4. T2.4.1（更新安装）
+
+### 第二阶段（增强功能）✅ 部分完成
+1. T2.4.2（安装方式选择）- ✅ 自动安装已实现
+2. T2.5.1 → T2.5.2（更新日志）- ✅ 已实现
+
+### 第三阶段（配置管理）✅ 已完成
+1. T2.6.1（更新配置）- ✅ 已实现
+
+---
+
+## 6. 任务优先级说明
+
+- **P0**：核心功能，必须完成（版本检查、下载、安装）- ✅ 已完成
+- **P1**：重要功能（安装方式选择、更新日志）- ✅ 已实现
+- **P2**：辅助功能（配置管理）- ✅ 已实现
+
+---
+
+## 7. 总结
+
+### 8.1 整体评价
+我们的实现**基本符合**官方和行业最佳实践，主要功能都已实现，包括：
+- ✅ 版本检查机制
+- ✅ 下载机制（含断点续传）
+- ✅ 安装机制（含备份和回滚）
+- ✅ 前端 UI 和交互
+- ✅ 代码优化和重构（2026-01-08）
+
+### 8.2 主要不足
+1. **安全性**：缺少数字签名验证（高优先级）
+2. **Windows 兼容性**：文件替换机制可能需要改进（高优先级）
+3. **功能增强**：缺少增量更新支持（中优先级）
+
+### 8.3 建议
+1. **立即改进**：添加数字签名验证，提高安全性
+2. **短期优化**：改进 Windows 文件替换机制，提高成功率
+3. **长期规划**：考虑添加增量更新支持，减少下载量
+
+---
+
+> 文档维护者：JueChen  
+> 创建时间：2026-01-07  
+> 最后更新：2026-01-08
--- a/docs/04-功能迭代/版本更新/版本更新设计.md
+++ b/docs/04-功能迭代/版本更新/版本更新设计.md
@@ -0,0 +1,285 @@
+# 版本更新功能设计文档
+
+## 1. 功能概述
+
+实现应用版本更新检查、下载、安装功能，支持自动和手动更新，提供更新日志展示。
+
+### 1.1 核心功能
+- 版本检查：自动/手动检查远程版本信息
+- 更新下载：支持断点续传的更新包下载
+- 更新安装：自动备份、安装、重启
+- 进度展示：实时显示下载和安装进度
+
+### 1.2 设计原则
+- **安全性**：文件哈希验证、HTTPS 传输
+- **可靠性**：断点续传、备份回滚机制
+- **用户体验**：实时进度反馈、错误提示
+- **代码质量**：遵循 DRY 原则，简洁易维护
+
+---
+
+## 2. 架构设计
+
+### 2.1 模块划分
+
+```
+版本更新模块
+├── 后端服务层
+│   ├── update_service.go      # 版本检查服务
+│   ├── update_download.go      # 下载服务
+│   ├── update_install.go      # 安装服务
+│   └── update_config.go        # 配置管理
+├── API 层
+│   └── update_api.go           # 更新 API 接口
+└── 前端层
+    └── useVersion.ts           # 版本管理 Composable
+```
+
+### 2.2 数据流
+
+```
+前端 (useVersion.ts)
+    ↓ 调用 API
+API 层 (update_api.go)
+    ↓ 调用服务
+服务层 (update_service.go / update_download.go / update_install.go)
+    ↓ 事件推送
+前端 (通过 Wails Events 接收进度)
+```
+
+### 2.3 关键组件
+
+#### 版本检查服务
+- **职责**：获取远程版本信息，比较版本号
+- **输入**：检查 URL
+- **输出**：更新信息（版本号、下载地址、更新日志等）
+
+#### 下载服务
+- **职责**：下载更新包，计算进度，验证文件
+- **输入**：下载 URL
+- **输出**：下载结果（文件路径、哈希值）
+- **特性**：断点续传、进度回调
+
+#### 安装服务
+- **职责**：备份、安装、重启应用
+- **输入**：安装包路径
+- **输出**：安装结果
+- **特性**：自动备份、失败回滚
+
+---
+
+## 3. 技术实现要点
+
+### 3.1 版本号格式
+- **格式**：语义化版本 `主版本号.次版本号.修订号`（如 `1.0.0`）
+- **比较逻辑**：逐级比较主版本号、次版本号、修订号
+- **解析支持**：支持 `v1.0.0` 或 `1.0.0` 格式
+
+### 3.2 远程版本信息接口
+
+#### 接口地址
+```
+https://img.1216.top/ssq/last-version.json
+```
+
+#### 接口返回格式
+```json
+{
+  "version": "0.1.1",
+  "download_url": "https://img.1216.top/ssq/releases/ssq-desk-0.1.1.exe",
+  "changelog": "更新日志内容",
+  "force_update": false,
+  "release_date": "2026-01-07"
+}
+```
+
+#### 字段说明
+- `version`: 最新版本号（语义化版本）
+- `download_url`: 更新包下载地址
+- `changelog`: 更新日志内容
+- `force_update`: 是否强制更新
+- `release_date`: 发布日期
+
+### 3.3 更新包格式
+- **Windows**：`.exe` 安装包或 `.zip` 压缩包
+- **支持方式**：全量更新（当前实现）
+
+### 3.4 下载机制设计
+
+#### 断点续传
+- 使用 HTTP `Range` 头实现断点续传
+- 支持从已下载位置继续下载
+- 自动检测已下载文件大小
+
+#### 进度计算
+- **更新频率**：每 0.3 秒更新一次
+- **进度值保护**：多层防护确保进度值在 0-100% 之间
+  - 后端 `normalizeProgress()` 函数标准化
+  - API 层最后一道防线检查
+  - 前端 `clampProgress()` 函数确保显示值合法
+
+#### 文件大小获取
+1. 优先从 `Content-Range` 头获取（最准确）
+2. 从响应 `ContentLength` 获取
+3. 通过 HEAD 请求获取（备用方案）
+
+### 3.5 安装机制设计
+
+#### 安装流程
+1. **备份**：安装前自动备份当前版本到 `~/.ssq-desk/backups/`
+2. **验证**：可选的文件哈希验证（MD5/SHA256）
+3. **安装**：
+   - `.exe` 文件：直接替换可执行文件
+   - `.zip` 文件：解压后替换文件
+4. **重启**：安装成功后自动重启应用
+5. **回滚**：安装失败时自动恢复备份
+
+#### Windows 文件替换
+- 使用重命名方式（`.old` 后缀）
+- 如果文件正在使用，将在重启后替换
+
+### 3.6 检查间隔设计
+
+#### 检查触发机制
+- **启动时检查**：应用启动时立即检查一次
+- **自动检查**：根据配置的检查间隔自动检查
+- **手动检查**：用户可随时手动触发检查
+
+#### 推荐配置
+- **开发/测试**：5-30分钟
+- **生产环境**：60分钟（1小时）推荐
+- **省流模式**：360分钟（6小时）
+- **最小间隔**：5分钟（防止过于频繁）
+- **最大间隔**：1440分钟（24小时）
+
+---
+
+## 4. 接口设计
+
+### 4.1 后端 API 接口
+
+#### CheckUpdate()
+- **功能**：检查是否有新版本
+- **返回**：更新信息（版本号、下载地址、更新日志等）
+
+#### GetCurrentVersion()
+- **功能**：获取当前版本号
+- **返回**：当前版本号
+
+#### DownloadUpdate(downloadURL)
+- **功能**：下载更新包（异步）
+- **参数**：下载地址
+- **事件**：通过 `download-progress` 和 `download-complete` 事件推送进度
+
+#### InstallUpdate(filePath, autoRestart)
+- **功能**：安装更新包
+- **参数**：文件路径、是否自动重启
+- **返回**：安装结果
+
+### 4.2 前端事件
+
+#### download-progress
+- **触发时机**：下载过程中（每 0.3 秒）
+- **数据格式**：
+```json
+{
+  "progress": 50.5,
+  "speed": 1024000,
+  "downloaded": 5242880,
+  "total": 10485760
+}
+```
+
+#### download-complete
+- **触发时机**：下载完成或失败
+- **数据格式**（成功）：
+```json
+{
+  "success": true,
+  "file_path": "C:\\Users\\...\\ssq-desk-0.1.1.exe",
+  "file_size": 10485760
+}
+```
+- **数据格式**（失败）：
+```json
+{
+  "error": "下载失败：网络错误"
+}
+```
+
+---
+
+## 5. 安全设计
+
+### 5.1 已实现的安全措施
+- ✅ **文件哈希验证**：支持 MD5/SHA256 哈希验证
+- ✅ **HTTPS 传输**：使用 HTTPS 确保传输安全
+- ✅ **进度值安全**：多层防护确保进度值不会异常
+
+### 5.2 待增强的安全措施
+- ⚠️ **数字签名验证**：未实现（建议增强）
+  - Windows: 验证 `.exe` 文件的 Authenticode 签名
+  - macOS: 验证 `.app` 的代码签名
+- ⚠️ **URL 白名单验证**：未实现（建议增强）
+  - 在配置中维护允许的下载域名列表
+  - 下载前验证 URL 是否在白名单中
+
+---
+
+## 6. 错误处理
+
+### 6.1 网络错误
+- **处理方式**：提示用户检查网络连接
+- **重试机制**：支持手动重试
+
+### 6.2 下载失败
+- **处理方式**：显示错误信息，支持重新下载
+- **断点续传**：支持从断点继续下载
+
+### 6.3 安装失败
+- **处理方式**：自动回滚到备份版本
+- **备份机制**：安装前自动创建备份
+
+### 6.4 进度值异常
+- **处理方式**：多层防护确保进度值在 0-100% 之间
+- **保护机制**：
+  - 后端标准化函数
+  - API 层检查
+  - 前端标准化函数
+
+---
+
+## 7. 性能优化
+
+### 7.1 代码优化（2026-01-08）
+- **后端代码量减少**：40-50%
+- **前端代码量减少**：约 40%（485行 → 300行）
+- **优化措施**：
+  - 提取重复逻辑为函数
+  - 精简日志输出
+  - 优化事件处理
+
+### 7.2 下载优化
+- **进度更新频率**：0.3 秒（平衡性能和用户体验）
+- **缓冲区大小**：32KB
+- **超时时间**：30 分钟
+
+---
+
+## 8. 扩展性设计
+
+### 8.1 可扩展功能
+- 增量更新支持
+- 更新包压缩
+- 多通道更新（稳定版/测试版）
+- 数字签名验证
+
+### 8.2 配置化设计
+- 检查间隔可配置
+- 检查地址可配置
+- 自动检查开关可配置
+
+---
+
+> 文档维护者：JueChen  
+> 创建时间：2026-01-08