jackyu66gitandCursor
4889ff5916
保留远程用户侧 ECR-009–016 与本地 Ops 目录/RBAC/CMS/危机等能力；文档标注分叉期间 ECR 编号冲突。 Co-authored-by: Cursor <cursoragent@cursor.com>
157 lines
5.2 KiB
Markdown
157 lines
5.2 KiB
Markdown
# 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. 测试与部署
|