上报下载行为

1. 接口定位

• 接口名称: 上报下载行为
• 所属域: chat/application
• 业务目标: 客户端在触发下载时上报一次下载事件，用于下载量统计

2. 请求定义

• Method: POST
• Path: /chatx/application/report_download
• Content-Type: 推荐 application/json
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 无
• 幂等性: 非严格幂等（服务端会按时间窗口去重）

3. 请求参数

Header 参数

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

Body 参数

字段	必填	类型	说明
versionID	条件	string	版本记录 ID（ObjectID）
platform	否	string	平台标识（如 ios、android）
version	否	string	版本号（如 1.0.7）

字段约束

• versionID 与 platform + version 二选一。
• 传 versionID 时必须是合法的 Mongo ObjectID 字符串。
• 未传 versionID 时必须同时提供 platform 与 version。
• 服务端会结合 IP + User-Agent + 10 分钟桶 做去重。

4. 响应结构

通用响应包裹

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

data 字段

字段	类型	说明
accepted	bool	是否被计入统计
duplicated	bool	是否被判定为重复上报

5. 业务规则

• 同一 versionID 在短时间内重复上报会被去重，避免重复累计下载量。
• 服务端对同一 IP 做分钟级限流；超限请求会返回成功包裹但 accepted=false。
• 当 versionID 不存在时，请求失败。

6. 错误码与失败场景

错误码	场景	典型报错
1001	versionID 非法	invalid versionID
1001	版本不存在	version not found
-	Redis 或数据库访问失败	由底层依赖错误透传

7. 示例

fetch 请求示例

fetch("http://localhost:10010/chatx/application/report_download", {
  method: "POST",
  headers: {
    operationID: "app-report-download-001",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    versionID: "67ea6411c901bf3cb50ea001",
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "versionID": "67ea6411c901bf3cb50ea001"
}

版本号上报示例（JSON）

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

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "accepted": true,
    "duplicated": false
  }
}

去重响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "accepted": false,
    "duplicated": true
  }
}

8. 时序流程

1. 校验 operationID 与请求体。
2. 校验 versionID 格式。
3. 执行 IP 限流判断。
4. 执行下载去重判断。
5. 去重通过后累加下载计数并返回。

9. 变更记录

• 2026-04-08: 首版发布，新增下载行为上报能力文档。