# 杜康好客 · 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
```