digital-psychology/.ai/product/feature-spec/ops-analytics.md

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

Status: Active · Map: §7 运营后台 · Phase: Ops-B
ESS：docs/ECR/ECR-007-ops-analytics.md（Approved · L2）· BD-2026-007 Approved
关联：ops-admin.md · analytics.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. 数据模型

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. 测试与部署