feat: 3.5版本规划

miniprogram/utils/downloadLogs.ts

@@ -4,6 +4,7 @@ export interface DownloadLogRecord {
     _id: string;
     userId: string;
     worksheetId: string;
+    exportId?: string;
     createdAt: string;
     worksheet?: {
         _id: string;
@@ -22,13 +23,16 @@ export interface DownloadLogRecord {
 /**
  * 记录下载日志
  */
-export async function addDownloadLog(worksheetId: string): Promise<boolean> {
+export async function addDownloadLog(
+    worksheetId: string,
+    exportId?: string,
+): Promise<boolean> {
     if (!worksheetId) return false;
     try {
         await getUser();
         const res = await wx.cloud.callFunction({
             name: 'userDownloadLogs',
-            data: { action: 'add', worksheetId },
+            data: { action: 'add', worksheetId, exportId },
         });
         const result = (res?.result as any) || {};
         return result.code === 0;

miniprogram/utils/downloadPrint.ts

@@ -6,6 +6,7 @@
 import { checkAndSaveImage } from './saveImage';
 import tracker from './tracker';
 import { addDownloadLog } from './downloadLogs';
+import { generateUUID } from './uuid';
 import {
     getUnlockMethod,
     isDownloadLimitEnabled,
@@ -131,23 +132,32 @@ function doDownload(
         errorToast?: string;
         trackerName?: string;
         trackerMode?: string;
+        trackerPage?: string;
         worksheetId?: string;
     },
 ): Promise<boolean> {
-    if (options.trackerName) {
-        if (options.trackerMode) {
-            tracker.reportDownload(options.trackerName, options.trackerMode);
-        } else {
-            tracker.reportDownload(options.trackerName);
-        }
-    }
+    const exportId = generateUUID();
+    const trackerPage = options.trackerPage || options.trackerName || '';
+    const trackerParams = {
+        export_id: exportId,
+        ...(options.worksheetId && { worksheet_id: options.worksheetId }),
+        ...(options.trackerName && { worksheet_title: options.trackerName }),
+        ...(options.trackerMode && { mode: options.trackerMode }),
+    };
 
-    return checkAndSaveImage(canvas).then((saved) => {
+    // 用户点击保存不等于保存成功，二者必须分开统计。
+    tracker.reportExportClick(trackerPage, trackerParams);
+
+    return checkAndSaveImage(canvas).then(async (saved) => {
         if (saved) {
+            // 只在 wx.saveImageToPhotosAlbum 的 success 回调后进入此分支。
             recordDownloadSuccess();
+            tracker.reportExportResult(trackerPage, true, trackerParams);
             if (options.worksheetId) {
-                addDownloadLog(options.worksheetId);
+                await addDownloadLog(options.worksheetId, exportId);
             }
+        } else {
+            tracker.reportExportResult(trackerPage, false, trackerParams);
         }
         return saved;
     });
@@ -163,6 +173,7 @@ export async function downloadPrint(
         errorToast?: string;
         trackerName?: string;
         trackerMode?: string;
+        trackerPage?: string;
         worksheetId?: string;
     } = {},
 ): Promise<boolean> {

miniprogram/utils/favorites.ts

@@ -1,4 +1,10 @@
 import { getUser } from './auth';
+import tracker from './tracker';
+
+function getCurrentPageRoute(): string {
+    const pages = getCurrentPages();
+    return pages[pages.length - 1]?.route || '';
+}
 
 export interface FavoriteRecord {
     _id: string;
@@ -31,7 +37,9 @@ export async function addFavorite(worksheetId: string): Promise<boolean> {
             data: { action: 'add', worksheetId },
         });
         const result = (res?.result as any) || {};
-        return result.code === 0;
+        const success = result.code === 0;
+        if (success) tracker.reportFavorite(getCurrentPageRoute(), worksheetId, true);
+        return success;
     } catch (e) {
         console.error('addFavorite failed', e);
         return false;
@@ -49,7 +57,11 @@ export async function removeFavorite(worksheetId: string): Promise<boolean> {
             data: { action: 'remove', worksheetId },
         });
         const result = (res?.result as any) || {};
-        return result.code === 0;
+        const success = result.code === 0;
+        if (success) {
+            tracker.reportFavorite(getCurrentPageRoute(), worksheetId, false);
+        }
+        return success;
     } catch (e) {
         console.error('removeFavorite failed', e);
         return false;
@@ -133,4 +145,3 @@ export async function batchCheckFavorited(
         return {};
     }
 }
-

miniprogram/utils/tracker.ts

@@ -115,18 +115,96 @@ class Tracker {
         };
     }
 
+    /**
+     * 统一业务埋点入口。pageName 使用页面 route，内容使用稳定的 worksheet_id。
+     */
+    report(
+        eventName: string,
+        pageName: string,
+        extraParams?: Record<string, any>,
+    ): void {
+        try {
+            this.sendEvent(
+                eventName,
+                this.getCommonEventParams(eventName, pageName, extraParams),
+            );
+        } catch (error) {
+            console.error(`上报 ${eventName} 事件失败:`, error);
+        }
+    }
+
+    reportPageView(pageName: string): void {
+        this.report('page_view', pageName);
+    }
+
+    reportWorksheetClick(
+        pageName: string,
+        extraParams: Record<string, any>,
+    ): void {
+        this.report('worksheet_click', pageName, extraParams);
+    }
+
+    reportPreviewView(
+        pageName: string,
+        extraParams: Record<string, any>,
+    ): void {
+        this.report('preview_view', pageName, extraParams);
+    }
+
+    reportGenerateStart(
+        pageName: string,
+        extraParams: Record<string, any>,
+    ): void {
+        this.report('generate_start', pageName, extraParams);
+    }
+
+    reportGenerateResult(
+        pageName: string,
+        success: boolean,
+        extraParams: Record<string, any>,
+    ): void {
+        this.report(
+            success ? 'generate_success' : 'generate_fail',
+            pageName,
+            extraParams,
+        );
+    }
+
+    reportExportClick(
+        pageName: string,
+        extraParams: Record<string, any>,
+    ): void {
+        this.report('export_click', pageName, extraParams);
+    }
+
+    reportExportResult(
+        pageName: string,
+        success: boolean,
+        extraParams: Record<string, any>,
+    ): void {
+        this.report(
+            success ? 'export_success' : 'export_fail',
+            pageName,
+            extraParams,
+        );
+    }
+
+    reportFavorite(
+        pageName: string,
+        worksheetId: string,
+        favorited: boolean,
+    ): void {
+        this.report(favorited ? 'favorite_add' : 'favorite_remove', pageName, {
+            worksheet_id: worksheetId,
+        });
+    }
+
     /**
      * 上报分享点击事件
      * @param pageName 页面名称
      */
-    reportShare(pageName: string): void {
-        try {
-            const params = this.getCommonEventParams('share_click', pageName);
-
-            this.sendEvent('share_click', params);
-        } catch (error) {
-            console.error('上报分享事件失败:', error);
-        }
+    reportShare(pageName: string, extraParams?: Record<string, any>): void {
+        this.report('share_click', pageName, extraParams);
     }
 
     /**
@@ -135,15 +213,8 @@ class Tracker {
      * @param mode 模式（可选）
      */
     reportDownload(pageName: string, mode?: string): void {
-        try {
-            const params = this.getCommonEventParams('download', pageName, {
-                ...(mode && { mode }),
-            });
-
-            this.sendEvent('download', params);
-        } catch (error) {
-            console.error('上报下载事件失败:', error);
-        }
+        // 兼容旧调用；新代码请使用 reportExportClick / reportExportResult。
+        this.reportExportClick(pageName, { ...(mode && { mode }) });
     }
 
     /**