压缩文档

2026-08-06 01:09:19 +08:00
parent 4f363fa9e7
commit 53a79d1255
14 changed files with 469 additions and 7237 deletions
@@ -1,86 +1,38 @@
 # 杜康好客 · 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`
+> 存储：C→`log_user_analytics` · 门店→`log_store_analytics` · 合伙人→`log_partner_analytics`  
+> 契约：`packages/shared-types/src/*-log.ts` · HQ：`/logs/users|stores|partners`

 ## 原则

-1. 端侧 **page_view / 点击** 走客户端 `track()`；业务结果（支付成功、核销确认）走后端 `AnalyticsService.track*Safe`
-2. 所有客户端事件携带 `sessionId`（localStorage `dukang_session_id`），支持匿名漏斗
-3. `extraJson` 不含密码/令牌；手机号脱敏
-4. eventName 必须先登记在 shared-types taxonomy，再 emit
+1. 端侧 page_view/点击 → `track()`；支付/核销结果 → 后端 `AnalyticsService.track*Safe`
+2. 携带 `sessionId`（`dukang_session_id`）
+3. `extraJson` 无密码/令牌；手机号脱敏
+4. eventName 先登记 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` 埋点） |
+| C | `POST /analytics/events` | OptionalJwt |
+| 门店 | `POST /analytics/store-events` | Jwt+STORE |
+| 合伙人 | `POST /analytics/partner-events` | Jwt+PARTNER |
+| 推广 | `POST /promo/touch` | OptionalJwt（双写 touch） |

-## 完整 eventName 清单
+## eventName

-见 shared-types：
+完整清单 → `user-log.ts` / `store-log.ts` / `partner-log.ts`

- [`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 要点

-## extraJson 字段约定
+| 端 | 常用字段 |
+|----|----------|
+| C | sessionId, cityCode, productId, storeId, orderId, amount, pagePath, failReason |
+| 门店 | redeemChannel, amount, durationMs, failReason |
+| 合伙人 | storeId, orderId, billId, cityCode |

-### 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
-```
+- **C**：session→home→detail→confirm→submit→pay→redeem
+- **门店**：home→scan→preview→confirm
+- **合伙人**：home→store_create→audit / orders→ship / bills→confirm