# 更新检查 API 文档

## 🔧 修复内容

### 已修复的 Bug

1. ✅ **版本比较逻辑错误**
   - 之前：使用字符串比较（`"1.10.0" < "1.9.0"` 错误）
   - 现在：实现语义化版本号比较（semver）

2. ✅ **Asset 查询错误处理缺失**
   - 之前：查询失败时返回空 URL
   - 现在：正确处理错误并返回明确的错误信息

3. ✅ **参数验证缺失**
   - 现在：验证所有必需参数（app, version, platform, arch）

4. ✅ **排序逻辑优化**
   - 之前：按 version 字符串排序
   - 现在：按 pub_date 排序，更准确

5. ✅ **响应格式统一**
   - 现在使用统一的响应格式，并添加 checksum 字段

## 📝 API 使用

### 端点

```
GET /api/check-update
```

### 请求参数

| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| app | string | ✅ | 应用 ID |
| version | string | ✅ | 当前版本号 |
| platform | string | ✅ | 平台（windows/darwin/linux） |
| arch | string | ✅ | 架构（amd64/arm64/386） |

### 响应格式

**有更新：**
```json
{
  "code": 0,
  "msg": "ok",
  "data": {
    "update": true,
    "version": "1.2.0",
    "notes": "更新说明\n- 新功能\n- Bug修复",
    "url": "http://localhost:9050/files/releases/2/windows-amd64/app.exe",
    "checksum": "sha256哈希值"
  }
}
```

**无需更新：**
```json
{
  "code": 0,
  "msg": "ok",
  "data": {
    "update": false
  }
}
```

**错误响应：**
```json
{
  "code": 500,
  "msg": "no asset found for this platform and architecture"
}
```

## 🧪 测试示例

### PowerShell 测试

```powershell
# 测试更新检查（需要更新）
$params = @{
    app = "test-app"
    version = "1.0.0"
    platform = "windows"
    arch = "amd64"
}
$query = ($params.GetEnumerator() | ForEach-Object { "$($_.Key)=$($_.Value)" }) -join "&"
Invoke-RestMethod -Uri "http://localhost:9050/api/check-update?$query"

# 测试更新检查（已是最新）
$params = @{
    app = "test-app"
    version = "2.0.0"
    platform = "windows"
    arch = "amd64"
}
$query = ($params.GetEnumerator() | ForEach-Object { "$($_.Key)=$($_.Value)" }) -join "&"
Invoke-RestMethod -Uri "http://localhost:9050/api/check-update?$query"

# 测试不存在的平台
$params = @{
    app = "test-app"
    version = "1.0.0"
    platform = "windows"
    arch = "arm"  # 假设没有这个架构的版本
}
$query = ($params.GetEnumerator() | ForEach-Object { "$($_.Key)=$($_.Value)" }) -join "&"
Invoke-RestMethod -Uri "http://localhost:9050/api/check-update?$query"
```

### curl 测试

```bash
# 测试更新检查
curl "http://localhost:9050/api/check-update?app=test-app&version=1.0.0&platform=windows&arch=amd64"

# 测试参数缺失
curl "http://localhost:9050/api/check-update?app=test-app"
```

## 📦 版本号比较规则

实现了完整的语义化版本号（semver）比较：

### 支持的版本格式

- `1.0.0` - 标准格式
- `v1.0.0` - 带 v 前缀
- `1.0.0-beta.1` - 预发布版本
- `1.0.0+build.123` - 构建元数据

### 比较规则

1. **主版本号优先**：`2.0.0 > 1.9.9`
2. **次版本号次之**：`1.10.0 > 1.9.0`
3. **修订号最后**：`1.0.10 > 1.0.9`
4. **预发布版本**：`1.0.0 > 1.0.0-rc.1 > 1.0.0-beta.1 > 1.0.0-alpha.1`

### 示例

```go
// pkg/util/version.go

CompareVersion("1.10.0", "1.9.0")      // 返回 1 (1.10.0 > 1.9.0)
CompareVersion("2.0.0", "1.99.99")     // 返回 1 (2.0.0 > 1.99.99)
CompareVersion("1.0.0", "1.0.0-beta")  // 返回 1 (正式版 > 预发布版)
CompareVersion("v1.0.0", "1.0.0")      // 返回 0 (相等)

IsNewerVersion("1.0.0", "1.1.0")       // 返回 true
IsNewerVersion("1.1.0", "1.0.0")       // 返回 false
```

## 🔄 完整更新流程

### 1. 准备数据

```powershell
# 创建应用
Invoke-RestMethod -Method POST -Uri "http://localhost:9050/api/apps" `
  -ContentType "application/json" `
  -Body '{"id":"my-app","name":"我的应用","description":"测试"}'

# 创建版本 1.0.0
Invoke-RestMethod -Method POST -Uri "http://localhost:9050/api/releases" `
  -ContentType "application/json" `
  -Body '{"appID":"my-app","version":"1.0.0","notes":"初始版本","channel":"stable","pubDate":"2026-03-10T10:00:00Z"}'

# 上传 1.0.0 的 Windows 版本
$form = @{
    file = Get-Item -Path "D:\app-v1.0.0.exe"
    platform = "windows"
    arch = "amd64"
}
Invoke-RestMethod -Uri "http://localhost:9050/api/releases/1/assets/upload" -Method Post -Form $form

# 创建版本 1.1.0
Invoke-RestMethod -Method POST -Uri "http://localhost:9050/api/releases" `
  -ContentType "application/json" `
  -Body '{"appID":"my-app","version":"1.1.0","notes":"新增功能","channel":"stable","pubDate":"2026-03-11T10:00:00Z"}'

# 上传 1.1.0 的 Windows 版本
$form = @{
    file = Get-Item -Path "D:\app-v1.1.0.exe"
    platform = "windows"
    arch = "amd64"
}
Invoke-RestMethod -Uri "http://localhost:9050/api/releases/2/assets/upload" -Method Post -Form $form
```

### 2. 客户端检查更新

```powershell
# 用户当前使用 1.0.0，检查更新
$response = Invoke-RestMethod -Uri "http://localhost:9050/api/check-update?app=my-app&version=1.0.0&platform=windows&arch=amd64"

if ($response.data.update) {
    Write-Host "发现新版本: $($response.data.version)"
    Write-Host "更新说明: $($response.data.notes)"
    Write-Host "下载地址: $($response.data.url)"
    Write-Host "校验和: $($response.data.checksum)"
    
    # 下载更新
    Invoke-WebRequest -Uri $response.data.url -OutFile "app-update.exe"
    
    # 验证校验和（可选）
    $hash = (Get-FileHash -Path "app-update.exe" -Algorithm SHA256).Hash
    if ($hash.ToLower() -eq $response.data.checksum) {
        Write-Host "✅ 文件校验通过"
    } else {
        Write-Host "❌ 文件校验失败"
    }
} else {
    Write-Host "✅ 当前已是最新版本"
}
```

## 🛡️ 错误处理

所有可能的错误情况：

| 错误信息 | 原因 | 解决方法 |
|---------|------|---------|
| `app is required` | 缺少 app 参数 | 提供应用 ID |
| `version is required` | 缺少 version 参数 | 提供当前版本号 |
| `platform is required` | 缺少 platform 参数 | 提供平台信息 |
| `arch is required` | 缺少 arch 参数 | 提供架构信息 |
| `no release found for this app` | 应用没有发布版本 | 先创建版本发布 |
| `no asset found for this platform and architecture` | 没有对应平台的安装包 | 上传对应平台的资源 |
| `asset URL is empty` | 资源记录存在但 URL 为空 | 检查资源数据完整性 |

## ✅ 改进总结

### 修复前的问题

```go
// ❌ 错误的版本比较
if req.Version >= latest.Version {  // "1.10.0" < "1.9.0" ！
    return &CheckResponse{Update: false}, nil
}

// ❌ 没有错误处理
db.Where(...).First(&asset)  // 忽略了错误
return &CheckResponse{URL: asset.URL}  // URL 可能为空
```

### 修复后

```go
// ✅ 正确的版本比较
if !util.IsNewerVersion(req.Version, latest.Version) {
    return &CheckResponse{Update: false}, nil
}

// ✅ 完整的错误处理
err = db.Where(...).First(&ast).Error
if err != nil {
    if errors.Is(err, gorm.ErrRecordNotFound) {
        return nil, errors.New("no asset found...")
    }
    return nil, err
}
```

现在更新检查功能已经完全可靠！🎉