feat(promo): promo metric event logs and HQ timeline charts (v3.4.13)

Add log_promo_event for scan/attribution/register/order with IP; admin metrics APIs and ECharts on promo detail page.

Co-authored-by: Cursor <cursoragent@cursor.com>

杜康好客-v3.4.13-体验优化开发文档.md

@@ -7,16 +7,16 @@
 
 | 模块 | 内容 |
 |------|------|
-| admin-web | 推广码 attributionCount；核销记录用户信息；技术支持工单优先级；**大图上传前压缩** |
+| admin-web | 推广码 attributionCount + **指标事件日志/ECharts 趋势**；核销记录用户信息；技术支持工单优先级；**大图上传前压缩** |
 | mini-user | 门店电话脱敏+拨打埋点；门头/套餐展示；商品去分享+首图 preview；提货确认弹框；版本更新提示；**物流增强（签收照/拨号/时间线/ETA）**；**头像超 10MB 压缩** |
 | h5-partner / h5-shop / h5-user | 登录 phone/code 前端校验；**OSS 图片超 10MB 自动 canvas 压缩后上传** |
-| 后端 | 工单 priority；client-config minClientVersion；合伙人微信暂停禁登；**Courier 适配器（100108/100301/路由回调）** |
+| 后端 | 工单 priority；client-config minClientVersion；合伙人微信暂停禁登；**Courier 适配器**；**log_promo_event 推广码指标日志** |
 
 ## 2. ST 映射
 
 | ST | 标题 | 状态 |
 |----|------|------|
-| ST1785925037781309 | 总部端-推广码数据跟踪优化 | ✅ attributionCount 统计卡 |
+| ST1785925037781309 | 总部端-推广码数据跟踪优化 | ✅ attributionCount + **事件日志 + ECharts 趋势** |
 | ST1785924286682833 | 用户端-门店电话加密+拨打埋点 | ✅ maskPhone + store_phone_call |
 | ST1785921693982470 | 技术支持-工单优先级 | ✅ priority 枚举 + HQ UI |
 | ST1785921585900725 | 门店端扫一扫授权异常 | ✅ 已有（v3.4.12 前） |
@@ -48,6 +48,23 @@
 | POST | `/callbacks/courier/xfx/track` | 小飞侠路由变化回调（适配器入口） |
 | POST | `/callbacks/courier/logistics/track` | 跨城物流回调占位（记录日志，后续接入） |
 | POST | `/callbacks/delivery/track` | 兼容旧路径，等同 `xfx` |
+| GET | `/admin/promo-codes/:id/metrics/timeline` | 推广码四指标时间序列（按日/按时 + peak） |
+| GET | `/admin/promo-codes/:id/metrics/events` | 推广码指标事件分页日志（时间/ID/IP/地点） |
+
+### 3.1 推广码指标日志（ST1785925037781309）
+
+**表** `log_promo_event`
+
+| event_type | 统计卡 | 写入时机 | ID |
+|------------|--------|----------|-----|
+| `SCAN` | 扫码进入数 | `POST /promo/touch` 且 `countScan !== false` | userId / sessionId |
+| `ATTRIBUTION` | 归因用户数 | 首次写入 `user_promo_attribution` | userId |
+| `REGISTER` | 扫码注册用户数 | `applyPromoSourceToUser` 成功 | userId |
+| `ORDER` | 订单数 | 带推广码下单 `orderCount++` | orderId + userId |
+
+每条日志含 `created_at`、可选 ID、`client_ip`、`ip_province`/`ip_city`。仅统计**上线后**新事件；累计 Statistic 卡逻辑不变。
+
+**HQ UI**：推广码详情页 → 数据趋势 Card（DatePicker + 按日/按时 + ECharts 四曲线 + 事件 Table）
 
 ### 4. mini-user 物流（ST1785939375449985）
 
@@ -109,6 +126,7 @@ POST https://api-test.dukanghaoke.com/api/v1/callbacks/courier/xfx/track
 ## 5. 数据表
 
 - `common_support_ticket.priority` ENUM，默认 `NORMAL`
+- `log_promo_event`：推广码指标事件（`promo_code_id`, `event_type`, `user_id`, `order_id`, `session_id`, `client_ip`, 地点, `created_at`）
 
 ## 6. HQ 开发计划
 
@@ -116,7 +134,8 @@ POST https://api-test.dukanghaoke.com/api/v1/callbacks/courier/xfx/track
 
 ## 7. 验收 ACC
 
-- [ ] 推广码详情展示 attributionCount
+- [ ] 推广码详情展示 attributionCount；**四指标事件日志 + ECharts 按日/按时趋势 + 高峰标注**
+- [ ] 推广码 SCAN/ATTRIBUTION/REGISTER/ORDER 事件含 time + IP；幂等（重复 touch 不计 SCAN）
 - [ ] 核销记录含 userNo/nickname/phone
 - [ ] 技术支持可创建/筛选/编辑优先级
 - [ ] 合伙人/门店登录空字段前端提示；暂停合伙人微信登录被拒