统计与分析

01MVP 的默认选择

01MVP 默认使用 Cloudflare Workers Analytics Engine，不加载 Google Analytics、百度统计或 Umami 的浏览器脚本。

浏览器把经过筛选的匿名事件发送到本站 /api/event。Cloudflare Route 只拦截这个路径，由 Worker 校验、限流并写入 Analytics Engine；其他页面和 API 仍可继续由 Zeabur 或其他源站处理。

浏览器匿名事件
  → 本站 /api/event
  → Cloudflare Worker
  → Analytics Engine 数据集

这样选择主要有三个原因：

国内用户不需要连接 Google 域名，统计请求和网站使用同一个域名。
页面不加载第三方统计脚本，减少外部依赖和额外下载。
事件字段由应用自己定义，可以只保留运营需要的数据。

第一方统计解决的是浏览器可达性、字段控制和自定义事件问题，不代表数据存储在中国大陆。对数据地域有硬性要求时，应改用满足地域要求的存储和计算服务。

默认覆盖的数据

模板已经统一处理：

页面访问、匿名周访客和会话
来源域名、UTM、国家/地区和界面语言
首页、学习页、价格页、付费墙和微信入口点击
文档阅读过半、接近完成和付费墙曝光
查看价格、开始结账、创建订单、结账失败和浏览器确认购买

支付成交、收入和退款仍以订单数据库与支付回调为准。浏览器事件用于观察漏斗，不作为财务口径。

隐私边界

默认实现不写入：

登录账号、姓名、邮箱、手机号
Cookie、Authorization header、请求 body
完整查询参数、原始 IP、完整 User-Agent
订单号、支付交易号、错误原文

访客 ID 是随机值，并在每个上海时区自然周轮换。它可以估算本周 UV，但不能跨周建立用户画像。

Cloudflare 配置

Cloudflare 部署配置在：

products/01mvp/apps/web/wrangler.jsonc

核心配置包括：

{
  "routes": [
    {
      "pattern": "example.com/api/event*",
      "zone_name": "example.com"
    }
  ],
  "ratelimits": [
    {
      "name": "EVENT_RATE_LIMITER",
      "namespace_id": "32001",
      "simple": {
        "limit": 120,
        "period": 60
      }
    }
  ],
  "analytics_engine_datasets": [
    {
      "binding": "MVP01_ANALYTICS",
      "dataset": "mvp01_events"
    }
  ]
}

把示例域名、binding 和 dataset 改成你自己的命名。Cloudflare 会在第一次写入时创建数据集。

发送自定义事件

页面和组件继续使用统一的 useAnalytics：

"use client";

import { useAnalytics } from "@/shared/analytics/analytics-provider";

export function UpgradeButton() {
  const { trackEvent } = useAnalytics();

  return (
    <button
      onClick={() =>
        trackEvent("pricing_cta_click", {
          category: "pricing",
          label: "upgrade",
          section: "account",
        })
      }
    >
      升级
    </button>
  );
}

允许的事件名和字段位于：

products/01mvp/apps/web/src/shared/analytics/analytics-contract.ts

新增事件时先扩展这里的白名单和固定字段，不要把任意对象、错误原文或用户资料直接传给统计接口。

每周查看数据

查询 Analytics Engine 需要一个只有 Account Analytics: Read 权限的 Cloudflare API Token：

CF_ACCOUNT_ID=你的账号ID \
CF_API_TOKEN=只读Token \
vpr @01mvp/product#analytics:weekly

默认输出上一个完整自然周的 Markdown 报告，包括：

PV、UV、会话、事件量和环比
价格页到创建订单的漏斗
热门页面、文档表现和主要点击
来源、UTM、国家/地区和语言
预设异常提示

也可以临时查询最近几天：

vpr @01mvp/product#analytics:weekly -- --days 14

原始数据可在 Cloudflare Dashboard 的 Workers & Pages → Analytics Engine → mvp01_events 中查询。

Analytics Engine 目前只保留三个月数据，并可能在高流量时采样。需要长期趋势时，定期把周报或每日汇总写入 D1、R2 或自己的数据仓库。

可选第三方工具

第一方统计是默认方案，不限制你增加其他工具：

Google Analytics

需要广告生态、GA4 报表或海外渠道归因时手动接入。

百度统计

已经使用百度推广和百度站长生态时手动接入。

Umami

需要现成的自托管可视化界面时手动接入。

新增第三方 provider 时，应集中修改 analytics-provider.tsx，同时检查 CSP、隐私说明和事件是否会重复上报。不要在各个页面分别插入脚本。