统计与分析接口（5 类 22 接口）

基础URL: https://tools.wktyl.com
维护: Xianyan 团队 | 更新时间: 2026-08-15
跳转: 用户中心 · 管理后台 · 用户安全

职责：埋点事件接收 + 用户行为分析 + 站点总览数据 + 行为趋势。

1. 通用约定

1.1 响应格式

统一 {code, msg, time, data}。统计相关接口响应额外带 meta：

{
  "code": 1,
  "data": [ ... ],
  "meta": { "count": 1234, "from": 0, "size": 20, "aggregations": {} }
}

1.2 频率限制

• 埋点事件上报：POST /api/stats/event 200/60s
• 数据查询：60/60s
• 数据导出（管理员）：5/300s

2. 接口清单

2.1 埋点事件上报

• POST /api/stats/event — 上报单个事件（通用）
• POST /api/stats/event/batch — 批量上报
• POST /api/stats/performance — 性能数据上报（FMP / LCP / 网络延迟）
• POST /api/stats/error — 错误日志上报

事件结构：

{
  "event_name": "click",
  "target_type": "button",
  "target_id": "submit",
  "page_url": "/login",
  "user_id": 12345,          // 可选，未登录填 null
  "session_id": "abc",
  "properties": { "x": 100 }, // 自定义属性
  "client_time": 1777156407000
}

2.2 站点总览

• GET /api/stats/overview — 主统计面板（PV/UV/IP、来源分布、趋势）
• GET /api/stats/overview/realtime — 实时统计（过去 5 分钟）
• GET /api/stats/dashboard — 后台数据看板（含日活、注册、活跃）
• GET /api/stats/trend?dimension=day|week|month&period=30d — 趋势数据

2.3 来源分析

• GET /api/stats/source — 来源分布（搜索引擎/直接访问/外链/广告）
• GET /api/stats/keyword — 搜索关键词分布
• GET /api/stats/landing — 着陆页统计
• GET /api/stats/country — 地域分布（国家/省份/城市）

2.4 页面分析

• GET /api/stats/page/list?page=...&sort=pv|uv — 页面列表（按 PV/UV）
• GET /api/stats/page/{path} — 页面详情（含入口/出口/平均停留）
• GET /api/stats/page/heatmap?path=/home — 页面点击热力图
• GET /api/stats/exitPages — 高跳出率页面

2.5 用户行为

• GET /api/stats/user/funnel?funnel_id=register — 转化漏斗
• GET /api/stats/user/retention?cohort=202608&periods=7 — 用户留存（队列分析）
• GET /api/stats/user/cohort — 同期群分析
• GET /api/stats/user/active?period=dau|wau|mau — 活跃度（DAU/WAU/MAU）

3. 关键示例

3.1 主统计面板

GET /api/stats/dashboard
Header: token: <admin_token>

# 响应
{
  "code": 1,
  "data": {
    "today": { "pv": 12345, "uv": 2345, "ip": 1234, "new_users": 56 },
    "yesterday": { "pv": 11000, "uv": 2100 },
    "week_compare": "+12%",
    "today_active_users": 1500
  },
  "meta": {
    "aggregations": { "from": "2026-08-15", "to": "2026-08-15" }
  }
}

3.2 用户留存

GET /api/stats/user/retention?cohort=20260801&periods=7
# 响应
{
  "code": 1,
  "data": {
    "cohort_size": 150,        // 该天新注册数
    "retention": [
      { "day": 1, "count": 75, "rate": 0.50 },
      { "day": 3, "count": 60, "rate": 0.40 },
      { "day": 7, "count": 50, "rate": 0.33 }
    ]
  }
}

4. 设计要点

• 埋点统一入口：所有事件都走 /event，前端 SDK 一个方法搞定
• 匿名/已登录合并：通过 user_id 字段自动分段（埋点表可以关联到登录用户）
• 数据看板分维度：日活/周活/月活、转化漏斗、留存、同期群、A/B 测试 — 不同视角不冲突
• 热力图基于事件：前端 SDK 记录点击坐标，server 聚合得热力图（不是图片）
• 数据导出有审计：导出接口走 admin + 写审计日志（含导出人、时间、数据范围）

5. 关联文档

• 管理后台（站点设置）
• 用户中心（个人面板）
• 用户安全

站点统计 API（v2.3）

版本: v2.3 | 更新: 2026-08-15
接口路径: /api/webapi/ 和 /api/statistics/
维护: Xianyan 团队
跳转: 统计与分析（埋点） · 管理后台

职责：站点级统计（PV/UV/分类分布）+ 用户级统计（需登录）。

1. v2.3 变更

• 站点级笔记统计移除（隐私调整）
• /api/statistics/notes 改为用户级（需登录）
• 新增 /api/statistics/engagement（互动数据）
• 新增 /api/statistics/attachments（附件数据）
• 新增 /api/statistics/api_usage（API 调用）

2. 接口清单

2.1 站点级（公开）

• GET /api/webapi/pv — 今日 PV/UV
• GET /api/webapi/activeUsers — 实时活跃用户
• GET /api/webapi/topPois — Top 兴趣点
• GET /api/webapi/contentDistribution — 内容分类分布
• GET /api/webapi/siteOverview — 站点总览
• GET /api/webapi/health — 服务健康
• GET /api/webapi/siteRank — 站点排行

2.2 统计页面专用

• GET /api/statistics/summary — 概览卡片
• GET /api/statistics/categories — 分类统计
• GET /api/statistics/engagement — 互动量
• GET /api/statistics/attachments — 附件量
• GET /api/statistics/api_usage — API 调用量
• GET /api/statistics/notes — 我的笔记（用户级，需登录）
• GET /api/statistics/growth — 增长趋势
• GET /api/statistics/retention — 留存
• GET /api/statistics/rank — 排行

2.3 演示用 mock 数据

• 当统计服务异常时自动降级到 mock，保证页面不空白

3. 响应格式

{
  "code": 1,
  "data": {
    "today_pv": 12345,
    "today_uv": 2345,
    "trend_24h": [/* 每小时 PV */],
    "top_categories": [...],
    "update_time": "2026-08-15 14:00"
  }
}

4. 设计要点

• 公开 vs 用户级分层：站点级公开（PV/UV），用户级（我的笔记/我的活动）需登录
• 降级到 mock：服务异常时自动回退 mock 数据，保证 stats.html 页面不空白
• 缓存 5 分钟：减少数据库压力

5. 关联文档

• 管理后台
• 统计与分析（埋点后台）