# 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） |