bohui-vue 1.0.1

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

@@ -0,0 +1,527 @@
+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 };

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

@@ -0,0 +1,85 @@
+type Trigger = "blur" | "change";
+
+type FormRule = {
+    validator: (rule: unknown, value: unknown, callback: (error?: Error | string) => void) => void;
+    trigger?: Trigger | Trigger[];
+    required?: boolean;
+    message?: string;
+};
+
+function isIPv4(value: unknown): boolean {
+    if (typeof value !== "string") return false;
+    const parts = value.split(".");
+    if (parts.length !== 4) return false;
+    for (const p of parts) {
+        if (p.length === 0 || p.length > 3) return false;
+        if (!/^[0-9]+$/.test(p)) return false;
+        const n = Number(p);
+        if (!Number.isInteger(n)) return false;
+        if (n < 0 || n > 255) return false;
+    }
+    return true;
+}
+
+function ipRule(message?: string, trigger: Trigger = "blur"): FormRule {
+    return {
+        trigger,
+        validator: (_rule, value, callback) => {
+            if (value === undefined || value === null || value === "") {
+                callback(new Error(message || "请输入IP地址"));
+                return;
+            }
+            if (!isIPv4(value)) {
+                callback(new Error(message || "IP地址格式不正确"));
+                return;
+            }
+            callback();
+        },
+    };
+}
+
+type NumberRangeOptions = {
+    min?: number;
+    max?: number;
+    integer?: boolean;
+    allowEmpty?: boolean;
+    message?: string;
+    trigger?: Trigger;
+};
+
+function numberRangeRule(options?: NumberRangeOptions): FormRule {
+    const { min, max, integer, allowEmpty, message, trigger = "blur" } = options || {};
+    return {
+        trigger,
+        validator: (_rule, value, callback) => {
+            if (value === undefined || value === null || value === "") {
+                if (allowEmpty) {
+                    callback();
+                } else {
+                    callback(new Error(message || "请输入数字"));
+                }
+                return;
+            }
+            const num = typeof value === "number" ? value : Number(value);
+            if (!Number.isFinite(num)) {
+                callback(new Error(message || "请输入有效的数字"));
+                return;
+            }
+            if (integer && !Number.isInteger(num)) {
+                callback(new Error(message || "请输入整数"));
+                return;
+            }
+            if (typeof min === "number" && num < min) {
+                callback(new Error(message || `最小值为${min}`));
+                return;
+            }
+            if (typeof max === "number" && num > max) {
+                callback(new Error(message || `最大值为${max}`));
+                return;
+            }
+            callback();
+        },
+    };
+}
+
+export { ipRule, numberRangeRule, isIPv4 };