lxy/ssq-desk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

.

Browse Source
This commit is contained in:
绝尘
2026-01-14 14:17:38 +08:00
commit f1e2ff6563
126 changed files with 13636 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/04-功能迭代/.gitkeep Normal file
View File

@@ -0,0 +1 @@
# 功能迭代目录

215
docs/04-功能迭代/双色球查询功能需求.md Normal file
View File

@@ -0,0 +1,215 @@
# 双色球查询功能需求文档
## 1. 功能概述
双色球桌面查询应用，提供历史开奖数据查询、统计分析等功能。
---
## 2. 查询功能
### 2.1 查询条件
#### 2.1.1 红球输入
- 6个红色球输入框，依次为：
- 红球1
- 红球2
- 红球3
- 红球4
- 红球5
- 红球6
#### 2.1.2 蓝球输入
- 1个蓝色球输入框：蓝球
#### 2.1.3 蓝球筛选
- 17个复选框：
- 蓝球1 至 蓝球16（16个选项）
- 全选复选框（1个）
#### 2.1.4 操作按钮
- **查询按钮**：执行查询
- **重置按钮**：清空所有输入，默认勾选全选复选框
### 2.2 查询逻辑
- 根据输入的6个红球和1个蓝球进行匹配查询
- 支持部分匹配（如只输入部分红球）
- 蓝球筛选：根据勾选的蓝球范围进行过滤
### 2.3 查询结果展示
#### 2.3.1 结果列表
显示字段：
- 期数
- 红球1
- 红球2
- 红球3
- 红球4
- 红球5
- 红球6
- 蓝球
#### 2.3.2 数字颜色标识
- **匹配的红球**：红色数字显示
- **匹配的蓝球**：蓝色数字显示
- **未匹配的数字**：黑色数字显示
#### 2.3.3 查询结果分类
**左侧汇总区域**：
- 开出过6个红球与1个蓝球：X次
- 开出过6个红球：X次
- 开出过5个红球与1个蓝球：X次
- 开出过5个红球：X次
- 开出过4个红球与1个蓝球：X次
- 开出过4个红球：X次
- 开出过3个红球与1个蓝球：X次
- 开出过3个红球：X次
- 开出过2个红球与1个蓝球：X次
- 开出过2个红球：X次
- 开出过1个红球与1个蓝球：X次
- 开出过1个红球：X次
- 开出过0个红球与1个蓝球：X次
- 开出过0个红球：X次
- 每个汇总项提供 `[显示历史开奖]` 链接
**右侧详情区域**：
- 点击左侧汇总项的 `[显示历史开奖]`，右侧显示对应的详细开奖记录
- 每条记录显示：期号、红球号码、蓝球号码
- 支持扩展查询：`[再扩展查询对比结果上下n期]` 按钮
**扩展功能**：
- 底部提供：`[扩展显示≤3个红球的对比结果]` 按钮
---
## 3. 数据维护功能
### 3.1 数据同步
- 从远程数据库同步历史数据
- 支持增量更新
- 数据校验和去重
### 3.2 数据管理
- 查看本地数据统计
- 手动刷新数据
- 数据备份与恢复
---
## 4. 其他功能
### 4.1 版本更新
- 检查更新
- 自动/手动更新
- 更新日志展示
### 4.2 离线数据
- 离线数据包管理
- 离线数据包更新
- 数据包下载与导入
### 4.3 授权管理
- 设备授权码管理
- 激活状态验证
- 授权信息显示
---
## 5. 数据库设计
### 5.1 数据库信息
- **地址**：39.99.243.191:3306
- **账号**：u_ssq
- **密码**：u_ssq@260106
- **数据库名**：ssq_dev
### 5.2 数据表结构
#### ssq_history（双色球历史开奖数据表）
```sql
CREATE TABLE IF NOT EXISTS `ssq_history` (
`id` INT NOT NULL COMMENT '主键ID',
`issue_number` VARCHAR(20) NOT NULL COMMENT '期号（如2025145）',
`open_date` DATE NULL COMMENT '开奖日期（允许为空）',
`red_ball_1` TINYINT NOT NULL COMMENT '红球1',
`red_ball_2` TINYINT NOT NULL COMMENT '红球2',
`red_ball_3` TINYINT NOT NULL COMMENT '红球3',
`red_ball_4` TINYINT NOT NULL COMMENT '红球4',
`red_ball_5` TINYINT NOT NULL COMMENT '红球5',
`red_ball_6` TINYINT NOT NULL COMMENT '红球6',
`blue_ball` TINYINT NOT NULL COMMENT '蓝球',
`created_at` DATETIME NOT NULL COMMENT '创建时间',
`updated_at` DATETIME NOT NULL COMMENT '更新时间',
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='双色球历史开奖数据';
```
#### 字段说明
- `id`：主键，唯一标识
- `issue_number`：期号，格式如 "2025145"
- `open_date`：开奖日期，可为空
- `red_ball_1` 至 `red_ball_6`：6个红球号码（1-33）
- `blue_ball`：蓝球号码（1-16）
- `created_at`：记录创建时间
- `updated_at`：记录更新时间
---
## 6. 界面设计要求
### 6.1 布局
- 顶部：查询条件区域
- 中间左侧：查询汇总列表
- 中间右侧：查询结果详情
- 底部：扩展功能按钮
### 6.2 样式规范
- 使用 Arco Design 组件库
- 红球数字：红色标识（#F53F3F）
- 蓝球数字：蓝色标识（#165DFF）
- 未匹配数字：黑色（默认）
- 保持主题兼容性
---
## 7. 技术实现
### 7.1 技术栈
- **前端**：Vue 3 + Arco Design + TypeScript
- **后端**：Go + Wails
- **数据库**：MySQL（远程）+ SQLite（本地缓存）
### 7.2 数据存储策略
- 远程 MySQL：完整历史数据
- 本地 SQLite：缓存查询结果，离线支持
### 7.3 性能优化
- 分页加载查询结果
- 本地数据缓存
- 异步数据同步
---
## 8. 开发优先级
### Phase 1：核心查询功能
1. 查询条件界面
2. 基础查询功能
3. 结果展示（列表+分类）
### Phase 2：数据管理
1. 数据同步功能
2. 本地数据管理
### Phase 3：其他功能
1. 版本更新
2. 离线数据包
3. 授权管理
---
> 文档维护者：JueChen
> 创建时间：2026-01-07

114
docs/04-功能迭代/授权码功能/授权码功能设计.md Normal file
View File

@@ -0,0 +1,114 @@
# 授权码功能设计
## 1. 功能概述
授权码功能用于设备激活和授权验证，确保应用在授权设备上使用。
## 2. 核心功能
### 2.1 设备标识
- 基于主机名、用户目录、操作系统生成设备ID
- 使用 MD5 哈希确保唯一性和稳定性
- 设备ID与授权码绑定
### 2.2 授权码验证
- 授权码输入和格式验证
- 设备绑定（授权码与设备ID关联）
- 授权状态存储（SQLite 本地数据库）
### 2.3 激活验证
- 应用启动时自动验证授权状态
- 授权信息展示
- 授权失效处理
## 3. 数据模型
### 3.1 Authorization 表结构
```sql
CREATE TABLE IF NOT EXISTS `sys_authorization_code` (
`id` INTEGER PRIMARY KEY AUTOINCREMENT, -- 主键ID
`license_code` VARCHAR(100) NOT NULL, -- 授权码（唯一）
`device_id` VARCHAR(100) NOT NULL, -- 设备ID（MD5哈希）
`activated_at` DATETIME NOT NULL, -- 激活时间
`expires_at` DATETIME NULL, -- 过期时间（可选，NULL表示永不过期）
`status` TINYINT NOT NULL DEFAULT 1, -- 状态（1:有效 0:无效）
`created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, -- 创建时间
`updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, -- 更新时间
UNIQUE (`license_code`) -- 授权码唯一索引
);
```
### 3.2 字段说明
- `id`: 主键ID，自增
- `license_code`: 授权码，唯一索引（UNIQUE约束）
- `device_id`: 设备ID（基于主机名、用户目录、操作系统生成的MD5哈希），通过 GORM 标签定义索引
- `activated_at`: 激活时间，必填
- `expires_at`: 过期时间，可选，NULL表示永不过期
- `status`: 状态（1:有效 0:无效），默认值为1
- `created_at`: 创建时间，自动设置为当前时间
- `updated_at`: 更新时间，自动更新为当前时间
### 3.3 索引说明
- `license_code`: 唯一索引（UNIQUE约束），用于快速查找和验证授权码
- 其他字段的索引通过 GORM 标签在模型定义中声明，由 GORM AutoMigrate 自动创建
## 4. API 接口
### 4.1 ActivateLicense
- **功能**: 激活授权码
- **参数**: `licenseCode string`
- **返回**: 激活结果和授权状态
### 4.2 GetAuthStatus
- **功能**: 获取当前授权状态
- **返回**: 授权状态信息
### 4.3 GetDeviceID
- **功能**: 获取设备ID
- **返回**: 设备ID字符串
## 5. 实现架构
### 5.1 分层结构
```
API 层 (auth_api.go)
↓
Service 层 (auth_service.go)
↓
Repository 层 (auth_repository.go)
↓
Model 层 (authorization.go)
↓
SQLite 数据库
```
### 5.2 启动验证流程
```
应用启动
↓
初始化 SQLite
↓
初始化 AuthAPI
↓
检查授权状态
↓
未激活 → 提示用户激活
已激活 → 继续运行
```
## 6. 使用说明
### 6.1 激活授权
前端调用 `ActivateLicense(licenseCode)` 方法激活授权码。
### 6.2 检查状态
前端调用 `GetAuthStatus()` 方法获取授权状态，根据状态决定是否显示激活界面。
### 6.3 设备ID
调用 `GetDeviceID()` 获取设备ID，可用于授权码生成或问题排查。
---
> 文档维护者：JueChen
> 创建时间：2026-01-07

7
docs/04-功能迭代/版本更新/last-version.json Normal file
View File

@@ -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"
}

347
docs/04-功能迭代/版本更新/任务规划.md Normal file
View File

@@ -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

285
docs/04-功能迭代/版本更新/版本更新设计.md Normal file
View File

@@ -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