下载量统计

1. 接口定位

• 接口名称: 下载量统计
• 所属域: admin/application
• 业务目标: 按平台和版本范围统计下载总量

2. 请求定义

• Method: POST
• Path: /adminx/application/statistic/download
• Content-Type: 推荐 application/json
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 需要 Header token，且必须是管理员 token
• 幂等性: 幂等

3. 请求参数

Header 参数

字段	必填	类型	说明
operationID	是	string	链路追踪 ID
token	是	string	管理员 token

Body 参数

字段	必填	类型	说明
platform	否	array<string>	平台过滤列表；为空表示不过滤平台
versionID	否	array<string>	版本 ID 过滤列表；为空表示统计全部版本
version	否	array<string>	版本号过滤列表（如 1.0.7）

字段约束

• versionID 与 version 二选一。
• 使用 versionID 时，每个元素都必须是合法 ObjectID。
• 使用 version 时必须同时提供 platform。
• 可同时使用 platform 与版本条件进行交集过滤。

4. 响应结构

通用响应包裹

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

data 字段

字段	类型	说明
total	int64	下载总量求和

5. 业务规则

• 未传任何过滤条件时，统计全平台、全版本下载总量。
• platform 与 versionID 都传时，按交集条件统计。
• 不存在匹配记录时返回 total=0。

6. 错误码与失败场景

错误码	场景	典型报错
1001	versionID 中存在非法值	invalid versionID
-	数据库聚合失败	由 Mongo 聚合层返回

7. 示例

fetch 请求示例

fetch("http://localhost:10011/adminx/application/statistic/download", {
  method: "POST",
  headers: {
    operationID: "app-stat-download-001",
    token: "eyJhbGciOi...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    platform: ["ios", "android"],
    versionID: ["67ea6411c901bf3cb50ea001"],
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "platform": ["ios", "android"],
  "versionID": ["67ea6411c901bf3cb50ea001"]
}

版本号请求示例（JSON）

{
  "platform": ["android"],
  "version": ["1.0.7"]
}

成功响应示例

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

8. 时序流程

1. 鉴权并校验管理员身份。
2. 解析平台与版本过滤条件。
3. 校验版本 ID 格式。
4. 执行下载量聚合求和。
5. 返回统计总量。

9. 变更记录

• 2026-04-08: 首版发布，新增下载量统计能力文档。