上报安装行为

1. 接口定位

• 接口名称: 上报安装行为
• 所属域: chat/application
• 业务目标: 客户端安装完成后上报一次安装事件，用于安装量统计

2. 请求定义

• Method: POST
• Path: /chatx/application/report_install
• Content-Type: 推荐 application/json
• operationID: 必填，请通过 Header operationID 传入
• 鉴权: 无
• 幂等性: 近似幂等（按 versionID + installID 去重）

3. 请求参数

Header 参数

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

Body 参数

字段	必填	类型	说明
versionID	条件	string	版本记录 ID（ObjectID）
platform	否	string	平台标识（如 ios、android）
version	否	string	版本号（如 1.0.7）
installID	是	string	设备安装标识（客户端生成并持久化）

字段约束

• versionID 与 platform + version 二选一。
• 传 versionID 时必须是合法的 Mongo ObjectID 字符串。
• 未传 versionID 时必须同时提供 platform 与 version。
• installID 不能为空。
• 服务端按 versionID + installID 长周期去重。

4. 响应结构

通用响应包裹

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

data 字段

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

5. 业务规则

• 同一 versionID + installID 仅会被累计一次安装量。
• 服务端对同一 IP 做分钟级限流；超限请求返回 accepted=false。
• 当 versionID 不存在时，请求失败。

6. 错误码与失败场景

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

7. 示例

fetch 请求示例

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

请求示例（JSON）

{
  "versionID": "67ea6411c901bf3cb50ea001",
  "installID": "ios-device-install-id-001"
}

版本号上报示例（JSON）

{
  "platform": "android",
  "version": "1.0.7",
  "installID": "android-install-id-001"
}

成功响应示例

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

去重响应示例

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

8. 时序流程

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

9. 变更记录

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