u-desk/docs/04-功能迭代/GO-DESK-1.尝试/更新升级功能设计.md

# Go Desk 更新升级功能设计

> **文档版本**：v0.1.0
> **创建时间**：2026-01-20
> **维护者**：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 应用更新最佳实践

---

**下一步**：根据此设计文档开始实现更新功能。