jacy
89fd333702
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>
87 lines
2.7 KiB
Markdown
87 lines
2.7 KiB
Markdown
# 杜康好客 · 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
|
||
```
|