分页查询版本列表

1. 接口定位

• 接口名称: 分页查询版本列表
• 所属域: admin/application
• 业务目标: 按平台列表筛选并分页返回应用版本记录

2. 请求定义

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

路径定位说明

• /application/page_versions 属于 Admin 主域的基础能力接口。
• 该接口强调“主域数据服务”语义，而不是 AdminX 扩展域入口。
• 若使用 AdminX 扩展后台链路，请参考: 分页查询版本列表（AdminX 扩展后台接口）。

3. 请求参数

Header 参数

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

Body 参数

字段	必填	类型	说明
platform	否	array<string>	平台过滤列表；为空时不过滤平台
pagination	是	object	分页参数

pagination 字段

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

字段约束

• 当前协议层没有为本接口定义显式 Check() 校验。
• 建议始终传入完整 pagination；当前实现会直接把分页结构透传给数据库分页层。

4. 响应结构

通用响应包裹

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

data 字段

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

versions 元素字段

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

5. 业务规则

• 本接口无需鉴权，admin 与 chat 侧都可调用同一条业务链路。
• platform 不为空时，数据库按 platform in [...] 做精确过滤。
• 排序规则固定为 latest desc, _id desc。
• AdminX 可复用该基础查询能力，但不改变此接口的主域归属。

6. 错误码与失败场景

错误码	场景	典型报错
-	数据库分页查询失败	由数据库层返回原始错误

7. 示例

fetch 请求示例

fetch("http://localhost:10009/application/page_versions", {
  method: "POST",
  headers: {
    operationID: "550e8400-e29b-41d4-a716-446655440705",
    "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": "67ea5ef1b9f35d6a63717811",
        "platform": "ios",
        "version": "1.2.0",
        "url": "https://example.com/downloads/openim-ios-1.2.0.ipa",
        "text": "bug fixes and performance improvements",
        "force": false,
        "latest": true,
        "hot": false,
        "createTime": 1767225600000
      }
    ]
  }
}

8. 时序流程

1. 解析平台过滤列表与分页参数。
2. 在 application 集合中按 platform 条件分页查询。
3. 按 latest desc, _id desc 排序。
4. 将数据库记录映射为 ApplicationVersion 列表并返回。

9. 变更记录

• 2026-03-31: 首版发布，基于应用版本分页过滤与排序逻辑补全文档。