12 KiB
12 KiB
版本更新功能任务规划
设计文档请参考：版本更新设计.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目录
- ✅ 断点续传：使用 HTTP
- 代码优化（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后缀），但可能在某些情况下失败
- ⚠️ Windows 下替换正在运行的可执行文件：当前实现使用重命名方式（
- 代码优化（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 优势
- 完整的备份和回滚机制：安装前备份，失败时自动回滚
- 多格式支持：同时支持
.exe安装程序和.zip压缩包 - 详细的进度反馈：实时显示下载进度、速度、大小
- 灵活的配置管理：支持自定义检查间隔和检查地址
- 代码质量：遵循 DRY 原则，代码简洁易维护
3.3 不足与改进建议
高优先级 🔴
-
添加数字签名验证
- Windows: 验证
.exe文件的 Authenticode 签名 - macOS: 验证
.app的代码签名 - 在安装前验证签名，确保更新包来源可信
- Windows: 验证
-
改进 Windows 文件替换机制
- 使用
MoveFileExAPI 的MOVEFILE_DELAY_UNTIL_REBOOT标志 - 或者使用临时文件名 + 原子替换的方式
- 使用
中优先级 ⚠️
-
添加下载 URL 白名单验证
- 在配置中维护允许的下载域名列表
- 下载前验证 URL 是否在白名单中
-
优化下载超时机制
- 根据文件大小动态调整超时时间
- 添加网络状态检测，网络断开时暂停下载
-
添加增量更新支持
- 服务器提供增量更新包（仅包含差异部分）
- 客户端支持增量更新包的下载和安装
低优先级 💡
-
添加更新包压缩
- 服务器提供压缩的更新包（
.zip或.7z） - 客户端下载后自动解压
- 服务器提供压缩的更新包（
-
优化进度更新频率
- 将进度更新频率改为可配置
- 根据下载速度动态调整更新频率
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 关键改进
-
进度值安全：多层防护确保进度值严格在 0-100% 之间
- 后端
normalizeProgress()函数 - 后端 API 层检查
- 前端
clampProgress()函数 - 组件内
Math.max(0, Math.min(100, ...))限制
- 后端
-
代码质量：
- 遵循 DRY 原则，消除重复代码
- 单一职责原则，每个函数只做一件事
- 减少日志输出，提高性能
- 代码更简洁易读，易于维护
5. 开发顺序建议
第一阶段（核心功能）✅ 已完成
- T2.1.1 → T2.1.2（版本号管理）
- T2.2.1 → T2.2.2 → T2.2.3（更新检查）
- T2.3.1 → T2.3.2（更新下载）
- T2.4.1（更新安装）
第二阶段（增强功能）✅ 部分完成
- T2.4.2（安装方式选择）- ✅ 自动安装已实现
- T2.5.1 → T2.5.2（更新日志）- ✅ 已实现
第三阶段（配置管理）✅ 已完成
- T2.6.1（更新配置）- ✅ 已实现
6. 任务优先级说明
- P0：核心功能，必须完成（版本检查、下载、安装）- ✅ 已完成
- P1：重要功能（安装方式选择、更新日志）- ✅ 已实现
- P2：辅助功能（配置管理）- ✅ 已实现
7. 总结
8.1 整体评价
我们的实现基本符合官方和行业最佳实践，主要功能都已实现，包括：
- ✅ 版本检查机制
- ✅ 下载机制（含断点续传）
- ✅ 安装机制（含备份和回滚）
- ✅ 前端 UI 和交互
- ✅ 代码优化和重构（2026-01-08）
8.2 主要不足
- 安全性：缺少数字签名验证（高优先级）
- Windows 兼容性：文件替换机制可能需要改进（高优先级）
- 功能增强：缺少增量更新支持（中优先级）
8.3 建议
- 立即改进：添加数字签名验证，提高安全性
- 短期优化：改进 Windows 文件替换机制，提高成功率
- 长期规划：考虑添加增量更新支持，减少下载量
文档维护者：JueChen
创建时间：2026-01-07
最后更新：2026-01-08