feat(analytics): persona logging upgrade and Sentry system config

Add client-logging SDK, expanded event taxonomy, API observability, admin domain events UI, and move SENTRY_DSN to HQ system settings with @sentry/node bootstrap after config preload. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-03 22:30:02 +08:00
parent ab10431001
commit 89fd333702
91 changed files with 1805 additions and 136 deletions
@@ -0,0 +1,86 @@
+# 杜康好客 · V3 埋点规范
+
+> **版本**：2026-08-03  
+> **存储**：C 端 → `log_user_analytics`；门店 → `log_store_analytics`；合伙人 → `log_partner_analytics`  
+> **契约**：[`packages/shared-types/src/*-log.ts`](../packages/shared-types/src/)  
+> **查询**：admin-web `/logs/users` · `/logs/stores` · `/logs/partners`
+
+## 原则
+
+1. 端侧 **page_view / 点击** 走客户端 `track()`；业务结果（支付成功、核销确认）走后端 `AnalyticsService.track*Safe`
+2. 所有客户端事件携带 `sessionId`（localStorage `dukang_session_id`），支持匿名漏斗
+3. `extraJson` 不含密码/令牌；手机号脱敏
+4. eventName 必须先登记在 shared-types taxonomy，再 emit
+
+## API
+
+| 端 | 路由 | 鉴权 |
+|----|------|------|
+| C 端 | `POST /api/v1/analytics/events` | OptionalJwt |
+| 门店 | `POST /api/v1/analytics/store-events` | Jwt + STORE |
+| 合伙人 | `POST /api/v1/analytics/partner-events` | Jwt + PARTNER |
+| 推广 | `POST /api/v1/promo/touch` | OptionalJwt（双写 `promo_touch` 埋点） |
+
+## 完整 eventName 清单
+
+见 shared-types：
+
+- [`user-log.ts`](../packages/shared-types/src/user-log.ts) — C 端 13 个 category
+- [`store-log.ts`](../packages/shared-types/src/store-log.ts) — 门店 8 个 category
+- [`partner-log.ts`](../packages/shared-types/src/partner-log.ts) — 合伙人 9 个 category
+
+## extraJson 字段约定
+
+### C 端（UserAnalyticsExtra）
+
+| 字段 | 说明 |
+|------|------|
+| sessionId | 会话 ID，漏斗串联 |
+| cityCode | 开城/地域 |
+| productId / skuId | 商品偏好 |
+| storeId | 门店偏好 |
+| orderId | 订单归因 |
+| amount / quantity | 客单价 |
+| sourceType / sourceRefId | 获客渠道 |
+| failReason | 失败原因 |
+| pagePath | 页面路径 |
+
+### 门店（StoreAnalyticsExtra）
+
+| 字段 | 说明 |
+|------|------|
+| redeemChannel | scan / phone / pending |
+| amount | 核销金额 |
+| durationMs | 耗时 |
+| failReason | 失败原因 |
+
+### 合伙人（PartnerAnalyticsExtra）
+
+| 字段 | 说明 |
+|------|------|
+| storeId / orderId / billId | 业务关联 |
+| cityCode | 城市维度 |
+
+## 转化漏斗（C 端）
+
+```
+session_start → home_view → product_detail_view → order_confirm_view
+  → order_submit → pay_page_view → pay_success
+  → benefit_redeem_start → redeem_code_view → benefit_redeem_success
+```
+
+## 核销漏斗（门店）
+
+```
+store_home_view → store_redeem_scan_start → store_redeem_preview
+  → store_redeem_confirm | store_redeem_confirm_fail
+```
+
+## 合伙人经营漏斗
+
+```
+partner_home_view → partner_store_create_view → partner_store_create
+  → partner_store_audit_approved
+partner_order_list_view → partner_order_ship
+partner_bills_view → partner_bill_detail_view → partner_bill_confirm
+```