bohui-vue 1.0.2 → 1.0.4

package/bin/create-vue-template.js

@@ -54,11 +54,6 @@ function parseFlags(args) {
       : flags.has("--unocss")
         ? true
         : null,
-    tracker: flags.has("--no-tracker")
-      ? false
-      : flags.has("--tracker")
-        ? true
-        : null,
     test:
       flags.has("--no-test") || flags.has("--no-tests")
         ? false
@@ -193,7 +188,7 @@ function removeScripts(obj, scriptsToRemove) {
 }
 
 function applyFeatureSelection(targetDir, features) {
-  const { echarts, unocss, tracker, test } = features;
+  const { echarts, unocss, test } = features;
 
   const packageJsonPath = path.join(targetDir, "package.json");
   const pkg = readJsonIfExists(packageJsonPath);
@@ -234,10 +229,6 @@ function applyFeatureSelection(targetDir, features) {
     }
   }
 
-  if (!tracker) {
-    rmIfExists(path.join(targetDir, "src", "utils", "tracker.ts"));
-  }
-
   if (!test) {
     rmIfExists(path.join(targetDir, "tests"));
     rmIfExists(
@@ -256,7 +247,7 @@ function applyFeatureSelection(targetDir, features) {
         /^\s*import\s+\{\s*defineConfig\s*\}\s+from\s+"vitest\/config";\s*\r?\n/m,
         'import { defineConfig } from "vite";\n',
       );
-      next = next.replace(/^\s*test:\s*\{[\s\S]*?\r?\n\s*\},\s*\r?\n/m, "");
+      next = next.replace(/^(\s*)test:\s*\{[\s\S]*?\r?\n\1\},\s*\r?\n/m, "");
       writeText(viteConfigPath, next);
     }
   }
@@ -362,37 +353,6 @@ function applyFeatureSelection(targetDir, features) {
       next = next.replace(/^\s*import\s+"uno\.css";\s*\r?\n/m, "");
     }
 
-    if (!tracker) {
-      next = next.replace(
-        /^\s*import\s+\{\s*createTrackerPlugin,\s*getTracker\s*\}\s+from\s+"@\/utils\/tracker";\s*\r?\n/m,
-        "",
-      );
-      next = next.replace(
-        /^\s*import\s+\{\s*abortAllRequests,\s*http,\s*formDataHttp\s*\}\s+from\s+"@\/api\/http";\s*\r?\n/m,
-        'import { abortAllRequests } from "@/api/http";\n',
-      );
-      next = next.replace(
-        /^\s*\.use\(createTrackerPlugin\(\{ appId: "vue3-template" \}\)\)\s*\r?\n/m,
-        "",
-      );
-      next = next.replace(
-        /\r?\n\s*\/\/ 监听用户信息变化，更新 tracker 用户 ID[\s\S]*?\r?\n\s*\{ immediate: true \}\r?\n\s*\);\r?\n/m,
-        "\n",
-      );
-      next = next.replace(
-        /^\s*getTracker\(\)\.bindRouter\(router\);\s*\/\/ 绑定路由\s*\r?\n/m,
-        "",
-      );
-      next = next.replace(
-        /^\s*getTracker\(\)\.bindRouterExposure\(router\);\s*\/\/ 绑定路由曝光事件\s*\r?\n/m,
-        "",
-      );
-      next = next.replace(
-        /^\s*getTracker\(\)\.attachAxios\(\[http,\s*formDataHttp\]\);\s*\/\/ 绑定 axios 实例\s*\r?\n/m,
-        "",
-      );
-    }
-
     writeText(mainPath, next);
   }
 }
@@ -453,12 +413,6 @@ async function main() {
       : nonInteractive
         ? true
         : await questionYesNo("是否需要 UnoCSS 原子化 CSS 能力", true);
-  const useTracker =
-    parsed.tracker != null
-      ? parsed.tracker
-      : nonInteractive
-        ? true
-        : await questionYesNo("是否需要数据埋点（Tracker）能力", true);
   const useTest =
     parsed.test != null
       ? parsed.test
@@ -523,7 +477,6 @@ async function main() {
   applyFeatureSelection(targetDir, {
     echarts: useECharts,
     unocss: useUnoCSS,
-    tracker: useTracker,
     test: useTest,
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "bohui-vue",
-    "version": "1.0.2",
+    "version": "1.0.4",
     "description": "Vue 项目模板创建工具，用于快速创建标准化的 Vue 项目",
     "main": "bin/create-vue-template.js",
     "bin": {

package/templates/vue-project/src/main.ts

@@ -46,7 +46,6 @@ import pinia from "./store";
 import { useUserStore } from "./store";
 
 import { abortAllRequests, http, formDataHttp } from "@/api/http";
-import { createTrackerPlugin, getTracker } from "@/utils/tracker";
 
 import "@unocss/reset/tailwind.css";
 import "uno.css";
@@ -85,7 +84,6 @@ app.use(ElButton)
     .use(ElCollapseItem)
     .use(pinia)
     .use(router)
-    .use(createTrackerPlugin({ appId: "vue3-template" }))
     .mount("#app");
 
 const userStore = useUserStore();
@@ -93,19 +91,6 @@ router.isReady().then(() => {
     userStore.setUserInfo();
 });
 
-// 监听用户信息变化，更新 tracker 用户 ID
-watch(
-    () => userStore.userInfo,
-    (u) => {
-        getTracker().setUserId(u?.id ?? null);
-    },
-    { immediate: true }
-);
-
-getTracker().bindRouter(router); // 绑定路由
-getTracker().bindRouterExposure(router); // 绑定路由曝光事件
-getTracker().attachAxios([http, formDataHttp]); // 绑定 axios 实例
-
 window.addEventListener("beforeunload", () => {
     abortAllRequests();
 });

package/templates/vue-project//345/267/245/347/250/213/345/214/226/346/250/241/346/235/277/344/273/213/347/273/215.md

@@ -79,7 +79,28 @@ src/
   main.ts                    # 应用入口（插件注册、全局样式引入）
 ```
 
-### 4.1 `components/`（全局复用组件）
+### 4.1 `views/`（页面组织规范）
+
+建议采用 “按业务域拆分 + 复杂度分级” 的混合策略，不强制所有页面都创建独立文件夹：
+
+#### 4.1.1 简单页面（扁平化）：
+
+如果页面功能单一、无私有组件、逻辑简单，直接在 views/ 下创建 .vue 文件。
+
+示例： src/views/Login.vue
+
+#### 4.1.2 复杂页面（目录化）：
+
+如果页面包含多个私有组件、独立的业务逻辑（hooks/composables）或拆分了子视图，则创建一个同名目录。
+
+- 每个页面一个目录：`src/views/<feature>/`
+- 页面入口：`<Feature>.vue`
+- 私有组件：`components/`
+- 私有逻辑：`composables/`
+
+示例：`src/views/teachingLog/`。
+
+### 4.2 `components/`（全局复用组件）
 
 用于沉淀“跨页面可复用”的组件，避免被单个页面目录绑定（例如 ECharts 封装、通用图表组件等）。
 
@@ -88,7 +109,7 @@ src/
 - 组件目录按领域拆分（如 `components/echarts/`）
 - 组件尽量“纯展示 + 明确输入输出”，避免直接依赖某个页面的 store/router
 
-#### 4.1.1 图表（ECharts）使用规范
+#### 4.2.1 图表（ECharts）使用规范
 
 模板内对 ECharts 做了“按需引入 + 统一渲染容器”的工程化封装，目标是：减少打包体积、统一初始化/销毁、降低业务图表组件的复杂度。
 
@@ -118,17 +139,6 @@ src/
 - `categories.length` 必须与 `series[].values.length` 一一对应
 - `values` 建议约束在 `0~100`（如百分比口径），超出范围需要在组件内部做钳制或规则说明
 
-### 4.2 `views/`（页面组织规范）
-
-建议按“业务域 / 页面模块”拆分：
-
-- 每个页面一个目录：`src/views/<feature>/`
-- 页面入口：`<Feature>.vue`
-- 页面内组件：`components/`
-- 页面内组合式逻辑：`composables/`
-
-示例：`src/views/teachingLog/`。
-
 ### 4.3 `api/`（请求层规范）
 
 - `src/api/http.ts`：提供两个实例
@@ -168,45 +178,7 @@ src/
 - 输入输出明确、易测试
 - 不直接操作 UI（比如弹窗提示）与路由（除非工具目标就是封装这些）
 
-#### 4.6.1 数据埋点（Tracker）使用规范
-
-模板提供了轻量级埋点/采集工具：`src/utils/tracker.ts`，并已在入口 `src/main.ts` 完成初始化接入，目标是统一采集页面访问、点击、接口请求结果等事件。
-
-- 上报地址
-    - 默认读取 `window.ConfigInfo.baseUrl` 拼接 `${baseUrl}/analytics/collect`
-    - 若未注入 `baseUrl`，回退到相对路径 `/analytics/collect`
-    - 可在初始化时通过 `createTrackerPlugin({ endpoint })` 覆盖
-- 接入方式（项目入口）
-    - Vue 插件：`createTrackerPlugin({ appId: "vue3-template" })` 注册全局能力
-    - 路由埋点：`getTracker().bindRouter(router)` 采集 `page_view`
-    - 页面曝光：`getTracker().bindRouterExposure(router)` 采集 `page_exposure`（仅统计页面可见时长）
-    - 接口埋点：`getTracker().attachAxios([http, formDataHttp])` 采集 `api_success/api_error`
-    - 用户关联：监听用户信息变化后 `getTracker().setUserId(u?.id ?? null)`，将后续事件与用户关联
-- 事件采集调用规范
-    - `$track(name, data)`：入队缓冲，适合高频/非关键事件（减少上报频率）
-    - `v-track` 指令：点击事件立即上报（避免跳转/关闭页面导致丢失）
-    - 手动即时上报：`getTracker().trackNow(name, data)`，适合关键动作
-
-组件内用法示例：
-
-```ts
-import { getTracker } from "@/utils/tracker";
-
-getTracker().track("search_submit", { keyword: "xxx" });
-getTracker().trackNow("pay_click", { orderId: "o_001" });
-```
-
-模板内置事件语义（建议统一沿用）：
-
-- `page_view`：路由切换后的页面访问
-- `page_exposure`：页面曝光时长结算（route_change / hidden / beforeunload）
-- `api_success` / `api_error`：接口成功/失败与耗时（自动从 axios 拦截器采集）
-- `click` / 自定义 click 事件：通过 `v-track` 或 `trackNow` 采集
-
-数据约定建议：
-
-- `name` 统一使用 `snake_case` 或 `kebab-case`，并在团队内固定一种风格
-- `data` 不写入敏感信息（token、密码、身份证号等），用户标识使用 `setUserId` 管理
+#### 4.6.1 数据埋点（tracker-vue-plugin）使用规范
 
 ### 4.7 `assets/`（样式与主题规范）
 

package/templates/vue-project/src/utils/tracker.ts

@@ -1,527 +0,0 @@
-import type { App, DirectiveBinding } from "vue";
-/**
- * 轻量级埋点/采集工具
- *
- * 目标：
- * - 统一收集页面访问、点击、接口请求结果等事件
- * - 支持队列缓冲与批量上报（降低上报频率、减少网络开销）
- * - 提供 Vue 插件（全局 $track）与指令（v-track）两种接入方式
- *
- * 说明：
- * - 本文件只负责“采集与发送”，不强依赖业务代码与路由/状态方案
- * - 上报请求统一通过项目内的 http 实例发送（便于复用拦截器、基础配置等）
- */
-
-/**
- * 使用简化的路由类型以避免依赖外部类型声明（如 vue-router 的类型）。
- * 这里只需要 fullPath/name 这两项字段即可完成 page_view 事件采集。
- */
-type SimpleRoute = { fullPath: string; name?: string | symbol | null };
-import type { AxiosInstance, InternalAxiosRequestConfig, AxiosResponse, AxiosError } from "axios";
-import { http } from "@/api/http";
-
-/**
- * 单条事件结构
- * - name: 事件名（如 page_view/click/api_success/api_error）
- * - ts: 事件产生时间戳（毫秒）
- * - data: 事件附加信息（会在 track/trackNow 内被 enrich 填充通用字段）
- */
-type TrackEvent = {
-    name: string;
-    ts: number;
-    data?: Record<string, unknown>;
-};
-
-/**
- * 初始化配置
- * - endpoint: 上报接口地址（默认 /analytics/collect 或 {baseUrl}/analytics/collect）
- * - appId: 应用标识（用于区分不同应用/站点）
- * - userId: 用户标识（可为空；登录后可 setUserId 更新）
- * - flushIntervalMs: 定时上报间隔（毫秒）
- * - maxBatchSize: 单次批量上报最大事件数（队列达到该值会立即 flush）
- */
-type TrackerInitOptions = {
-    endpoint?: string;
-    appId?: string;
-    userId?: string | null;
-    flushIntervalMs?: number;
-    maxBatchSize?: number;
-};
-
-/**
- * 页面曝光时长上报触发原因
- * - route_change: 路由切换离开当前页面
- * - hidden: 页面进入后台/不可见
- * - beforeunload: 页面关闭/刷新
- */
-type PageExposureReason = "route_change" | "hidden" | "beforeunload";
-
-class Tracker {
-    /**
-     * 上报地址
-     * - 默认尝试读取 window.ConfigInfo.baseUrl（适配通过全局配置注入后端地址的场景）
-     * - 若不存在 baseUrl，则回落到相对路径 /analytics/collect
-     */
-    private endpoint: string;
-    /** 应用标识 */
-    private appId: string;
-    /** 用户标识（可为空） */
-    private userId: string | null;
-    /**
-     * 会话标识
-     * - 在实例创建时生成，用于将同一次访问过程中的事件串联起来
-     * - 若需要跨刷新/重开浏览器持久化，可改造为写入 localStorage（当前未做）
-     */
-    private sessionId: string;
-    /** 事件队列（用于批量上报） */
-    private queue: TrackEvent[] = [];
-    /** 定时 flush 的 interval 句柄 */
-    private timer: number | null = null;
-    /** flush 的时间间隔（毫秒） */
-    private flushIntervalMs: number;
-    /** 单次 flush 的最大事件数 */
-    private maxBatchSize: number;
-    /**
-     * 页面曝光埋点是否已绑定
-     * - 防止 bindRouterExposure 被重复调用时重复注册监听器
-     */
-    private pageExposureBound = false;
-    /**
-     * 页面曝光统计状态
-     * - visibleStartTs: 当前可见时间片段起点；为 null 表示当前不可见/未计时
-     * - accumulatedMs: 当前页面累计曝光时长（只累计可见时间片段）
-     */
-    private pageExposureState: {
-        path: string;
-        name: string | null;
-        title: string | null;
-        visibleStartTs: number | null;
-        accumulatedMs: number;
-    } | null = null;
-
-    constructor() {
-        const base = (window as any).ConfigInfo?.baseUrl || "";
-        this.endpoint = base ? `${base}/analytics/collect` : "/analytics/collect";
-        this.appId = "app";
-        this.userId = null;
-        this.sessionId = this.createId();
-        this.flushIntervalMs = 5000;
-        this.maxBatchSize = 50;
-    }
-
-    /**
-     * 初始化 tracker
-     * - 可覆盖默认配置
-     * - 启动定时 flush，并在页面卸载/切后台时尽量把队列发出去
-     *
-     * 注意：
-     * - 这里对 flushIntervalMs/maxBatchSize 使用了“真值判断”，意味着传入 0 会被忽略
-     *   （一般不需要 0；若确需支持，可将判断改为 typeof === "number"）
-     */
-    init(opts?: TrackerInitOptions) {
-        if (opts?.endpoint) this.endpoint = opts.endpoint;
-        if (opts?.appId) this.appId = opts.appId;
-        if (typeof opts?.userId !== "undefined") this.userId = opts.userId;
-        if (opts?.flushIntervalMs) this.flushIntervalMs = opts.flushIntervalMs;
-        if (opts?.maxBatchSize) this.maxBatchSize = opts.maxBatchSize;
-        this.startTimer();
-    }
-
-    /**
-     * 入队采集（异步批量上报）
-     * - 适合高频事件（如 page_view、接口成功/失败等）
-     * - 到达 maxBatchSize 时会触发一次立即 flush
-     */
-    track(name: string, data?: Record<string, unknown>) {
-        const e: TrackEvent = { name, ts: Date.now(), data: this.enrich(data) };
-        this.queue.push(e);
-        if (this.queue.length >= this.maxBatchSize) this.flush();
-    }
-
-    /**
-     * 立即采集并上报（不入队）
-     * - 适合对“及时性”要求较高的事件（如点击/关键操作）
-     * - 失败时静默吞掉错误，避免影响业务流程
-     */
-    trackNow(name: string, data?: Record<string, unknown>) {
-        const e: TrackEvent = { name, ts: Date.now(), data: this.enrich(data) };
-        const payload = {
-            appId: this.appId,
-            userId: this.userId,
-            sessionId: this.sessionId,
-            ua: navigator.userAgent,
-            events: [e],
-        };
-        http.post<any>(this.endpoint, payload).catch(() => void 0);
-    }
-
-    /**
-     * 更新 userId
-     * - 可在登录/退出时调用
-     * - 后续事件会携带新的 userId
-     */
-    setUserId(userId: string | null) {
-        this.userId = userId;
-    }
-
-    /**
-     * 绑定路由（采集页面浏览）
-     * - 在每次路由切换后上报 page_view
-     * - 记录当前路径、来源路径、路由 name 与 document.title
-     */
-    bindRouter(router: any) {
-        router.afterEach((to: SimpleRoute, from: SimpleRoute) => {
-            this.track("page_view", {
-                path: to.fullPath,
-                from: from.fullPath,
-                name: to.name || null,
-                title: document.title || null,
-            });
-        });
-    }
-
-    /**
-     * 绑定路由页面曝光时长采集
-     *
-     * 统计口径：
-     * - 只统计页面处于 visible 的时间片段
-     * - hidden/beforeunload/route_change 时进行结算并上报 page_exposure
-     * - route_change 还会附带 toPath/toName，用于分析跳转去向
-     *
-     * 幂等性：
-     * - 内部通过 pageExposureBound 做去重，多次调用不会重复绑定监听
-     */
-    bindRouterExposure(router: any) {
-        if (this.pageExposureBound) return;
-        this.pageExposureBound = true;
-
-        const initRoute = (router.currentRoute?.value || null) as SimpleRoute | null;
-        const initPath =
-            initRoute?.fullPath ||
-            (typeof window.location.hash === "string" && window.location.hash
-                ? window.location.hash.replace(/^#/, "")
-                : window.location.pathname);
-
-        this.pageExposureState = {
-            path: initPath,
-            name: this.serializeRouteName(initRoute?.name),
-            title: document.title || null,
-            visibleStartTs: document.visibilityState === "hidden" ? null : Date.now(),
-            accumulatedMs: 0,
-        };
-
-        router.afterEach((to: SimpleRoute, _from: SimpleRoute) => {
-            this.endPageExposure("route_change", {
-                toPath: to.fullPath,
-                toName: this.serializeRouteName(to.name),
-            });
-            this.pageExposureState = {
-                path: to.fullPath,
-                name: this.serializeRouteName(to.name),
-                title: document.title || null,
-                visibleStartTs: document.visibilityState === "hidden" ? null : Date.now(),
-                accumulatedMs: 0,
-            };
-        });
-
-        document.addEventListener("visibilitychange", () => {
-            if (!this.pageExposureState) return;
-            if (document.visibilityState === "hidden") {
-                this.endPageExposure("hidden");
-                return;
-            }
-            if (this.pageExposureState.visibleStartTs === null) {
-                this.pageExposureState.visibleStartTs = Date.now();
-            }
-        });
-
-        window.addEventListener("beforeunload", () => {
-            this.endPageExposure("beforeunload");
-        });
-    }
-
-    /**
-     * 接入 axios 实例（采集接口成功/失败）
-     * - request 拦截器写入 __startTs 用于耗时计算
-     * - response 拦截器采集 api_success / api_error
-     *
-     * 注意：
-     * - 会跳过上报接口自身的请求，避免“上报产生上报”导致递归/噪音
-     * - 建议传入你项目中实际使用的 axios 实例数组（如 http、其他业务实例）
-     */
-    attachAxios(instances: AxiosInstance[]) {
-        instances.forEach((inst) => {
-            const instAny = inst as any;
-            if (instAny.__trackerAxiosBound) return;
-            instAny.__trackerAxiosBound = true;
-
-            inst.interceptors.request.use((cfg: InternalAxiosRequestConfig) => {
-                (cfg as any).__startTs = Date.now();
-                return cfg;
-            });
-
-            const onFulfilled = (res: AxiosResponse) => {
-                const s = (res.config as any)?.__startTs as number | undefined;
-                const d = typeof s === "number" ? Date.now() - s : null;
-                const url = res.config?.url || null;
-                const method = ((res.config?.method || "get") as string).toUpperCase();
-                if (!this.isAnalyticsUrl(url, res.config?.baseURL)) {
-                    this.track("api_success", {
-                        url,
-                        method,
-                        status: res.status,
-                        duration: d,
-                    });
-                }
-                return res;
-            };
-
-            const onRejected = (err: unknown) => {
-                const axiosErr = err as AxiosError;
-                const cfg = axiosErr.config;
-                const s = (cfg as any)?.__startTs as number | undefined;
-                const d = typeof s === "number" ? Date.now() - s : null;
-                if (!this.isAnalyticsUrl(cfg?.url || null, cfg?.baseURL)) {
-                    this.track("api_error", {
-                        url: cfg?.url || null,
-                        method: ((cfg?.method || "get") as string).toUpperCase(),
-                        status: axiosErr.response?.status || null,
-                        message: axiosErr.message,
-                        duration: d,
-                    });
-                }
-                return Promise.reject(err);
-            };
-
-            inst.interceptors.response.use(onFulfilled, onRejected);
-
-            const handlers = (inst.interceptors.response as any)?.handlers as
-                | Array<{ fulfilled?: unknown; rejected?: unknown }>
-                | undefined;
-            if (Array.isArray(handlers)) {
-                const idx = handlers.findIndex(
-                    (h) => h?.fulfilled === onFulfilled && h?.rejected === onRejected
-                );
-                if (idx > 0) {
-                    const [h] = handlers.splice(idx, 1);
-                    handlers.unshift(h);
-                }
-            }
-        });
-    }
-
-    /**
-     * 生成 v-track 指令
-     *
-     * 用法示例：
-     * - v-track="'buy_click'"                      // 直接传事件名
-     * - v-track="{ name: 'buy_click', data: {...}}" // 同时携带自定义 data
-     *
-     * 行为：
-     * - 仅监听 click 事件
-     * - 默认会携带当前元素 tagName/id，便于定位点击来源
-     * - 使用 trackNow 立即上报（避免用户跳转/关闭页面导致丢失）
-     */
-    directive() {
-        return {
-            mounted: (el: HTMLElement, binding: DirectiveBinding) => {
-                const handler = (_evt: Event) => {
-                    const v = binding.value;
-                    if (typeof v === "string") {
-                        this.trackNow(v, { tag: el.tagName, id: el.id || null });
-                    } else if (v && typeof v === "object") {
-                        const name = (v as any).name || "click";
-                        const data = (v as any).data || {};
-                        this.trackNow(name, { ...data, tag: el.tagName, id: el.id || null });
-                    } else {
-                        this.trackNow("click", { tag: el.tagName, id: el.id || null });
-                    }
-                };
-                (el as any).__trackHandler = handler;
-                el.addEventListener("click", handler);
-            },
-            beforeUnmount: (el: HTMLElement) => {
-                const h = (el as any).__trackHandler as ((e: Event) => void) | undefined;
-                if (h) el.removeEventListener("click", h);
-                (el as any).__trackHandler = null;
-            },
-        } as any;
-    }
-
-    /**
-     * 批量上报队列事件
-     * - 每次最多发送 maxBatchSize 条
-     * - 失败时静默吞掉错误，避免影响业务
-     *
-     * 注意：
-     * - 当前实现使用 http.post 上报，默认是异步请求；在 beforeunload 中可能来不及完成
-     *   若对离开页面的可靠性要求更高，可考虑改用 navigator.sendBeacon（需后端支持）
-     */
-    flush() {
-        if (!this.queue.length) return;
-        const batch = this.queue.splice(0, this.maxBatchSize);
-        const payload = {
-            appId: this.appId,
-            userId: this.userId,
-            sessionId: this.sessionId,
-            ua: navigator.userAgent,
-            events: batch,
-        };
-        http.post<any>(this.endpoint, payload).catch(() => void 0);
-    }
-
-    /**
-     * 注入通用字段（每个事件都会带上）
-     * - url: 当前完整地址（含 hash/query）
-     * - viewport: 当前视口大小
-     * - ts: enrich 时刻的时间戳（与 TrackEvent.ts 可能接近但不完全相同）
-     *
-     * 说明：
-     * - TrackEvent.ts 表示“事件产生时间”，enrich.ts 表示“入队/上报时刻”
-     * - 若你不希望重复时间字段，可移除 enrich.ts 或移除 TrackEvent.ts（二选一）
-     */
-    private enrich(data?: Record<string, unknown>) {
-        const base = {
-            url: window.location.href,
-            viewport: { w: window.innerWidth, h: window.innerHeight },
-            ts: Date.now(),
-        };
-        return data ? { ...base, ...data } : base;
-    }
-
-    /**
-     * 判断某个请求 URL 是否为埋点上报接口
-     * - 用于避免对上报接口本身再产生 api_success/api_error 事件
-     * - 兼容相对/绝对 URL 的情况（URL 构造失败时回退到字符串包含判断）
-     */
-    private isAnalyticsUrl(u?: string | null, baseURL?: string) {
-        if (!u) return false;
-
-        const normalizePathname = (p: string) => p.replace(/\/+$/, "");
-        const toUrl = (raw: string, base: string) => {
-            try {
-                return new URL(raw, base);
-            } catch {
-                return null;
-            }
-        };
-
-        try {
-            const b =
-                toUrl(u, baseURL || window.location.origin) || toUrl(u, window.location.origin);
-            const a =
-                toUrl(this.endpoint, baseURL || window.location.origin) ||
-                toUrl(this.endpoint, window.location.origin);
-
-            if (a && b) {
-                const ap = normalizePathname(a.pathname);
-                const bp = normalizePathname(b.pathname);
-                if (ap === bp) return true;
-                if (ap.endsWith("/analytics/collect") && bp.endsWith("/analytics/collect"))
-                    return true;
-            }
-
-            return false;
-        } catch {
-            return u.includes("/analytics/collect");
-        }
-    }
-
-    /**
-     * 启动定时器并注册兜底 flush
-     * - interval: 定期 flush
-     * - beforeunload: 关闭/刷新前尽量 flush（可靠性依赖浏览器与网络环境）
-     * - visibilitychange: 切到后台时 flush（移动端/低内存场景更容易被挂起）
-     */
-    private startTimer() {
-        if (this.timer) window.clearInterval(this.timer);
-        this.timer = window.setInterval(() => this.flush(), this.flushIntervalMs);
-        window.addEventListener("beforeunload", () => this.flush());
-        document.addEventListener("visibilitychange", () => {
-            if (document.visibilityState === "hidden") this.flush();
-        });
-    }
-
-    /**
-     * 将路由 name 统一序列化为 string
-     * - 兼容 vue-router 允许 name 为 symbol 的情况
-     */
-    private serializeRouteName(name?: string | symbol | null) {
-        if (!name) return null;
-        if (typeof name === "string") return name;
-        return name.toString();
-    }
-
-    /**
-     * 结算并上报当前页面曝光时长
-     * - 在 route_change/hidden/beforeunload 时调用
-     * - 只在 durationMs > 0 时上报，避免产生无意义噪音数据
-     */
-    private endPageExposure(reason: PageExposureReason, extra?: Record<string, unknown>) {
-        if (!this.pageExposureState) return;
-
-        const now = Date.now();
-        if (this.pageExposureState.visibleStartTs !== null) {
-            this.pageExposureState.accumulatedMs += now - this.pageExposureState.visibleStartTs;
-            this.pageExposureState.visibleStartTs = null;
-        }
-
-        const durationMs = this.pageExposureState.accumulatedMs;
-        if (durationMs > 0) {
-            this.track("page_exposure", {
-                path: this.pageExposureState.path,
-                name: this.pageExposureState.name,
-                title: this.pageExposureState.title,
-                durationMs,
-                reason,
-                ...(extra || {}),
-            });
-        }
-
-        this.pageExposureState.accumulatedMs = 0;
-    }
-
-    /**
-     * 生成会话/事件相关的唯一标识
-     * - 优先使用 crypto.randomUUID（更可靠）
-     * - 回退到时间戳 + 随机串（兼容老环境）
-     */
-    private createId() {
-        if (typeof crypto !== "undefined" && "randomUUID" in crypto) return crypto.randomUUID();
-        return `${Date.now()}_${Math.random().toString(36).slice(2)}`;
-    }
-}
-
-/**
- * 单例 tracker
- * - 便于在全局复用（插件、指令、手动调用 getTracker 都指向同一个实例）
- */
-const tracker = new Tracker();
-
-/**
- * 创建 Vue 插件
- * - install 时注入全局方法 $track（走队列，适合非关键事件）
- * - 注册 v-track 指令（走 trackNow，适合点击等关键事件）
- */
-export function createTrackerPlugin(opts?: TrackerInitOptions) {
-    tracker.init(opts);
-    return {
-        install(app: App) {
-            (app.config.globalProperties as any).$track = (
-                name: string,
-                data?: Record<string, unknown>
-            ) => tracker.track(name, data);
-            app.directive("track", tracker.directive());
-        },
-    };
-}
-
-/**
- * 获取 tracker 单例
- * - 可用于在任意位置手动调用（如 getTracker().bindRouter(router)）
- */
-export function getTracker() {
-    return tracker;
-}
-
-export type { TrackerInitOptions };