埋点统计的前世今生
前端项目中的埋点（Tracking）是指隐式收集用户行为数据并上传到服务端的过程。埋点方案经历了几个阶段：
| 阶段 | 方式 | 优缺点 |
|---|---|---|
| 早期 | 图片请求（1px GIF + GET 参数） | URL 长度有限，敏感数据不安全 |
| 主流 | Ajax POST 请求 | 数据量大，可加密传输 |
| 实时 | WebSocket | 实时性强，但实现复杂 |
uni-admin 内置的 uni-stat 统计模块采用 POST 请求方式，配合定时任务进行数据聚合。
uni-stat 2.0 架构
uni-stat 已经发展到 2.0 版本，是 uni-admin 模板项目内置的统计组件。它的核心特点：
- 全端统计：iOS、Android、Web、各平台小程序共用一套 SDK，一张报表查看全部数据
- 自由部署：数据存储在自己的 uniCloud 空间，不依赖第三方统计平台
- 深度集成：与 uni-app 和 uniCloud 深度绑定，自动采集页面访问、设备信息等基础数据
服务端模块构成
uniCloud/cloud-functions/common/
├── uni-config-center/
│ └── uni-stat/ # 配置文件
│ └── config.json # 定时任务、调试模式等配置
├── uni-stat/ # 核心统计模块
│ ├── index.js # 入口文件
│ └── stat/
│ ├── stat.js # 统计调度处理函数（核心）
│ └── data.js # 数据统计定时器
└── uni-stat-receiver/ # 数据接收器（前端上报入口）
text
核心模块解读
入口文件 index.js：初始化数据接收器和统计模块。
统计调度函数 stat.js：这是最核心的方法。它根据不同的统计类型调用对应的模块：
基础统计 → stat-result.js
活跃设备统计 → active-devices.js
活跃用户统计 → active-users.js
留存统计 → retention.js
...等等
text
数据统计定时器 data.js：包含三个关键方法：
cron()— 数据统计定时处理任务，按分钟/小时/日/月/实时周期跑批stat()— 统计调度处理函数，根据统计类型分派到具体模块clean()— 日志清理调度函数
数据处理流程
以 stat-result.js（基础数据结果统计）为例，核心流程：
1. 从 session-log 表中查询原始会话数据
2. 使用 MongoDB 聚合查询（group by + project）统计各维度数据
- 按平台（platform）分组
- 按渠道（channel）分组
- 按版本（version）分组
3. 将聚合结果批量插入（batch insert）到结果统计表
4. 返回统计结果
text
所有统计模块都遵循类似的模式：查询原始日志 → 聚合计算 → 写入统计结果表。
模块与统计功能的对应关系
| 源码文件 | 统计功能 |
|---|---|
stat-result.js | 基础数据（设备数、用户数、访问量、活跃度） |
active-devices.js | 活跃设备统计 |
active-users.js | 活跃用户统计 |
retention.js | 留存率统计 |
session-log.js | 会话日志 |
user-session-log.js | 用户会话日志 |
error-log.js | 错误日志 |
channel.js | 渠道统计 |
pay-result.js | 支付统计 |
定时任务配置
在 uni-config-center/uni-stat/config.json 中配置统计任务的执行周期：
{
"cron": {
"minute": "*/10 * * * *",
"hour": "0 * * * *",
"day": "0 0 * * *",
"month": "0 0 1 * *"
},
"debug": true
}
json
配置格式类似 Linux crontab，但简化为 4 位（分钟、小时、日、月）。将 debug 设为 true 可以在控制台看到详细的上传日志，方便调试。
前端采集 SDK
前端 SDK 在小程序的生命周期方法中自动采集数据：
App.onLaunch → 采集启动数据（平台、SDK版本、语言、经纬度等）
App.onShow → 采集页面切换事件
App.onHide → 采集应用进入后台事件
App.onError → 采集错误事件
text
采集到的数据按照约定的格式打包，通过 uni-stat-receiver 云对象以 POST 请求上传到云端。上传周期默认为 10 秒，并非每次操作都立即上报。
↑