addd

2026-09-28 13:14:50 +08:00
1 parent a6c12f161a
commit e6f7de88d7
@@ -0,0 +1,88 @@
+# 客户端软件包
+
+以下是客户端软件包相关接口的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`。
@@ -0,0 +1 @@
+123