整理开发文档

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

@@ -0,0 +1,38 @@
+# 杜康好客 · V3 埋点规范
+
+> 存储：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`（`dukang_session_id`）
+3. `extraJson` 无密码/令牌；手机号脱敏
+4. eventName 先登记 taxonomy 再 emit
+
+## API
+
+| 端 | 路由 | 鉴权 |
+|----|------|------|
+| C | `POST /analytics/events` | OptionalJwt |
+| 门店 | `POST /analytics/store-events` | Jwt+STORE |
+| 合伙人 | `POST /analytics/partner-events` | Jwt+PARTNER |
+| 推广 | `POST /promo/touch` | OptionalJwt（双写 touch） |
+
+## eventName
+
+完整清单 → `user-log.ts` / `store-log.ts` / `partner-log.ts`
+
+## extraJson 要点
+
+| 端 | 常用字段 |
+|----|----------|
+| C | sessionId, cityCode, productId, storeId, orderId, amount, pagePath, failReason |
+| 门店 | redeemChannel, amount, durationMs, failReason |
+| 合伙人 | storeId, orderId, billId, cityCode |
+
+## 漏斗（摘要）
+
+- **C**：session→home→detail→confirm→submit→pay→redeem
+- **门店**：home→scan→preview→confirm
+- **合伙人**：home→store_create→audit / orders→ship / bills→confirm