GET/api/v1/admin/users/statistics
管理员Cookie,ADMIN_USERS_READJSON 响应接入指南 ↗

查询用户基础统计

请求参数

面向后台账号列表顶部。OWNER和VIEWER拥有ADMIN_USERS_READ可调用;必须可信HTTPS、独立Cookie及真实JWE,不接受App Bearer。八项公共请求头必填,固定admin/web/admin_web。来源限制遵循后台安全协议。

无路径参数、查询参数或业务请求体;无需传日期、客户端统计值、分页或列表筛选。统计所有账号,包含ACTIVE/DISABLED/DELETED墓碑、资料完成/未完成,未知性别单独计数;不包含管理员账号。

“今日”是Asia/Shanghai自然日的新增注册:创建时间大于等于当天00:00,小于次日00:00。它不是今日登录人数、活跃人数或当前在线人数;用户修改资料不改变注册时间。

请求示例

统一加密封装示例;installationId为当前浏览器持久UUID,codec为createJweEncryption实例,Cookie由浏览器维护。

const url = new URL('/api/v1/admin/users/statistics', location.origin);
const headers = {
  'Accept-Language': 'zh-CN',
  'X-Client-Type': 'admin', 'X-Platform': 'web',
  'X-App-Version': '1.0.0', 'X-App-Build': '1', 'X-Channel': 'admin_web',
  'X-Device-Id': installationId,
  'X-Request-Id': crypto.randomUUID(), 'X-Request-Timestamp': String(Date.now()),
};
const encrypted = await codec.prepare({url, method: 'GET', headers, body: null});
const response = await fetch(url, {headers: encrypted.headers,
  credentials: 'same-origin', redirect: 'error'});
const payload = await encrypted.decode(response);

外层Accept为application/jose,GET密文置于X-Budyoo-JWE,不发送普通JSON正文;详情见AES协议。

成功响应

HTTP200,Cache-Control:no-store,实际外层为JWE,解密后合成示例:

{
  "code": "SUCCESS",
  "message": "操作成功。",
  "data": {
    "total": 120,
    "registeredToday": 8,
    "male": 50,
    "female": 60,
    "genderUnset": 10,
    "date": "2026-11-03",
    "timeZone": "Asia/Shanghai",
    "generatedAt": "2026-11-03T08:00:00Z"
  },
  "errors": []
}
字段 类型/可空 含义
total 非负integer,不为null 全部App用户账号数,不受列表筛选影响
registeredToday 非负integer,不为null 统计日期内新创建的账号数
male/female 非负integer,不为null 已保存性别分别为male/female的人数
genderUnset 非负integer,不为null 尚无资料或尚未设置性别的人数;total=male+female+genderUnset
date YYYY-MM-DD string,不为null 本次统计使用的自然日
timeZone string,不为null 固定Asia/Shanghai,不由浏览器时区或语言决定
generatedAt ISO 8601 string,不为null 本次开始读取统计的服务端时间,带时区

一条数据库聚合取得同一快照,空库返回真实零值;不扫描当前分页条目估算总数。只返回统计数字,不返回联系方式、性别明细、凭据或个人资料。

失败响应

HTTP code 条件
400 INVALID_CLIENT_HEADERS 必填公共头缺失、重复或不合法
400 ENCRYPTION_REQUIRED/INVALID_ENCRYPTED_REQUEST 缺失真实JWE或信封校验失败
401 UNAUTHORIZED Cookie无效、安装不匹配、匿名或使用App凭据
403 FORBIDDEN/ADMIN_CSRF_INVALID 权限或来源不符
426 HTTPS_REQUIRED 使用明文HTTP
429 TOO_MANY_REQUESTS 来源或网关限流
503 SERVICE_UNAVAILABLE 数据库/Redis不可用;不返回伪造零值
{"code":"SERVICE_UNAVAILABLE","message":"按Accept-Language生成的本地化提示","data":null,"errors":[]}

错误遵循公共协议,四语提示及英文回退保持一致;无法建立JWE上下文的失败不能作为已认证业务结果。

接入说明

后台进入账号列表或点击刷新时读取;搜索和翻页只更新列表,顶部统计仍是全量口径。网页将今日注册、用户总数、男生、女生、未设置性别显示为五个紧凑统计项,未设置性别使用圆形Budyoo Logo,统计日期及北京时间在下方统一说明。失败显示错误与重试;尚未获取时使用占位符。它是读取时的快照,不承诺实时推送。五张统计卡片均可点击,通过账号列表的statistic=TODAY/ALL/MALE/FEMALE/GENDER_UNSET在服务端筛选;点击清空其他条件并回到第一页,之后可叠加原有查询。当前项亮黄描边,支持键盘,用户总数或重置恢复全部;统计仍为全量,不随筛选缩小。今日分类与本接口共用北京时间自然日边界,点击今日时同步重新读取统计;两个独立请求遇到新增注册或跨日时仍可能短暂不同。

实现由admin/users编排日期和DTO,profile/api提供聚合,SQL只在profile/repository。新增统计不修改账号,不创建迁移,不提供日活、在线、趋势或报表导出。服务器282项整合回归通过,新增4项覆盖空库、北京时间午夜左右边界、未知性别/缺少资料/禁用账号、独立于列表筛选、四语JWE、OWNER/VIEWER、匿名/HTTP/App凭证/缺头拒绝及数据库失败503。真实页面四语桌面/手机布局与筛选后统计不变已验证,数字与运行库只读聚合核对一致;运行库没有注入统计示例账号。