分页查询版本列表

1. 接口定位

• 接口名称: 分页查询版本列表
• 所属域: client/application
• 业务目标: 按平台分页拉取应用版本记录列表，用于客户端版本历史展示或调试排查

2. 请求定义

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

3. 请求参数

Header 参数

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

Body 参数

字段	必填	类型	说明
platform	否	array<string>	平台过滤列表；为空表示不过滤平台
pagination	是	object	分页参数，要求传 pageNumber/showNumber

pagination 对象

字段	必填	类型	说明
pageNumber	是	int32	页码，从 1 开始
showNumber	是	int32	每页条数

4. 响应结构

通用响应包裹

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

data 字段

字段	类型	说明
total	int64	总记录数
versions	array<object>	当前页版本列表

version 对象

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

5. 业务规则

• 该接口实际由 admin 服务提供数据，但对客户端公开。
• platform 为空时，返回所有平台的版本记录。
• 查询排序规则为 latest desc, _id desc。
• pagination 是数据库分页的必填参数；为空时底层分页查询会报错。

6. 错误码与失败场景

错误码	场景	典型报错
1001	Header 缺少 operationID	header must have operationID
1001	pagination 为空或非法	由分页校验链路返回，如 Pagination is nil
-	数据库查询失败	由 MongoDB 查询链路返回

7. 示例

fetch 请求示例

fetch("http://localhost:10008/application/page_versions", {
  method: "POST",
  headers: {
    operationID: "app-page-versions-001",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    platform: ["ios", "android"],
    pagination: {
      pageNumber: 1,
      showNumber: 20,
    },
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "platform": ["ios", "android"],
  "pagination": {
    "pageNumber": 1,
    "showNumber": 20
  }
}

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "total": 2,
    "versions": [
      {
        "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
      }
    ]
  }
}

8. 时序流程

1. 校验 operationID。
2. 解析 platform 过滤条件与分页参数。
3. 调用 admin 服务分页查询版本记录。
4. 将查询结果映射为版本对象列表返回。

9. 变更记录

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