@mtn-ui-z/monitor 0.0.1

package/dist/src/api.d.ts

@@ -0,0 +1,40 @@
+import { ApiData, MonitorOptions } from './types';
+
+/**
+ * API 监控类
+ * 负责拦截并上报 API 请求数据
+ */
+export declare class ApiMonitor {
+    /** 监控配置选项 */
+    private options;
+    /** 数据上报函数 */
+    private reportFn;
+    /** 原始 fetch 方法 */
+    private originalFetch;
+    /** 原始 XMLHttpRequest */
+    private originalXhr;
+    /** 是否已启动 */
+    private isStarted;
+    /**
+     * 构造函数
+     * @param options - 监控配置
+     * @param reportFn - 上报函数
+     */
+    constructor(options: MonitorOptions, reportFn: (data: ApiData) => void);
+    /**
+     * 启动 API 监控
+     */
+    start(): void;
+    /**
+     * 停止 API 监控
+     */
+    stop(): void;
+    /**
+     * 拦截 fetch 请求
+     */
+    private interceptFetch;
+    /**
+     * 拦截 XMLHttpRequest
+     */
+    private interceptXhr;
+}

package/dist/src/behavior.d.ts

@@ -0,0 +1,46 @@
+import { BehaviorData, MonitorOptions } from './types';
+
+/**
+ * 用户行为监控类
+ * 负责采集用户交互行为数据
+ */
+export declare class BehaviorMonitor {
+    /** 监控配置选项 */
+    private options;
+    /** 数据上报函数 */
+    private reportFn;
+    /** 是否已启动 */
+    private isStarted;
+    /** 点击事件处理器（用于 stop 时移除） */
+    private boundClickHandler;
+    /** 滚动事件处理器（用于 stop 时移除） */
+    private boundScrollHandler;
+    /** 可见性变化处理器（用于 stop 时移除） */
+    private boundVisibilityHandler;
+    /**
+     * 构造函数
+     * @param options - 监控配置
+     * @param reportFn - 上报函数
+     */
+    constructor(options: MonitorOptions, reportFn: (data: BehaviorData) => void);
+    /**
+     * 启动用户行为监控
+     */
+    start(): void;
+    /**
+     * 停止用户行为监控
+     */
+    stop(): void;
+    /**
+     * 监听点击事件
+     */
+    private observeClick;
+    /**
+     * 监听滚动事件
+     */
+    private observeScroll;
+    /**
+     * 监听页面可见性变化
+     */
+    private observeVisibility;
+}

package/dist/src/custom.d.ts

@@ -0,0 +1,29 @@
+import { CustomData, MonitorOptions } from './types';
+
+/**
+ * 自定义事件监控类
+ * 负责处理用户手动上报的自定义事件
+ */
+export declare class CustomMonitor {
+    /** 监控配置选项 */
+    private options;
+    /** 数据上报函数 */
+    private reportFn;
+    /**
+     * 构造函数
+     * @param options - 监控配置
+     * @param reportFn - 上报函数
+     */
+    constructor(options: MonitorOptions, reportFn: (data: CustomData) => void);
+    /**
+     * 上报自定义事件
+     * @param eventName - 事件名称
+     * @param eventData - 事件数据
+     */
+    report(eventName: string, eventData?: Record<string, unknown>): void;
+    /**
+     * 上报页面停留事件
+     * @param duration - 停留时长（毫秒）
+     */
+    reportStay(duration: number): void;
+}

package/dist/src/error.d.ts

@@ -0,0 +1,72 @@
+import { ErrorData, MonitorOptions } from './types';
+
+/**
+ * 错误监控类
+ * 负责捕获并上报各类前端错误
+ */
+export declare class ErrorMonitor {
+    /** 监控配置选项 */
+    private options;
+    /** 数据上报函数 */
+    private reportFn;
+    /** 绑定的事件处理器 - JS 错误 */
+    private boundErrorHandler;
+    /** 绑定的事件处理器 - Promise 未捕获异常 */
+    private boundPromiseHandler;
+    /** 绑定的事件处理器 - 资源加载错误 */
+    private boundResourceHandler;
+    /** Vue 错误处理器 */
+    private vueErrorHandler;
+    /**
+     * 构造函数
+     * @param options - 监控配置
+     * @param reportFn - 上报函数
+     */
+    constructor(options: MonitorOptions, reportFn: (data: ErrorData) => void);
+    /**
+     * 启动错误监控
+     * 添加全局事件监听器
+     */
+    start(): void;
+    /**
+     * 停止错误监控
+     * 移除所有事件监听器
+     */
+    stop(): void;
+    /**
+     * 创建 Vue 错误处理器
+     * 用于设置到 app.config.errorHandler
+     * @param customHandler - 用户自定义的处理函数（可选），会在监控上报后调用
+     * @returns Vue 错误处理函数
+     */
+    createVueErrorHandler(customHandler?: (err: Error, instance: unknown, info: string) => void): (err: Error, instance: unknown, info: string) => void;
+    /**
+     * 注册 Vue 错误处理器（兼容旧版）
+     * @param handler - 用户自定义的 Vue 错误处理函数
+     * @returns Vue 错误处理器函数
+     * @deprecated 请使用 createVueErrorHandler 代替
+     */
+    registerVueHandler(handler: (err: Error, instance: unknown, info: string) => void): (err: Error, instance: unknown, info: string) => void;
+    /**
+     * 处理 JS 运行时错误
+     * @param event - ErrorEvent 事件对象
+     */
+    private handleError;
+    /**
+     * 处理 Promise 未捕获异常
+     * @param event - PromiseRejectionEvent 事件对象
+     */
+    private handlePromiseReject;
+    /**
+     * 处理资源加载错误
+     * @param event - 事件对象
+     */
+    private handleResourceError;
+    /**
+     * 处理 Vue 组件错误
+     * @param err - Vue 错误对象
+     * @param instance - 触发错误的组件实例
+     * @param info - 错误信息字符串
+     */
+    private handleVueError;
+}

package/dist/src/index.d.ts

@@ -0,0 +1,122 @@
+import { App } from 'vue';
+import { MonitorInstance, MonitorOptions } from './types';
+
+/**
+ * 监控 SDK 主类
+ * 提供统一的初始化和 API 接口
+ */
+declare class Monitor implements MonitorInstance {
+    /** 监控配置选项 */
+    private options;
+    /** 错误监控模块 */
+    private errorMonitor?;
+    /** 性能监控模块 */
+    private performanceMonitor?;
+    /** PV 监控模块 */
+    private pvMonitor?;
+    /** API 监控模块 */
+    private apiMonitor?;
+    /** 用户行为监控模块 */
+    private behaviorMonitor?;
+    /** 自定义事件监控模块 */
+    private customMonitor?;
+    /** 长任务监控模块 */
+    private longTaskMonitor?;
+    /** 上报管理模块 */
+    private reportManager?;
+    /** 当前用户 ID */
+    private userId?;
+    /** 是否已初始化 */
+    private isInited;
+    /**
+     * 初始化监控 SDK
+     * @param options - 监控配置选项
+     */
+    init(options: MonitorOptions): void;
+    /**
+     * 手动上报错误
+     * @param error - Error 对象
+     * @param errorType - 错误类型
+     */
+    reportError(error: Error, errorType?: 'js' | 'resource' | 'promise' | 'vue'): void;
+    /**
+     * 手动上报性能数据
+     * @param metric - 性能指标类型
+     * @param value - 指标值（毫秒）
+     */
+    reportPerformance(metric: 'page' | 'resource' | 'fcp' | 'fp' | 'lcp' | 'fid' | 'cls' | 'tti' | 'ttfb' | 'dns' | 'tcp' | 'download', value: number): void;
+    /**
+     * 手动上报页面访问（PV）
+     */
+    reportPv(): void;
+    /**
+     * 手动上报自定义事件
+     * @param eventName - 事件名称
+     * @param eventData - 事件数据
+     */
+    reportCustomEvent(eventName: string, eventData?: Record<string, unknown>): void;
+    /**
+     * 设置用户 ID
+     * 用于关联用户行为
+     * @param userId - 用户唯一标识
+     */
+    setUserId(userId: string): void;
+    /**
+     * 销毁监控实例
+     * 停止所有监控，释放资源
+     */
+    destroy(): void;
+}
+export declare const monitor: Monitor;
+/**
+ * Vue 插件形式
+ * 可通过 app.use(MtnMonitor, options) 快速集成
+ */
+export declare const MtnMonitor: {
+    /**
+     * 安装 Vue 插件
+     * @param app - Vue 应用实例
+     * @param options - 监控配置选项
+     */
+    install(app: App, options: MonitorOptions): void;
+};
+declare module '@vue/runtime-core' {
+    interface ComponentCustomProperties {
+        $monitor: MonitorInstance;
+    }
+}
+declare module 'vue' {
+    interface App {
+        $monitor: MonitorInstance;
+    }
+}
+export type { 
+/** 监控配置选项 */
+MonitorOptions, 
+/** 监控实例接口 */
+MonitorInstance, 
+/** 错误数据类型 */
+ErrorData, 
+/** 性能数据类型 */
+PerformanceData, 
+/** PV 数据类型 */
+PvData, 
+/** API 数据类型 */
+ApiData, 
+/** 用户行为数据类型 */
+BehaviorData, 
+/** 自定义事件数据类型 */
+CustomData, 
+/** 长任务数据类型 */
+LongTaskData, 
+/** 监控数据联合类型 */
+MonitorData, } from './types';
+export { ErrorMonitor } from './error';
+export { PerformanceMonitor } from './performance';
+export { PvMonitor } from './pv';
+export { ApiMonitor } from './api';
+export { BehaviorMonitor } from './behavior';
+export { CustomMonitor } from './custom';
+export { LongTaskMonitor } from './longtask';
+export { ReportManager } from './report';
+export default monitor;

package/dist/src/longtask.d.ts

@@ -0,0 +1,42 @@
+import { LongTaskData, MonitorOptions } from './types';
+
+/**
+ * 长任务监控类
+ * 使用 PerformanceObserver 监控长任务和内存使用
+ */
+export declare class LongTaskMonitor {
+    /** 监控配置选项 */
+    private options;
+    /** 数据上报函数 */
+    private reportFn;
+    /** PerformanceObserver 实例 */
+    private observer;
+    /** 是否已启动 */
+    private isStarted;
+    /** 内存信息轮询定时器 */
+    private memoryInterval;
+    /**
+     * 构造函数
+     * @param options - 监控配置
+     * @param reportFn - 上报函数
+     */
+    constructor(options: MonitorOptions, reportFn: (data: LongTaskData) => void);
+    /**
+     * 启动长任务监控
+     */
+    start(): void;
+    /**
+     * 停止长任务监控
+     */
+    stop(): void;
+    /**
+     * 监控 Long Task
+     * Long Task 是指执行时间超过 50ms 的任务
+     */
+    private observeLongTask;
+    /**
+     * 监控内存使用情况
+     * 兼容新版 Performance.memory 和旧版 performance.msMemoryUsageInfo
+     */
+    private observeMemory;
+}

package/dist/src/performance.d.ts

@@ -0,0 +1,64 @@
+import { PerformanceData, MonitorOptions } from './types';
+
+/**
+ * 性能监控类
+ * 使用 Performance Observer API 采集关键性能指标
+ */
+export declare class PerformanceMonitor {
+    /** 监控配置选项 */
+    private options;
+    /** 数据上报函数 */
+    private reportFn;
+    /** PerformanceObserver 实例数组，用于停止时清理 */
+    private observers;
+    /** load 事件监听器引用 */
+    private loadHandler;
+    /** CLS 上报定时器引用 */
+    private clsTimeoutId;
+    /**
+     * 构造函数
+     * @param options - 监控配置
+     * @param reportFn - 上报函数
+     */
+    constructor(options: MonitorOptions, reportFn: (data: PerformanceData) => void);
+    /**
+     * 启动性能监控
+     * 采集各类性能指标
+     */
+    start(): void;
+    /**
+     * 停止性能监控
+     * 清理所有 observer 和定时器
+     */
+    stop(): void;
+    /**
+     * 上报页面基础性能指标
+     * 使用 performance.getEntriesByType('navigation') 获取页面加载各阶段耗时
+     */
+    private reportPagePerformance;
+    /**
+     * 监听资源加载性能
+     * 使用 PerformanceObserver 监听所有资源请求
+     */
+    private observeResources;
+    /**
+     * 监听 First Contentful Paint (FCP)
+     * 首次内容绘制时间
+     */
+    private observeFCP;
+    /**
+     * 监听 Largest Contentful Paint (LCP)
+     * 最大内容绘制时间，关键用户体验指标
+     */
+    private observeLCP;
+    /**
+     * 监听 Cumulative Layout Shift (CLS)
+     * 累计布局偏移，衡量页面稳定性
+     */
+    private observeCLS;
+    /**
+     * 监听 First Input Delay (FID)
+     * 首次输入延迟，衡量页面响应性
+     */
+    private observeFID;
+}

package/dist/src/pv.d.ts

@@ -0,0 +1,55 @@
+import { PvData, MonitorOptions } from './types';
+
+/**
+ * 页面访问监控类
+ * 负责采集和上报页面访问数据
+ */
+export declare class PvMonitor {
+    /** 监控配置选项 */
+    private options;
+    /** 数据上报函数 */
+    private reportFn;
+    /** 当前用户 ID */
+    private userId?;
+    /** 原始的 pushState 方法 */
+    private originalPushState;
+    /** 原始的 replaceState 方法 */
+    private originalReplaceState;
+    /** popstate 事件回调 */
+    private popstateHandler;
+    /** 是否已启动 */
+    private isStarted;
+    /**
+     * 构造函数
+     * @param options - 监控配置
+     * @param reportFn - 上报函数
+     */
+    constructor(options: MonitorOptions, reportFn: (data: PvData) => void);
+    /**
+     * 启动页面访问监控
+     * 首次访问立即上报，并监听路由变化
+     */
+    start(): void;
+    /**
+     * 停止页面访问监控
+     * 恢复原始方法，移除事件监听
+     */
+    stop(): void;
+    /**
+     * 手动触发一次 PV 上报
+     * 可用于路由切换后手动上报
+     */
+    report(): void;
+    /**
+     * 设置用户 ID
+     * @param userId - 用户唯一标识
+     */
+    setUserId(userId: string): void;
+    /**
+     * 监听路由变化
+     * 支持浏览器前进后退、pushState
+     * 注意：仅在 pushState 和 popstate 时上报，不在 replaceState 时上报。
+     * Vue Router 4 在一次 router.push() 中会先 replaceState 再 pushState，若 replaceState 也上报会导致同一次跳转产生两次 PV。
+     */
+    private observeRouter;
+}

package/dist/src/report.d.ts

@@ -0,0 +1,31 @@
+import { MonitorData, MonitorOptions } from './types';
+
+/**
+ * 上报管理类
+ * 处理数据上报的核心逻辑
+ */
+export declare class ReportManager {
+    /** 监控配置选项 */
+    private options;
+    /**
+     * 构造函数
+     * @param options - 监控配置
+     */
+    constructor(options: MonitorOptions);
+    /**
+     * 上报监控数据
+     * @param data - 监控数据
+     */
+    report(data: MonitorData): void;
+    /**
+     * 判断是否在采样范围内
+     * @returns 是否应该上报
+     */
+    private isSampled;
+    /**
+     * 默认上报实现
+     * 优先使用 sendBeacon，回退使用 fetch
+     * @param data - 监控数据
+     */
+    private defaultReport;
+}