# 客户端软件包

以下是客户端软件包相关接口的API文档。

## 查看最新版本

查询指定客户端（`identity`）的最新版本信息，若带 `canary=true` 且当前登录用户在灰度范围内，则查询范围覆盖灰度版，否则仅返回正式版。

- 请求地址：/client/software/latest
- 请求方式：GET

### 请求参数

| 参数名称 | 是否必传 | 类型 | 描述 |
|:-----|:-----|:-----|:-----|
| identity | 是 | String | 客户端标识，示例：devco |
| canary | 否 | Boolean | 传true则查询范围覆盖灰度版，否则只查正式版；不传等同于false |

### 请求示例

```bash
curl -X GET {gateway}/client/software/latest?identity=devco&canary=true
```

### 响应参数

| 参数名称 | 类型 | 描述 |
|:-----|:-----|:-----|
| code | Number | 返回码（200=成功） |
| msg | String | 提示信息 |
| data | Object | 版本信息；无匹配版本时为 null |
| data.releaseId | String | 版本记录 ID（Long 序列化为字符串） |
| data.versionNo | String | 版本号，如 1.0.0 |
| data.releaseTime | String | 发布时间，格式 yyyy-MM-dd HH:mm:ss（GMT+8） |
| data.releaseNotes | String | 更新内容 |
| data.packageOssId | String | 安装包 OSS 主键（Long 序列化为字符串）；前端据此请求预签名下载地址 |
| data.packageName | String | 安装包文件名 |
| data.packageSize | Number | 安装包大小（字节） |
| data.packageSizeDisplay | String | 安装包大小展示文案，如 12.50 MB |
| data.state | String | 版本状态：canary=灰度版、release=正式版 |

### 成功示例

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "releaseId": "1928374655647382",
        "versionNo": "1.0.0",
        "releaseTime": "2026-09-28 10:00:00",
        "releaseNotes": "修复已知问题，优化启动速度",
        "packageOssId": "1928374655647383",
        "packageName": "devco-1.0.0-setup.exe",
        "packageSize": 13107200,
        "packageSizeDisplay": "12.50 MB",
        "state": "release"
    }
}
```

### 无版本示例

查询范围内没有任何版本时，`data` 为 `null`：

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": null
}
```

### 失败示例

```json
{
    "code": 500,
    "msg": "错误信息"
}
```

### 备注

- 结果按 `releaseTime` 倒序取第一条，即为最新版本。
- 未登录（`LoginHelper.getLoginUser()` 为 null）时仅返回正式版，忽略 `canary`。
- `packageName`、`packageSize`、`packageSizeDisplay` 在数据库未记录安装包信息时，会尝试从 OSS 元数据补全；OSS 查询失败时保持为空，不影响接口返回。
- 下载安装包请调用 `GET /client/software/download/{ossId}`，其中 `ossId` 取 `data.packageOssId`。