dukang/杜康好客-v3-埋点规范.md

杜康好客 · V3 埋点规范

版本：2026-08-03
存储：C 端 → log_user_analytics；门店 → log_store_analytics；合伙人 → log_partner_analytics
契约：packages/shared-types/src/*-log.ts
查询：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 — C 端 13 个 category
• store-log.ts — 门店 8 个 category
• 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