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>

packages/shared-types/src/promo.ts

@@ -85,6 +85,50 @@ export function promoConversion(scan: number, orders: number): string {
   return `${Math.round((orders / scan) * 1000) / 10}%`;
 }
 
+export type PromoMetricEventType = 'SCAN' | 'ATTRIBUTION' | 'REGISTER' | 'ORDER';
+
+export const PROMO_METRIC_EVENT_LABELS: Record<PromoMetricEventType, string> = {
+  SCAN: '扫码进入',
+  ATTRIBUTION: '归因用户',
+  REGISTER: '扫码注册',
+  ORDER: '订单',
+};
+
+export type PromoMetricEventItem = {
+  id: string;
+  eventType: PromoMetricEventType;
+  userId: string | null;
+  orderId: string | null;
+  sessionId: string | null;
+  clientIp: string | null;
+  ipProvince: string | null;
+  ipCity: string | null;
+  createdAt: string;
+};
+
+export type PromoMetricTimelineBucket = {
+  key: string;
+  scan: number;
+  attribution: number;
+  register: number;
+  order: number;
+};
+
+export type PromoMetricTimelinePeak = {
+  scan: { key: string; count: number } | null;
+  attribution: { key: string; count: number } | null;
+  register: { key: string; count: number } | null;
+  order: { key: string; count: number } | null;
+};
+
+export type PromoMetricTimelineDto = {
+  granularity: 'day' | 'hour';
+  dateFrom: string;
+  dateTo: string;
+  buckets: PromoMetricTimelineBucket[];
+  peak: PromoMetricTimelinePeak;
+};
+
 export function buildPromoLandingUrl(baseUrl: string, code: string, qrcodeId: string): string {
   const base = baseUrl.replace(/\/$/, '');
   return `${base}/?promo=${encodeURIComponent(code)}&pid=${encodeURIComponent(qrcodeId)}`;