BFF Messenger OPS CONSOLE
只读视图 · admin

统计接口 契约 · 待接入

数据概览页的所有数字都来自这一个接口:按 App、按日 / 周 / 月返回新增与活跃。本文定义请求参数、响应结构、汇总口径与降级行为,页面实现已按此约定取数。

方法 / 路径
GET /api/stats
鉴权
Cookie · Session
维度
day / week / month
时区
Asia/Shanghai

01请求

同一域名下取数可避免跨域;页面用 credentials: "include" 携带登录态。

curl
curl -s "https://bffmsg.fullstorynovel.com/api/stats?app=bff&dim=day" \
  -H "Accept: application/json" \
  --cookie "session=<sid>"
参数类型说明默认
appstringall 或 App id(如 bff、fsn);all 返回各 App 的汇总all
dimstringday / week / month,决定主数组的粒度与长度day
from
to
dateYYYY-MM-DD,闭区间;缺省时按 dim 取最近 30 天 / 12 周 / 12 月—
tzstringIANA 时区名,影响「今日」与自然周/月的边界Asia/Shanghai

02响应

HTTP 200,application/json。三个时间数组始终同时返回,页面按 dim 取用其中之一。

json
{
  "generatedAt": "2026-11-22T17:00:00+08:00",
  "app": "bff",
  "appName": "BFF Messenger",
  "total": 217463,          // 累计用户
  "day": [
    { "label": "11-20", "new": 391, "active": 5168 },
    { "label": "11-21", "new": 468, "active": 5813 },
    { "label": "11-22", "new": 458, "active": 5743 }
  ],
  "week": [
    { "label": "11-16~11-22", "new": 2724, "active": 11103 }
  ],
  "month": [
    { "label": "2026-11", "new": 14650, "active": 32540 }
  ],
  "platform": [
    { "name": "Android", "value": 63 },
    { "name": "iOS", "value": 31 },
    { "name": "Web", "value": 6 }
  ],
  "retention": [
    { "name": "次日", "value": 40.8 },
    { "name": "3 日", "value": 29.0 },
    { "name": "7 日", "value": 17.8 },
    { "name": "30 日", "value": 9.5 }
  ],
  "apps": [
    { "id": "bff", "name": "BFF Messenger" },
    { "id": "fsn", "name": "FullStoryNovel" }
  ]
}
字段类型约定
generatedAtstringISO 8601,必须带时区偏移,用于判断数据新鲜度
totalint累计注册用户;app=all 时为各 App 之和
day[]
week[]
month[]
object[]至少 2 条才能算环比;页面绘图取末尾 12 条,明细表取末尾 10 天 / 8 周 / 8 月
platform[]object[]{name, value},value 为百分比,合计应为 100
retention[]object[]{name, value},value 为 0–100 的百分比
apps[]object[]{id, name} 清单,用于渲染 App 下拉框
数组元素类型约定
labelstring日:MM-DD;周:MM-DD~MM-DD(周一→周日);月:YYYY-MM
newint该周期新增注册数,≥ 0
activeint该周期活跃数:日 = DAU、周 = WAU、月 = MAU,≥ 0

03汇总口径

选择「全部 App」时,页面直接使用接口返回的 all 数据,不做二次加总,避免口径重复。

指标app = 单个 Appapp = all
新增 / 活跃该 App 周期值各 App 同期之和(新增可加;活跃按去重口径由服务端聚合)
累计用户该 App 累计注册各 App 累计之和
平台分布该 App 活跃用户占比按各 App 最新一期活跃加权平均
留存该 App 分档留存率同上,加权平均
注意:多 App 的活跃去重只能由服务端完成(同一设备跨 App 的情形按业务定义处理),前端不要用各 App 活跃数直接相加后声称是 DAU。

04错误与降级

页面当前对失败的策略是「静默保留示例数据」,上线前建议按状态码给出提示。

状态码含义页面当前行为 / 建议
401 / 403未登录或无权限保留示例数据;建议跳转登录或显示「无权限」
404app 或 dim 不存在忽略响应;服务端应校验 app 白名单
429限流保留示例数据;建议按 Retry-After 退避
5xx服务端异常同上,并记录 trace id

05接入步骤

  1. 实现接口:按上表返回 JSON,app 与 dim 必做白名单校验,其余参数可忽略。
  2. 同域部署:把接口挂在同一域名(推荐 /api/stats)并沿用现有 nginx;若必须跨域,需返回 Access-Control-Allow-Origin(不可用 *)且带 Access-Control-Allow-Credentials: true。
  3. 改一处常量:把 index.html 顶部 STATS_API 填成接口地址;返回真实数据后删掉头部「示例数据」徽章。
js · index.html
// 留空 → 使用示例数据;填入后按 app + dim 取数
var STATS_API = "/api/stats";