digital-psychology/docs/ECR/ECR-007-ops-analytics.md

ECR-007

Title: 运营行为分析 Ops-B（自有埋点采集 · 管理端数据看板）
Status: Approved
Date: 2026-08-07
Approved: 2026-08-07（Human）
Change Level: L2（新能力；栈与分层不变）

Change

1. Active Feature Spec：.ai/product/feature-spec/ops-analytics.md（Ops-B）
2. 新增表 analytics_sessions / analytics_events（可选日汇总表）
3. User API：POST /api/v1/analytics/events（DeviceAuth，批量 ingest）
4. Admin API：GET /api/v1/admin/analytics/*（overview / pages / exits / clicks / funnel）
5. user-h5：扩展 analytics.ts — 会话、页停留、点击、退出页；可与 GA4 双写
6. admin-h5：侧栏「数据」看板（传统 App 运营看数）

Motivation

当前埋点仅可选 GA4 + 漏斗事件，管理端无法看停留、退出页、点击排行；运维只能改库或外挂。需按传统 App 运营模式自有采集并在后台展示。

Scope

Allowed

• 上列 Spec / 表 / API / H5 SDK / admin「数据」页
• 修订 ops-admin.md / feature-map.md §7 写入 Ops-B
• OpenAPI 增补 analytics 路径

Forbidden（Non-goals）

• Ops-C 内容 CMS · Ops-D 优惠券/退款工单 · Ops-E RBAC/封禁/推送（另开 ECR）
• UGC / 达人 / 真支付网关
• 热力图坐标、会话录像、实时毫秒大屏
• 新基础设施（Kafka/ClickHouse 等）— 首期 Postgres；量级不够不升级 L3
• 采集生日、问答正文、手机号等 PII

Risk

Risk	Mitigation
事件量表膨胀	批量 ingest + 日汇总表；索引按日；后续再议 OLAP（新 ECR/ADR）
客户端丢数	sendBeacon 退出冲刷；失败静默不挡 UX
与 GA 双写不一致	Spec 声明自有管道为运营真相源；GA 可选
Admin 鉴权绕过	聚合 API 仅挂 AdminAuth

Acceptance Criteria

• Spec ops-analytics.md §验收用例通过
• Integration：H5 形态上报 → DB → admin analytics GET 非空且量级一致
• go test 相关包绿；npm run build:h5 · build:admin 绿
• OpenAPI / TRACEABILITY / STATE / TEST_REPORT / CODE_REVIEW
• python scripts/ess-validate.py --phase review --ecr ECR-007（Reviewer 门禁）
• Docs + CHANGELOG

Rollback

• 去掉 analytics 路由注册；H5 关闭自有上报开关
• down migration 删 analytics 表（开发/可接受环境）

Risk Review

• Path: N/A（非交易策略变更）

Linked

• Feature Spec: .ai/product/feature-spec/ops-analytics.md
• PRODUCT_SPEC: docs/PRODUCT_SPEC/ECR-007-ops-analytics.md
• ENGINEERING_SPEC: docs/ENGINEERING_SPEC/ECR-007-ops-analytics.md
• BACKEND_DESIGN: docs/BACKEND_DESIGN/ECR-007-ops-analytics.md（BD-2026-007）
• HANDOFF / TASK / STATE：见同号前缀
• EXPERIMENT: N/A
• TRACEABILITY row: updated Yes（Approved）
• 后续分期：Ops-C/D/E 各开独立 ECR（见 PRODUCT_SPEC 附录）