新增用户数统计

1. 接口定位

• 接口名称: 新增用户数统计
• 所属域: admin/statistic
• 业务目标: 统计时间范围内的注册用户总量和按天分布

2. 请求定义

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

3. 请求参数

Header 参数

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

Body 参数

字段	必填	类型	说明
start	是	int64	统计开始时间，Unix 毫秒时间戳
end	是	int64	统计结束时间，Unix 毫秒时间戳

字段约束

• start 不能大于 end。
• 统计区间会被转换为 time.UnixMilli(start/end) 后传给 OpenIM 统计接口。

4. 响应结构

通用响应包裹

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

data 字段

字段	类型	说明
total	int64	当前系统累计注册用户总数，不仅限于区间内
date_count	map<string, int64>	区间内按日期聚合的新增用户数

5. 业务规则

• API 层会先获取默认 OpenIM 管理员 token，再调用 OpenIM 的 /statistics/user/register 统计能力。
• total 不是区间注册总数，而是系统当前累计注册用户总量。
• date_count 才表示 start-end 区间内的每日新增分布。

6. 错误码与失败场景

错误码	场景	典型报错
1001	start > end	start > end
-	获取默认 IM 管理员 token 失败	由 OpenIM token 链路返回
-	调用注册统计接口失败	由 OpenIM 用户统计链路返回

7. 示例

fetch 请求示例

fetch("http://localhost:10009/statistic/new_user_count", {
  method: "POST",
  headers: {
    operationID: "550e8400-e29b-41d4-a716-446655440204",
    token: "eyJhbGciOi...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    start: 1774905600000,
    end: 1775164800000,
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

请求示例（JSON）

{
  "start": 1774905600000,
  "end": 1775164800000
}

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "total": 1024,
    "date_count": {
      "2026-03-29": 18,
      "2026-03-30": 25,
      "2026-03-31": 21
    }
  }
}

失败响应示例

{
  "errCode": 1001,
  "errMsg": "ArgsError",
  "errDlt": "start > end"
}

8. 时序流程

1. 中间件校验管理员 token。
2. 解析 start/end 时间范围。
3. 获取默认 OpenIM 管理员 token。
4. 调用 OpenIM 注册统计接口。
5. 将累计总量和日期分布重新组装后返回。

9. 变更记录

• 2026-03-31: 首版发布，基于 admin API 新增用户统计逻辑与 OpenIM 用户统计实现补全文档。