# Feature Spec: 运营行为分析（Ops-B）

> Status: `Active` · Map: `§7 运营后台` · Phase: `Ops-B`  
> ESS：`docs/ECR/ECR-007-ops-analytics.md`（**Closed** · L2）· BD-2026-007 Approved  
> 关联：[ops-admin.md](ops-admin.md) · [analytics.md](analytics.md) · [cece-frontend-re/complete-design/40-ops-commerce.md](cece-frontend-re/complete-design/40-ops-commerce.md)

---

## ESS 门禁

按本仓 `docs/PROJECT_RULES.md` + ESS `CHANGE_MANAGEMENT.md`：

1. Change Level = **L2** → ECR Approved + Feature Spec Active + BACKEND_DESIGN Approved — **已满足（2026-08-07）**  
2. 实现顺序以 `docs/ENGINEERING_SPEC/ECR-007-ops-analytics.md` 为准  
3. 完成后：TEST_REPORT · CODE_REVIEW · `ess-validate --phase review` · DoD Review Report  

（与 ECR/BACKEND_DESIGN 冲突时以已 Approved 的 ESS 工件为准。）

---

## 1. 目标

按**传统 App 运营**模式：

1. **采集**：页浏览、点击、停留时长、会话退出页等  
2. **落库**：自有管道（可与 GA4 双写）  
3. **展示**：管理端「数据」看板（DAU、页面、退出页、漏斗）  
4. **分期**：先 Ops-B 分析，再内容 / 商业 / 权限全量模块  

---

## 2. 分期总览

| 分期 | 主题 | 交付 |
|---|---|---|
| Ops-A | 已完成 | 登录 · 用户 · 订单 · 会员授予 · 审计 · 概览图 |
| **Ops-B** | **行为分析** | 自有埋点 + 管理端「数据」 |
| Ops-C | 内容运营 | 首页宫格/工具配置 · 测评上下架 |
| Ops-D | 商业加深 | 订单筛选 · 套餐价配置 · 退款只读 |
| Ops-E | 系统 | RBAC · 封禁 · 推送/站内信占位 |

UGC / 达人 / 真支付网关：**更远期**，不在本 Spec 承诺范围。

---

## 3. Ops-B 功能定义

| 字段 | 内容 |
|---|---|
| Name | App 行为分析（采集 + 运营看板） |
| Purpose | 用自有数据回答：谁来了、看了哪、停多久、从哪走、点了什么、漏斗掉哪 |
| Business Goal | 替代「只能看 GA / 改库」；支撑日常运营决策 |

| In | Out |
|---|---|
| session / page_view / page_leave(dwell) / ui_click / session_end(exit_page) | 热力图坐标级精确点击 |
| 漏斗事件写入同一管道 | 实时毫秒大屏 |
| Admin「数据」页聚合 | 用户轨迹录像 |

---

## 4. 采集字典（客户端）

扩展 `apps/user-h5/src/lib/analytics.ts`：通道 A = GA4（可选）；通道 B = 自有 `POST /api/v1/analytics/events`。

| Event | 触发 | 关键 props |
|---|---|---|
| `session_start` | 冷启动或可见性恢复（节流） | `session_id`, `cold`, `app_ver` |
| `page_view` | `router.afterEach` | `page_path`, `page_title`, `referrer_path` |
| `page_leave` | 路由离开 / `visibilitychange=hidden` / `pagehide` | `page_path`, **`dwell_ms`** |
| `ui_click` | `data-track` 或白名单委托 | `page_path`, `element_id` |
| `session_end` | 超时 / 关页（`sendBeacon`） | `session_id`, `duration_ms`, **`exit_page`** |
| 既有漏斗 | 保持 | `home_cta_portrait` 等 |

规则：

- 批量上报（5–10s）+ 退出冲刷  
- `session_id`：`sessionStorage`；30min 无互动新开  
- **禁止**生日、问答正文、手机号、完整档案 ID 明文  

---

## 5. 数据模型

```text
analytics_sessions
  id, device_key, user_id?, started_at, ended_at, exit_page, duration_ms

analytics_events
  id, session_id, user_id?, name, page_path, props jsonb, client_ts, received_at

analytics_daily_page（可选汇总）
  day, page_path, pv, uv, dwell_sum_ms, exit_count
```

---

## 6. API

| Method | Path | 意图 |
|---|---|---|
| POST | `/api/v1/analytics/events` | 批量 ingest（DeviceAuth，限流） |
| GET | `/api/v1/admin/analytics/overview` | DAU / 会话 / 均时长 |
| GET | `/api/v1/admin/analytics/pages` | 页 PV/UV/avg_dwell/exit |
| GET | `/api/v1/admin/analytics/exits` | 退出页 TOP |
| GET | `/api/v1/admin/analytics/clicks` | 点击 TOP |
| GET | `/api/v1/admin/analytics/funnel` | 漏斗计数 |

查询均带 `from` / `to`（日）。

---

## 7. 管理端「数据」页

侧栏：概览 · **数据** · 用户 · 订单 · 审计  

- 时间筛选：今日 / 7 日 / 30 日  
- 卡片：DAU、新增、会话数、人均会话时长  
- 图：日活趋势；页面均停留 TOP  
- 表：页面明细、退出页 TOP、点击 TOP  
- 漏斗：画像完成 → 深度 CTA → 支付成功  

视觉：愈心谷色系；品牌仅 logo，无「运营后台」字样。

---

## 8. Ops-C～E 边界（后置）

| 分期 | In |
|---|---|
| Ops-C | 首页宫格/工具 CRUD；scales 上下架 |
| Ops-D | 订单多维筛选；membership 展示价；退款状态只读 |
| Ops-E | 用户封禁；admin 角色；推送任务占位 |

---

## 9. Ops-B 验收

**Given** H5 打开并切换两页后离开  
**When** ingest 成功  
**Then** 存在 `page_view`×2、`page_leave`（含 dwell_ms）、`session_end.exit_page`  

**Given** Admin 登录「数据」近 7 日  
**When** GET overview/pages/exits  
**Then** 返回非空聚合且与事件量级一致  

---

## 10. 实施顺序

1. 本 Spec 置 Active + 改 feature-map §7 / ops-admin 分期  
2. Migration + ingest API  
3. Admin 聚合 API  
4. H5 SDK（会话/停留/点击/beacon）  
5. admin-h5「数据」页  
6. 测试与部署