jackyu66gitandCursor
bd22d9dddd
落地 synastry/star/ask API 与 H5 页面，补齐 cece-frontend-re complete-design 证据文档，并加入 Android 模拟器截图抓取脚本。 Co-authored-by: Cursor <cursoragent@cursor.com>
149 lines
3.7 KiB
Markdown
149 lines
3.7 KiB
Markdown
# Feature Spec: 增长埋点（P1 最小集）
|
||
|
||
> Status: `Active` · Map: 横切增长 · Phase: `P1`（切片 A）
|
||
> 规范：[../feature-design.md](../feature-design.md) · 走查：[P1-PROCESS-REVIEW.md](P1-PROCESS-REVIEW.md)
|
||
|
||
---
|
||
|
||
## 1. 功能定义
|
||
|
||
| 字段 | 内容 |
|
||
|---|---|
|
||
| Name | 增长埋点最小集 |
|
||
| Purpose | 用统一 `track()` 采集主漏斗关键节点，支撑转化分析 |
|
||
| Business Goal | 能量化：建档探索 → 深度版/会员；不阻塞主路径 |
|
||
|
||
| In | Out |
|
||
|---|---|
|
||
| H5 `track` + GA4（可配 Measurement ID） | 服务端埋点中台 |
|
||
| 下文 **5 个核心事件** + 自动 `page_view` | 全量 Spec §11 一次接完 |
|
||
| DEV 可 debug 日志 | 采集生日/答题全文等 PII |
|
||
|
||
---
|
||
|
||
## 2. 用户价值
|
||
|
||
1. 用户无感（不改变主流程）。
|
||
2. 产品可看漏斗掉点。
|
||
3. 付费：N/A。
|
||
|
||
---
|
||
|
||
## 3. 用户角色
|
||
|
||
全部 Visitor/User 路径均可触发；不因埋点失败阻断功能。
|
||
|
||
---
|
||
|
||
## 4. 用户流程
|
||
|
||
```text
|
||
App 启动 → 若配置了 GA ID 则注入 gtag
|
||
↓
|
||
路由变化 → page_view
|
||
↓
|
||
主漏斗节点 → track(核心事件)
|
||
↓
|
||
gtag 不可用 / 未配置 → no-op（可选 console debug）
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 页面设计
|
||
|
||
无独立页面。触点：`/` · `/portrait` · `/relation` · 深度版 CTA · pay-mock 成功。
|
||
|
||
---
|
||
|
||
## 6. 页面状态规范
|
||
|
||
N/A（横切）。要求：埋点失败不影响 UI。
|
||
|
||
---
|
||
|
||
## 7. Business Rules
|
||
|
||
| ID | Rule |
|
||
|---|---|
|
||
| R1 | 统一经 `apps/user-h5/src/lib/analytics.ts` 的 `track`；页面禁止直接调 `window.gtag` |
|
||
| R2 | **P1 核心事件仅下表 5 个**（另加自动 `page_view`）；其它 Spec §11 事件名保留，后续迭代再挂 |
|
||
| R3 | 禁止把生日、问答正文、档案 ID 明文作为事件参数（可用 `report_type` 等枚举） |
|
||
| R4 | `VITE_GA_MEASUREMENT_ID` 为空时 track 为 no-op，应用仍可用 |
|
||
| R5 | 事件名稳定，snake_case，与下表一致 |
|
||
|
||
### P1 核心事件字典（冻结）
|
||
|
||
| Event | 触发 | 可选 params |
|
||
|---|---|---|
|
||
| `home_cta_portrait` | 首页点「开始」且生日校验通过，即将进画像 | — |
|
||
| `portrait_completed` | 画像基础结果首次展示成功 | `source`: query\|report_id |
|
||
| `deep_access_clicked` | 用户点击深度版 CTA（画像/关系/报告） | `surface`: portrait\|relation\|report |
|
||
| `purchase_completed` | mock 支付成功且刷新后权益生效 | `kind`: deep_access\|membership |
|
||
| `relation_completed` | 关系理解基础结果展示成功 | — |
|
||
|
||
基础设施：
|
||
|
||
| Event | 触发 | params |
|
||
|---|---|---|
|
||
| `page_view` | 路由 afterEach | `page_path`, `page_title` |
|
||
|
||
---
|
||
|
||
## 8. 数据模型影响
|
||
|
||
无 DB。配置：`VITE_GA_MEASUREMENT_ID`（H5）。
|
||
|
||
---
|
||
|
||
## 9. API 需求
|
||
|
||
无后端 API。
|
||
|
||
---
|
||
|
||
## 10. 权限设计
|
||
|
||
埋点不鉴权；不依赖登录态字段。
|
||
|
||
---
|
||
|
||
## 11. 埋点
|
||
|
||
见 §7 字典（本 Spec 即权威事件表）。
|
||
|
||
---
|
||
|
||
## 12. 测试验收标准
|
||
|
||
**Given** 未配置 GA ID
|
||
**When** 触发 `track('portrait_completed')`
|
||
**Then** 不抛错、不挡 UI
|
||
|
||
**Given** mock `window.gtag`
|
||
**When** `track('home_cta_portrait')`
|
||
**Then** gtag 被以 event 名调用
|
||
|
||
**Given** 用户完成画像基础结果
|
||
**When** 页面 Normal
|
||
**Then** 曾触发 `portrait_completed`（单测或集成对 track mock）
|
||
|
||
---
|
||
|
||
## 13. AI 开发前检查
|
||
|
||
- [x] Spec 齐全
|
||
- [x] 仅 5 核心 + page_view
|
||
- [x] 无 PII 参数
|
||
|
||
---
|
||
|
||
## 14. Implementation Notes
|
||
|
||
| 项 | 内容 |
|
||
|---|---|
|
||
| Packages | `src/lib/analytics.ts` · `main.ts` · Home/Portrait/Relation/Report/Membership |
|
||
| Config | `VITE_GA_MEASUREMENT_ID` · `VITE_ANALYTICS_DEBUG`（`apps/user-h5/.env.example`） |
|
||
| Legacy | 静态站曾用 `G-LVVXH3TL04`，可写入 `.env.local` |
|
||
| Tests | `analytics.spec.ts` |
|
||
| Process Review | 切片 A **已实现**（2026-08-02） |
|