登录用户数统计

1. 接口定位

• 接口名称: 登录用户数统计
• 所属域: admin/statistic
• 业务目标: 统计时间范围内的登录用户数、未登录用户数和每日登录分布

2. 请求定义

• Method: POST
• Path: /statistic/login_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。

4. 响应结构

通用响应包裹

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

data 字段

字段	类型	说明
loginCount	int64	区间内发生登录的用户数
unloginCount	int64	当前累计用户总数减去 loginCount 的结果
count	map<string, int64>	区间内按日期聚合的登录用户数

5. 业务规则

• API 层只是鉴权后透传到 chat UserLoginCount RPC。
• chat 统计逻辑会先取当前累计用户总数，再统计区间登录数，因此 unloginCount 表示“当前累计用户总数 - 区间登录用户数”，不是“区间内未登录新增用户数”。
• count 的 key 为日期字符串，value 为当天登录用户数。

6. 错误码与失败场景

错误码	场景	典型报错
1001	start > end	start > end
-	查询累计用户总数失败	由数据库层返回
-	查询登录统计失败	由数据库层返回

7. 示例

fetch 请求示例

fetch("http://localhost:10009/statistic/login_user_count", {
  method: "POST",
  headers: {
    operationID: "550e8400-e29b-41d4-a716-446655440205",
    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": {
    "loginCount": 640,
    "unloginCount": 384,
    "count": {
      "2026-03-29": 120,
      "2026-03-30": 258,
      "2026-03-31": 262
    }
  }
}

失败响应示例

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

8. 时序流程

1. 中间件校验管理员 token。
2. 解析 start/end 时间范围。
3. chat RPC 校验 start <= end。
4. 统计累计用户总数和区间登录数据。
5. 计算 unloginCount 并返回每日登录分布。

9. 变更记录

• 2026-03-31: 首版发布，基于 admin API 登录统计路由和 chat 登录统计实现补全文档。