查询用户基础统计¶
请求参数¶
面向后台账号列表顶部。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。真实页面四语桌面/手机布局与筛选后统计不变已验证,数字与运行库只读聚合核对一致;运行库没有注入统计示例账号。