# 数据埋点（Analytics / 数据统计）

| 项目 | 内容 |
|---|---|
| 版本 | v0.1 |
| 结论先行 | **Cloudflare 默认不会自动统计访问量**，需要自建埋点；可选配免费的 Cloudflare Web Analytics 补充 PV/UV。本仓库已规划自建事件管道。 |

---

## 1. 结论：Cloudflare 会帮我统计访问数吗？

**不会自动统计。**

- Cloudflare **Workers / Pages 本身不记录访问量**。它们只提供请求日志（免费的 workers.dev 日志量有限，且不面向「产品访问统计」），没有内置的 PV/UV 看板。
- 若想要「访问数」，Cloudflare 提供了独立且免费的 **Cloudflare Web Analytics**（需在控制台开通，并通过一个 JS beacon 脚本注入页面，或在 Pages 中开启）。它提供：页面浏览量、唯一访客、停留时长、Core Web Vitals，按域名聚合，隐私友好（无 cookie）。适合做**流量基线**。
- 但 Web Analytics 只到「域名级 PV/UV」，**没有业务事件能力**（谁开局了、谁领了 Token、局内出牌次数等），也无法和 D1 里的用户/对局数据关联。

**结论**：访问数要自己埋；PV/UV 用 Web Analytics 免费补一份基线；业务事件用自建管道（本仓库设计）。

---

## 2. 埋点设计目标

1. **可回答业务问题**：DAU/WAU、对局量、经济流通、段位分布、Agent 模式占比。
2. **轻量**：事件批量上报、节流、去重；不拖慢对局（埋点异步、失败静默）。
3. **隐私**：匿名 UID；不采集消息内容/聊天记录；不做跨站追踪。
4. **可控**：全链路在自家 Cloudflare 内（Workers + D1），无第三方依赖；未来可平滑接外部 BI。

---

## 3. 方案选型

| 方案 | 能力 | 成本 | 结论 |
|---|---|---|---|
| **自建：Workers ingest → D1 事件表 + 定时聚合 → Admin 报表** | 事件级、可与业务数据关联 | 低（CF 免费额度内） | ✅ 主方案 |
| Cloudflare Web Analytics（beacon） | 域级 PV/UV / Web Vitals | 免费 | ✅ 补充方案（流量基线） |
| 外部工具（PostHog/Plausible/Analytics Engine） | 现成看板/漏斗 | 中等 / 依赖第三方 | ⏳ 备选（数据量起来后评估） |

> 注：Cloudflare Analytics Engine 面向日志型聚合，正在被 Workers Logs / Pipelines 取代，故不选为主方案，保持 D1 + 聚合足够。

---

## 4. 上报链路

```
客户端（插件） ──批量 POST /api/analytics──▶ Workers ingest
                                              │ 校验 ingest key、白名单事件、限流
                                              ▼
                                        D1 analytics_events
                                              │ 定时（cron 每小时）聚合
                                              ▼
                                      D1 analytics_daily（预聚合）
                                              │
                                              ▼
                                    Admin 报表端点 /api/admin/stats
```

- **节流**：客户端 10 条/批 或 5s 攒批；心跳级事件（对局内高频）本地先汇总再上报。
- **去重**：事件带客户端 `event_id`（uid + 时间戳 + 随机），D1 以 (event_id) 去重。
- **失败静默**：上报失败不打断用户，本地最多重试 1 次。

---

## 5. 事件字典（初版）

> 字段：`{ v, event, uid?, ts, props, event_id }`，`props` 为 JSON。

| 事件 | 触发时机 | 关键 props |
|---|---|---|
| `app_open` | 插件面板首次打开（每会话一次） | `source: lobby\|waiting_tip` |
| `daily_claim` | 签到成功/失败 | `amount, success, reason` |
| `lobby_view` | 进入大厅 | `balance, rank_id` |
| `queue_join` / `queue_leave` | 进入/退出匹配队列 | `table_id` |
| `match_start` | 对局开始 | `table_id, room_id, seats:3, base_stake` |
| `match_finish` | 对局结算 | `room_id, duration_ms, multiplier, winner_role, deltas[]` |
| `player_action` | 出牌/过/叫地主（可选，抽样上报 10%） | `action, cards_len` |
| `rank_up` | 段位上升 | `from_rank, to_rank` |
| `avatar_upload` | 上传自定义头像 | `success, bytes_before, bytes_after, format_after: webp, reason?` |
| `rescue_claim` | 领救济金 | `amount` |
| `disconnect` / `reconnect` | 断线/重连 | `room_id, duration_ms` |
| `error_frontend` | 前端异常 | `scope, message, stack_hash` |
| `error_backend` | 后端异常（由服务端直接记录） | `route, code` |
| `agent_turn`（Phase 2） | Agent 出牌 | `agent_source: self\|remote, duration_ms, fallback: bool` |
| `friend_room`（Phase 2） | 好友房开/加 | `mode` |

---

## 6. 关键指标（KPI / 报表）

### 6.1 流量
- PV / UV（日、周）——Web Analytics + 自建 `app_open` 双口径核对。
- 等待提示 → 打开牌局转化率（`waiting_tip → app_open`）。

### 6.2 对局
- 对局数（日/周）、人均局数、平均对局时长、桌别分布。
- 开局成功率（进队列 → 实际开局比例）、平均匹配等待时长。

### 6.3 经济
- 日发行（签到+救济）vs 日回收（rake）——**通胀监控**。
- Token 流通总量、人均余额、破产率。
- 段位分布（各段位人数占比）、升段率。

### 6.4 质量
- 断线率、重连成功率、后端错误率（5xx）、前端错误率。

### 6.5 Agent（Phase 2）
- Agent 模式对局占比、Agent 平均决策耗时、超时兜底率。

### 6.6 统计口径定义（统一）
- **DAU**：当天 UTC+8 内至少发生 1 次 `app_open` 或业务事件的去重 UID 数。
- **对局数**：`match_finish` 事件数（同一房间去重）。
- **PV**：`app_open` + 页面切换（大厅/牌桌/流水/设置）之和。
- 所有时间统一 **UTC+8** 展示；存储用毫秒时间戳 + 时区字段。

---

## 7. 存储与聚合（D1）

- 明细表 `analytics_events`（见架构设计 §3.3）：写入即得，当日可查明细。
- 预聚合表 `analytics_daily`：
```sql
CREATE TABLE analytics_daily (
  day      TEXT NOT NULL,      -- 'YYYY-MM-DD' (UTC+8)
  metric   TEXT NOT NULL,      -- dau | matches | avg_duration_ms | issued | raked | ...
  value    INTEGER NOT NULL,
  PRIMARY KEY (day, metric)
);
```
- Workers **cron**（每小时）聚合昨日/当日数据；明细保留 90 天，聚合永久保留（可配置）。

---

## 8. 报表与访问

- `/api/admin/stats?days=7&metric=dau`（Admin key 鉴权，只读）。
- 简单 HTML 看板（同 Worker 托管，Admin key 访问）显示：
  - 日活/周活趋势图、对局量、经济通胀曲线、段位分布、错误率。
- 粒度：日报（日/周/月切换）。

---

## 9. 隐私与合规

- 匿名 UID，不关联真实身份；昵称由用户自填（可随时改）。
- 不采集：消息内容、对话记录、文件内容、IP 原始地址（可只存国家/地区城市码，若需）。
- 埋点数据不共享第三方；仅用于产品改进。
- Web Analytics 为隐私友好型（无 cookie），默认开启可接受，设置页提供「关闭统计」开关（尊重用户）。

---

## 10. 开放问题

1. 是否需要在本地开发环境（localhost）也上报？→ 建议默认关，开发期用日志代替。
2. 是否需要漏斗分析（大厅→匹配→开局→第二局）？→ 若需要，事件已足够，加一个聚合即可。
3. 对局内高频事件（出牌）全量 or 抽样？→ 建议抽样 10%，防 D1 写入成本。