重构：文件系统模块化架构，优化应用启动流程

2026-01-28 00:28:54 +08:00
parent 4a9b25a505
commit 8c577f70e7
123 changed files with 32030 additions and 967 deletions
--- a/docs/04-功能迭代/GO-DESK-1.尝试/更新升级功能设计.md
+++ b/docs/04-功能迭代/GO-DESK-1.尝试/更新升级功能设计.md
@@ -0,0 +1,250 @@
+# Go Desk 更新升级功能设计
+
+> **文档版本**：v1.0  
+> **创建时间**：2025-01-XX  
+> **维护者**：JueChen  
+> **状态**：设计阶段
+
+## 1. 功能概述
+
+实现应用的自动更新升级功能，包括版本检查、下载更新包、自动替换和重启应用。
+
+## 2. 功能需求
+
+### 2.1 核心功能
+
+- [ ] 版本检查：启动时或手动检查最新版本
+- [ ] 版本对比：比较当前版本与最新版本
+- [ ] 更新提示：发现新版本时提示用户
+- [ ] 下载更新：后台下载更新包（支持进度显示）
+- [ ] 自动替换：下载完成后自动替换旧版本
+- [ ] 自动重启：替换完成后自动重启应用
+
+### 2.2 版本管理
+
+- **当前版本**：从代码中定义（如 `const Version = "1.0.0"`）
+- **版本格式**：语义化版本（如 `1.0.0`, `1.0.1`）
+- **版本检查**：从服务器获取最新版本信息（JSON 格式）
+
+### 2.3 更新流程
+
+```
+应用启动
+  ↓
+检查更新（可选，后台进行）
+  ↓
+发现新版本？
+  ↓ 是
+显示更新提示
+  ↓
+用户确认更新
+  ↓
+下载更新包（显示进度）
+  ↓
+下载完成
+  ↓
+关闭当前应用
+  ↓
+替换旧版本文件
+  ↓
+启动新版本
+  ↓
+完成
+```
+
+## 3. 技术实现
+
+### 3.1 版本信息结构
+
+```go
+type VersionInfo struct {
+    Version     string `json:"version"`      // 版本号，如 "1.0.1"
+    DownloadURL string `json:"download_url"` // 下载地址
+    ReleaseNotes string `json:"release_notes"` // 更新说明
+    Size        int64  `json:"size"`        // 文件大小（字节）
+    MD5         string `json:"md5"`         // 文件 MD5 校验
+}
+```
+
+### 3.2 版本检查接口
+
+**接口地址**：`https://your-server.com/api/version/check`
+
+**请求**：
+```json
+{
+  "current_version": "1.0.0",
+  "platform": "windows"
+}
+```
+
+**响应**：
+```json
+{
+  "has_update": true,
+  "latest_version": "1.0.1",
+  "download_url": "https://your-server.com/releases/go-desk-1.0.1.exe",
+  "release_notes": "修复了若干问题",
+  "size": 13765632,
+  "md5": "abc123..."
+}
+```
+
+### 3.3 Go 后端实现
+
+#### 3.3.1 版本定义
+
+```go
+// app.go 或 version.go
+const AppVersion = "1.0.0"
+```
+
+#### 3.3.2 更新检查方法
+
+```go
+// CheckUpdate 检查更新
+func (a *App) CheckUpdate() (map[string]interface{}, error)
+```
+
+#### 3.3.3 下载更新方法
+
+```go
+// DownloadUpdate 下载更新包
+func (a *App) DownloadUpdate(downloadURL string, progressCallback func(int)) error
+```
+
+#### 3.3.4 应用更新方法
+
+```go
+// ApplyUpdate 应用更新（替换文件并重启）
+func (a *App) ApplyUpdate(updateFilePath string) error
+```
+
+### 3.4 前端实现
+
+#### 3.4.1 更新检查组件
+
+- 启动时自动检查（可选）
+- 手动检查按钮
+- 更新提示对话框
+- 下载进度显示
+
+#### 3.4.2 界面元素
+
+- 版本号显示
+- 更新提示对话框（Arco Modal）
+- 下载进度条（Arco Progress）
+- 更新说明展示
+
+## 4. 实现细节
+
+### 4.1 版本比较
+
+使用语义化版本比较：
+- 格式：`主版本号.次版本号.修订号`（如 `1.0.0`）
+- 比较逻辑：逐级比较版本号
+
+### 4.2 文件下载
+
+- 使用 Go 标准库 `net/http` 下载
+- 支持进度回调
+- 支持断点续传（可选）
+- 下载到临时目录（如 `%TEMP%/go-desk-update.exe`）
+
+### 4.3 文件替换（Windows）
+
+**方案1：使用批处理脚本**
+1. 下载完成后，生成批处理脚本
+2. 脚本内容：等待进程结束 → 替换文件 → 启动新版本 → 删除脚本
+3. 启动脚本后退出当前应用
+
+**方案2：使用 Go 实现**
+1. 创建更新助手程序
+2. 主程序退出前启动助手程序
+3. 助手程序等待主程序退出后替换文件并重启
+
+### 4.4 错误处理
+
+- 网络错误：提示检查网络连接
+- 下载失败：支持重试
+- 文件校验失败：重新下载
+- 替换失败：提示手动更新
+
+## 5. 文件结构
+
+```
+go-desk/
+├── internal/
+│   └── update/
+│       ├── update.go      # 更新核心逻辑
+│       ├── version.go    # 版本管理
+│       └── download.go   # 下载功能
+├── app.go                # 添加更新相关方法
+└── version.go            # 版本常量定义
+```
+
+## 6. 配置项
+
+### 6.1 更新服务器配置
+
+```go
+const (
+    UpdateCheckURL = "https://your-server.com/api/version/check"
+    UpdateInterval = 24 * time.Hour // 检查间隔
+)
+```
+
+### 6.2 可选配置
+
+- 是否自动检查更新
+- 检查更新间隔
+- 更新服务器地址
+
+## 7. 安全考虑
+
+1. **HTTPS 连接**：版本检查和下载使用 HTTPS
+2. **文件校验**：下载后验证 MD5/SHA256
+3. **权限检查**：确保有写入权限
+4. **回滚机制**：更新失败时保留旧版本
+
+## 8. 用户体验
+
+1. **非阻塞**：更新检查在后台进行，不阻塞应用启动
+2. **可取消**：用户可以选择稍后更新
+3. **进度显示**：下载时显示进度条
+4. **友好提示**：清晰的更新说明和操作指引
+
+## 9. 开发优先级
+
+### 阶段一：基础功能
+- [ ] 版本定义和比较
+- [ ] 版本检查接口
+- [ ] 简单的更新提示
+
+### 阶段二：下载功能
+- [ ] 文件下载实现
+- [ ] 进度显示
+- [ ] 错误处理
+
+### 阶段三：自动更新
+- [ ] 文件替换逻辑
+- [ ] 自动重启
+- [ ] 完整测试
+
+## 10. 注意事项
+
+1. **Windows 文件锁定**：需要先关闭应用才能替换
+2. **权限问题**：确保有写入应用目录的权限
+3. **网络超时**：设置合理的超时时间
+4. **更新失败处理**：保留旧版本，不破坏现有功能
+
+## 11. 参考实现
+
+- Electron 的 auto-updater 机制
+- Wails 社区更新方案
+- Go 应用更新最佳实践
+
+---
+
+**下一步**：根据此设计文档开始实现更新功能。
+