# 更新 API 文档

本文档说明 CS工具箱 的更新检查接口格式和配置方法。

## 功能概述

CS工具箱 支持两种更新检查方式：
1. **自定义更新服务器**（优先）
2. **GitHub Release**（作为备用方案）

## 配置方法

### 方式一：环境变量（推荐）

在项目根目录创建 `.env.local` 文件：

```env
NEXT_PUBLIC_UPDATE_ENDPOINT=https://your-server.com/api/update/check
NEXT_PUBLIC_GITHUB_REPO=your-username/your-repo
```

### 方式二：代码中配置

在 `src/app/(main)/preference/general/page.tsx` 中修改：

```typescript
const customEndpoint = "https://your-server.com/api/update/check"
const githubRepo = "your-username/your-repo"
```

## 自定义更新服务器接口格式

### 请求

- **方法**: GET
- **URL**: 你配置的 `customEndpoint`
- **Headers**: 无特殊要求

### 响应格式

服务器应返回 JSON 格式的更新信息：

```json
{
  "version": "0.0.7",
  "notes": "## 更新内容\n\n- 修复了已知问题\n- 添加了新功能",
  "pub_date": "2025-01-15T10:00:00Z",
  "download_url": "https://your-server.com/releases/v0.0.7/cstb-0.0.7-x86_64.exe",
  "signature": "可选：安装包签名",
  "platforms": {
    "windows-x86_64": {
      "url": "https://your-server.com/releases/v0.0.7/cstb-0.0.7-windows-x86_64.exe",
      "signature": "可选：Windows 安装包签名"
    },
    "darwin-x86_64": {
      "url": "https://your-server.com/releases/v0.0.7/cstb-0.0.7-darwin-x86_64.dmg",
      "signature": "可选：macOS x86_64 安装包签名"
    },
    "darwin-aarch64": {
      "url": "https://your-server.com/releases/v0.0.7/cstb-0.0.7-darwin-aarch64.dmg",
      "signature": "可选：macOS Apple Silicon 安装包签名"
    },
    "linux-x86_64": {
      "url": "https://your-server.com/releases/v0.0.7/cstb-0.0.7-linux-x86_64.AppImage",
      "signature": "可选：Linux 安装包签名"
    }
  }
}
```

### 字段说明

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `version` | string | 是 | 新版本号，格式：`主版本.次版本.修订版本`（如 `0.0.7`） |
| `notes` | string | 否 | 更新说明，支持 Markdown 格式 |
| `pub_date` | string | 否 | 发布时间，ISO 8601 格式（如 `2025-01-15T10:00:00Z`） |
| `download_url` | string | 是 | 默认下载链接（如果未指定平台特定链接时使用） |
| `signature` | string | 否 | 默认安装包签名 |
| `platforms` | object | 否 | 平台特定的下载信息 |

### 平台特定配置

如果提供了 `platforms` 对象，系统会优先使用当前平台的特定链接。支持的平台标识：

- `windows-x86_64`: Windows 64位
- `darwin-x86_64`: macOS Intel
- `darwin-aarch64`: macOS Apple Silicon
- `linux-x86_64`: Linux 64位

### 简化格式（仅 Windows）

如果你只需要支持 Windows，可以简化响应：

```json
{
  "version": "0.0.7",
  "notes": "更新说明",
  "download_url": "https://your-server.com/releases/v0.0.7/cstb-0.0.7.exe"
}
```

## GitHub Release 格式

### 仓库要求

1. 在 GitHub 上创建 Release
2. Release 标签格式：`v0.0.7` 或 `0.0.7`（系统会自动移除 `v` 前缀）
3. Release 标题和说明会作为更新说明显示

### 资源文件命名

系统会自动识别以下格式的安装包：

**Windows:**
- `.exe`
- `.msi`
- 文件名包含 `windows` 和 `x86_64`

**macOS:**
- `.dmg`
- 文件名包含 `darwin` 和架构标识（`x86_64` 或 `aarch64`）

**Linux:**
- `.deb`
- `.rpm`
- `.AppImage`
- 文件名包含 `linux` 和 `x86_64`

### 推荐命名格式

```
cstb-{version}-{platform}-{arch}.{ext}
```

例如：
- `cstb-0.0.7-windows-x86_64.exe`
- `cstb-0.0.7-darwin-x86_64.dmg`
- `cstb-0.0.7-darwin-aarch64.dmg`
- `cstb-0.0.7-linux-x86_64.AppImage`

## 版本比较逻辑

系统使用简单的版本号比较：
- 按 `.`、`-`、`_` 分割版本号
- 逐段比较数字部分
- 如果新版本号大于当前版本，则提示更新

例如：
- `0.0.7` > `0.0.6` ✓
- `0.0.6-beta.4` 与 `0.0.6` 视为相等（简单比较）

## 更新流程

1. **检查更新**：用户点击"检查更新"按钮
2. **下载更新**：如果有新版本，用户确认后开始下载
3. **安装更新**：
   - Windows: 自动运行 NSIS 安装程序（静默模式）
   - macOS: 打开 DMG 文件（需用户手动安装）
   - Linux: 根据文件类型执行相应安装命令

## 示例服务器实现

### Node.js/Express 示例

```javascript
app.get('/api/update/check', (req, res) => {
  const platform = req.headers['user-agent'] || '';
  
  const updateInfo = {
    version: "0.0.7",
    notes: "## 更新内容\n\n- 修复了已知问题",
    pub_date: new Date().toISOString(),
    download_url: "https://your-server.com/releases/v0.0.7/cstb-0.0.7.exe",
    platforms: {
      "windows-x86_64": {
        url: "https://your-server.com/releases/v0.0.7/cstb-0.0.7-windows-x86_64.exe"
      }
    }
  };
  
  res.json(updateInfo);
});
```

### Python/Flask 示例

```python
from flask import Flask, jsonify
from datetime import datetime

app = Flask(__name__)

@app.route('/api/update/check')
def check_update():
    return jsonify({
        "version": "0.0.7",
        "notes": "## 更新内容\n\n- 修复了已知问题",
        "pub_date": datetime.now().isoformat() + "Z",
        "download_url": "https://your-server.com/releases/v0.0.7/cstb-0.0.7.exe",
        "platforms": {
            "windows-x86_64": {
                "url": "https://your-server.com/releases/v0.0.7/cstb-0.0.7-windows-x86_64.exe"
            }
        }
    })
```

## 注意事项

1. **HTTPS**: 建议使用 HTTPS 协议以确保安全
2. **CORS**: 如果从浏览器访问，需要配置 CORS 头
3. **超时**: 请求超时时间为 10 秒
4. **下载超时**: 下载超时时间为 5 分钟
5. **缓存**: 系统不会缓存更新信息，每次检查都会请求最新数据

## 故障排查

### 自定义服务器检查失败

1. 检查服务器是否可访问
2. 检查响应格式是否正确
3. 检查 HTTP 状态码是否为 200
4. 查看应用日志中的错误信息

### GitHub Release 检查失败

1. 确认仓库名称格式正确（`owner/repo`）
2. 确认仓库是公开的
3. 确认已创建 Release
4. 确认 Release 中有适合当前平台的资源文件

### 下载失败

1. 检查下载链接是否有效
2. 检查网络连接
3. 检查磁盘空间是否充足
4. 检查文件权限

## 测试

可以使用以下 curl 命令测试自定义服务器：

```bash
curl https://your-server.com/api/update/check
```

应该返回符合格式的 JSON 响应。