# Nanami 启动器 API 文档

> Base URL: `https://nanami.rucky.cn`（或对应部署地址）
>
> 标注说明：🆕 新增 | ✏️ 有变动 | 无标注为原有不变

---

## 1. 检查更新 ✏️

检查指定软件是否有新版本。

```
GET /api/software/check-update?slug={slug}&versionCode={versionCode}
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| slug | string | 是 | 软件标识，如 `nanami-launcher` 或 `nanami-launcher-patch` |
| versionCode | number | 否 | 当前客户端版本号（整数），不传默认为 0 |

**响应示例：**

```json
{
  "hasUpdate": true,
  "forceUpdate": false,
  "latest": {
    "version": "1.3.0",
    "versionCode": 130,
    "changelog": "- 修复xxx\n- 新增xxx",
    "downloadUrl": "https://nanami.rucky.cn/api/software/download/clxxx?source=launcher",
    "fileSize": 52428800,
    "minVersion": "1.0.0",
    "createdAt": "2026-03-25T10:00:00.000Z"
  }
}
```

**✏️ 变动说明**：返回的 `downloadUrl` 现在自动附带 `?source=launcher` 参数，启动器直接使用该 URL 下载即可，下载量会被单独统计为「客户端更新下载」，与网页端下载区分。启动器无需做任何额外处理。

---

## 2. 下载文件 ✏️

根据版本 ID 下载文件。通常不需要手动拼接，直接使用 check-update 返回的 `downloadUrl` 即可。

```
GET /api/software/download/{versionId}?source={source}
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| versionId | string | 是 | 路径参数，版本记录 ID |
| source | string | 否 | 下载来源标识，传 `launcher` 表示客户端更新下载 |

**响应**：

- 本地文件：直接返回二进制流（`Content-Type: application/octet-stream`）
- 外链文件：302 重定向到外部 URL

**✏️ 变动说明**：新增 `source` 查询参数。当 `source=launcher` 时，下载量会同时计入总下载量和启动器更新下载量两个计数器。check-update 返回的 URL 已自动包含此参数，启动器无需手动处理。

---

## 3. 获取最新版本信息（网页用）

获取 nanami-launcher 的最新版本信息或直接下载，主要给网页端使用。

```
GET /api/software/latest?info=1&track=1
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| info | string | 否 | 传 `1` 返回 JSON 元数据；不传则直接下载文件 |
| track | string | 否 | 仅在 `info=1` 时生效，传 `1` 同时计数下载量 |

**响应示例（info=1）：**

```json
{
  "available": true,
  "version": "1.3.0",
  "versionCode": 130,
  "changelog": "...",
  "fileSize": 52428800,
  "createdAt": "2026-03-25T10:00:00.000Z",
  "downloadUrl": "/api/software/download/clxxx",
  "downloadType": "local"
}
```

> 此接口固定查询 slug 为 `nanami-launcher` 的软件，启动器通常使用 check-update 接口而非此接口。

---

## 4. 上报心跳（在线状态） 🆕

启动器定期调用此接口上报在线状态，建议每 **60 秒** 调用一次。超过 3 分钟无心跳视为离线。

```
POST /api/launcher/heartbeat
Content-Type: application/json
```

**请求体：**

```json
{
  "deviceId": "unique-machine-id",
  "os": "Windows",
  "osVersion": "10.0.19045",
  "appVersion": "1.3.0"
}
```

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| deviceId | string | **是** | 设备唯一标识，建议使用机器码或 UUID 持久化存储 |
| os | string | 否 | 操作系统名称，如 `Windows`、`macOS`、`Linux` |
| osVersion | string | 否 | 系统版本号，如 `10.0.19045`、`14.3` |
| appVersion | string | 否 | 启动器版本号，如 `1.3.0` |

**响应：**

```json
{ "ok": true }
```

**实现建议**：
- 启动器启动时立即发送一次心跳，之后每 60 秒发送一次
- `deviceId` 需要在客户端持久化保存，确保同一台机器始终使用相同 ID
- IP 地址由服务端自动获取，无需客户端上报
- 网络失败时静默忽略即可，不影响启动器正常功能

---

## 5. 历史更新日志 🆕

查询指定软件的所有版本历史和更新日志，按版本号倒序排列。

```
GET /api/software/changelog?slug={slug}
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| slug | string | 是 | 软件标识，如 `nanami-launcher` 或 `nanami-launcher-patch` |

**响应示例：**

```json
{
  "name": "Nanami 启动器（全量包）",
  "slug": "nanami-launcher",
  "versions": [
    {
      "version": "1.3.0",
      "versionCode": 130,
      "changelog": "- 新增xxx\n- 修复xxx",
      "fileSize": 52428800,
      "isLatest": true,
      "forceUpdate": false,
      "createdAt": "2026-03-25T10:00:00.000Z"
    },
    {
      "version": "1.2.0",
      "versionCode": 120,
      "changelog": "- 优化xxx",
      "fileSize": 50331648,
      "isLatest": false,
      "forceUpdate": false,
      "createdAt": "2026-03-10T08:00:00.000Z"
    }
  ]
}
```

**响应字段说明：**

| 字段 | 类型 | 说明 |
|------|------|------|
| versions[].version | string | 版本号 |
| versions[].versionCode | number | 版本号（整数），用于比较大小 |
| versions[].changelog | string | 更新日志内容 |
| versions[].fileSize | number | 文件大小（字节） |
| versions[].isLatest | boolean | 是否为当前最新版本 |
| versions[].forceUpdate | boolean | 是否为强制更新版本 |
| versions[].createdAt | string | 发布时间（ISO 8601） |

---

## 接口一览

| 方法 | 路径 | 状态 | 用途 |
|------|------|------|------|
| GET | `/api/software/check-update` | ✏️ 变动 | 检查更新，downloadUrl 已含 source 标记 |
| GET | `/api/software/download/{id}` | ✏️ 变动 | 下载文件，支持 source 参数区分来源 |
| GET | `/api/software/latest` | 无变动 | 获取最新版信息/下载（网页用） |
| GET | `/api/software/changelog` | 🆕 新增 | 查询历史更新日志 |
| POST | `/api/launcher/heartbeat` | 🆕 新增 | 上报在线状态 |