仪表盘数值总览

1. 接口定位

• 接口名称: 仪表盘数值总览
• 所属域: admin/statistic
• 业务目标: 聚合后台仪表盘总量类数据，减少前端多接口拼装

2. 请求定义

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

3. 请求参数

Header 参数

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

Body 参数

字段	必填	类型	说明
timezone	否	string	IANA 时区名，例如 Asia/Shanghai、UTC。为空时默认 UTC。无效值返回参数错误

请求示例（JSON）

{
  "timezone": "Asia/Shanghai"
}

4. 响应结构

通用响应包裹

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

data 字段

字段	类型	说明
totalUserCount	int64	总用户数（当前口径与 allTimeUserCount 一致）
totalGroupCount	int64	总群组数（当前口径与 allTimeGroupCount 一致）
blockedUserCount	int64	总用户封禁
forbiddenIPCount	int64	总禁止 IP
appDownloadTotal	int64	app 累计下载量
canceledUserCount	int64/null	已注销用户数；当前版本不支持，返回 null
dissolvedGroupCount	int64/null	已解散群组数；当前版本不支持，返回 null
allTimeUserCount	int64/null	历史累计用户数；当前版本返回值可用
allTimeGroupCount	int64/null	历史累计群组数；当前版本返回值可用
todayRegisterCount	int64	今日新增注册用户数（按 timezone 口径）
yesterdayRegisterCount	int64	昨日新增注册用户数（按 timezone 口径）
fifteenDayRegisterCount	int64	近十五日新增注册用户数（含今日，按 timezone）
todayLoginCount	int64	今日登录用户数（按 timezone 口径）
yesterdayLoginCount	int64	昨日登录用户数（按 timezone 口径）
fifteenDayLoginCount	int64	近十五日登录用户数（含今日，按 timezone）
statTime	int64	统计时间戳（Unix 毫秒）
capability	object	可用能力声明

capability 字段

字段	类型	说明
supportCanceledUserCount	bool	是否支持 canceledUserCount
supportDissolvedGroupCount	bool	是否支持 dissolvedGroupCount

5. 业务规则

• 本接口为 adminx 聚合能力，统一承载仪表盘总量类数据。
• 为降低跨服务与数据库压力，接口结果会进行 15 秒短缓存，存在秒级延迟。
• 缓存按 timezone 分桶，不同时区不会复用同一缓存结果。
• 口径定义：
  • 今日：[今日 00:00, 当前时刻)
  • 昨日：[昨日 00:00, 今日 00:00)
  • 近十五日：[14 天前 00:00, 当前时刻)
• canceledUserCount 与 dissolvedGroupCount 当前版本能力未就绪，固定返回 null，并通过 capability 声明为 false。
• allTimeUserCount 与 allTimeGroupCount 当前可返回有效值。

6. 示例

fetch 请求示例

fetch("http://localhost:10011/adminx/statistic/overview_value", {
  method: "POST",
  headers: {
    operationID: "adminx-overview-value-001",
    token: "eyJhbGciOi...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ timezone: "Asia/Shanghai" }),
})
  .then((res) => res.json())
  .then((data) => console.log(data));

成功响应示例

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "totalUserCount": 10240,
    "totalGroupCount": 980,
    "blockedUserCount": 126,
    "forbiddenIPCount": 43,
    "appDownloadTotal": 582190,
    "canceledUserCount": null,
    "dissolvedGroupCount": null,
    "allTimeUserCount": 10240,
    "allTimeGroupCount": 980,
    "todayRegisterCount": 48,
    "yesterdayRegisterCount": 67,
    "fifteenDayRegisterCount": 812,
    "todayLoginCount": 526,
    "yesterdayLoginCount": 744,
    "fifteenDayLoginCount": 6421,
    "statTime": 1780224203000,
    "capability": {
      "supportCanceledUserCount": false,
      "supportDissolvedGroupCount": false
    }
  }
}

7. 变更记录

• 2026-05-31: 首版发布，新增 adminx 仪表盘数值总览接口。
• 2026-05-31: 增加 timezone 参数与注册/登录今日、昨日、近十五日单值字段。