获取最新版本

1. 接口定位

• 接口名称: 获取最新版本
• 所属域: client/application
• 业务目标: 按平台查询当前最新的应用版本信息，用于客户端升级提示

2. 请求定义

• Method: POST
• Path: /application/latest_version
• Content-Type: 推荐 application/json
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 无
• 幂等性: 幂等（只读操作）

3. 请求参数

Header 参数

字段	必填	类型	说明
operationID	是	string	链路追踪 ID
token	否	string	本接口无需 token

Body 参数

字段	必填	类型	说明
platform	是	string	平台标识，如 ios、android
version	否	string	当前协议里存在，但当前实现未使用

字段约束

• platform 为空时，数据库查询会按空字符串执行，通常拿不到记录。
• version 当前不会参与任何版本比较或过滤，仅保留在协议定义中。

4. 响应结构

通用响应包裹

字段	类型	说明
errCode	int	错误码，0 表示成功
errMsg	string	错误简述
errDlt	string	错误详情
data	object	业务数据

data 字段

字段	类型	说明
version	object	最新版本对象；无记录时为空对象

version 对象

字段	类型	说明
id	string	版本记录 ID
platform	string	平台标识
version	string	版本号
url	string	下载地址
text	string	更新文案
force	bool	是否强制更新
latest	bool	是否标记为最新版本
hot	bool	是否热更新版本
createTime	int64	创建时间，毫秒时间戳

5. 业务规则

• 该接口实际由 admin 服务提供数据，但对客户端公开。
• 服务端按 platform 查询 MongoDB 中对应平台的版本记录。
• 查询排序规则为 latest desc, _id desc，因此优先返回被标记为 latest=true 的最新一条记录。
• 当指定平台没有任何版本记录时，返回成功响应，但 data.version 为空。

6. 错误码与失败场景

错误码	场景	典型报错
1001	Header 缺少 operationID	header must have operationID
-	数据库查询失败	由 MongoDB 查询链路返回

7. 示例

fetch 请求示例

fetch("http://localhost:10008/application/latest_version", {
  method: "POST",
  headers: {
    operationID: "app-latest-version-001",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    platform: "ios",
    version: "1.0.0",
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "platform": "ios",
  "version": "1.0.0"
}

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "version": {
      "id": "67ea6411c901bf3cb50ea001",
      "platform": "ios",
      "version": "1.2.3",
      "url": "https://cdn.example.com/app/ios-1.2.3.ipa",
      "text": "修复已知问题并优化启动速度",
      "force": false,
      "latest": true,
      "hot": false,
      "createTime": 1774922000000
    }
  }
}

成功响应示例（无版本记录）

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {}
}

8. 时序流程

1. 校验 operationID。
2. 解析请求体中的 platform。
3. 调用 admin 服务查询该平台的最新版本。
4. 若有记录，映射为版本对象返回。
5. 若没有记录，返回成功且不带版本对象。

9. 变更记录

• 2026-03-31: 首版发布，基于 client API 路由与 admin 版本查询实现整理。