feat: 创建 TypeScript 类型定义
This commit is contained in:
zdl
349
src/types/metrics.ts
Normal file
349
src/types/metrics.ts
Normal file
@@ -0,0 +1,349 @@
|
||||
/**
|
||||
* 性能指标相关的 TypeScript 类型定义
|
||||
* @module types/metrics
|
||||
*/
|
||||
|
||||
// ============================================================
|
||||
// Web Vitals 指标
|
||||
// ============================================================
|
||||
|
||||
/**
|
||||
* Web Vitals 评级
|
||||
*/
|
||||
export type MetricRating = 'good' | 'needs-improvement' | 'poor';
|
||||
|
||||
/**
|
||||
* 单个 Web Vitals 指标
|
||||
*/
|
||||
export interface WebVitalMetric {
|
||||
/** 指标名称 (如 'LCP', 'FCP') */
|
||||
name: string;
|
||||
/** 指标值（毫秒或分数） */
|
||||
value: number;
|
||||
/** 评级 (good/needs-improvement/poor) */
|
||||
rating: MetricRating;
|
||||
/** 与上周对比的差值 */
|
||||
delta?: number;
|
||||
/** 测量时间戳 */
|
||||
timestamp: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* 完整的 Web Vitals 指标集合
|
||||
*/
|
||||
export interface WebVitalsMetrics {
|
||||
/** Largest Contentful Paint - 最大内容绘制时间 */
|
||||
LCP: WebVitalMetric;
|
||||
/** First Contentful Paint - 首次内容绘制时间 */
|
||||
FCP: WebVitalMetric;
|
||||
/** Cumulative Layout Shift - 累积布局偏移 */
|
||||
CLS: WebVitalMetric;
|
||||
/** First Input Delay - 首次输入延迟 */
|
||||
FID: WebVitalMetric;
|
||||
/** Time to First Byte - 首字节时间 */
|
||||
TTFB: WebVitalMetric;
|
||||
}
|
||||
|
||||
// ============================================================
|
||||
// 资源加载指标
|
||||
// ============================================================
|
||||
|
||||
/**
|
||||
* 资源类型
|
||||
*/
|
||||
export type ResourceType = 'script' | 'stylesheet' | 'image' | 'font' | 'document' | 'other';
|
||||
|
||||
/**
|
||||
* 单个资源加载指标
|
||||
*/
|
||||
export interface ResourceTiming {
|
||||
/** 资源名称 */
|
||||
name: string;
|
||||
/** 资源类型 */
|
||||
type: ResourceType;
|
||||
/** 资源大小（字节） */
|
||||
size: number;
|
||||
/** 加载耗时（毫秒） */
|
||||
duration: number;
|
||||
/** 开始时间 */
|
||||
startTime: number;
|
||||
/** 是否来自缓存 */
|
||||
fromCache: boolean;
|
||||
}
|
||||
|
||||
/**
|
||||
* 资源加载统计
|
||||
*/
|
||||
export interface ResourceStats {
|
||||
/** JS 文件总大小（字节） */
|
||||
totalJsSize: number;
|
||||
/** CSS 文件总大小（字节） */
|
||||
totalCssSize: number;
|
||||
/** 图片总大小（字节） */
|
||||
totalImageSize: number;
|
||||
/** 字体总大小（字节） */
|
||||
totalFontSize: number;
|
||||
/** 总加载时间（毫秒） */
|
||||
totalLoadTime: number;
|
||||
/** 缓存命中率（0-1） */
|
||||
cacheHitRate: number;
|
||||
/** 详细的资源列表 */
|
||||
resources: ResourceTiming[];
|
||||
}
|
||||
|
||||
// ============================================================
|
||||
// 首屏指标
|
||||
// ============================================================
|
||||
|
||||
/**
|
||||
* 首屏性能指标
|
||||
*/
|
||||
export interface FirstScreenMetrics {
|
||||
/** Web Vitals 指标 */
|
||||
webVitals: Partial<WebVitalsMetrics>;
|
||||
/** 资源加载统计 */
|
||||
resourceStats: ResourceStats;
|
||||
/** 首屏可交互时间（毫秒） */
|
||||
timeToInteractive: number;
|
||||
/** 骨架屏展示时长（毫秒） */
|
||||
skeletonDisplayDuration: number;
|
||||
/** API 请求统计 */
|
||||
apiStats: ApiRequestStats;
|
||||
/** 测量时间戳 */
|
||||
measuredAt: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* API 请求统计
|
||||
*/
|
||||
export interface ApiRequestStats {
|
||||
/** 总请求数 */
|
||||
totalRequests: number;
|
||||
/** 平均响应时间（毫秒） */
|
||||
avgResponseTime: number;
|
||||
/** 最慢的请求耗时（毫秒） */
|
||||
slowestRequest: number;
|
||||
/** 失败的请求数 */
|
||||
failedRequests: number;
|
||||
/** 详细的请求列表 */
|
||||
requests: ApiRequestTiming[];
|
||||
}
|
||||
|
||||
/**
|
||||
* 单个 API 请求时序
|
||||
*/
|
||||
export interface ApiRequestTiming {
|
||||
/** 请求 URL */
|
||||
url: string;
|
||||
/** 请求方法 */
|
||||
method: string;
|
||||
/** 响应时间（毫秒） */
|
||||
duration: number;
|
||||
/** HTTP 状态码 */
|
||||
status: number;
|
||||
/** 是否成功 */
|
||||
success: boolean;
|
||||
/** 开始时间 */
|
||||
startTime: number;
|
||||
}
|
||||
|
||||
// ============================================================
|
||||
// 业务指标
|
||||
// ============================================================
|
||||
|
||||
/**
|
||||
* 功能卡片点击统计
|
||||
*/
|
||||
export interface FeatureCardMetrics {
|
||||
/** 卡片 ID */
|
||||
cardId: string;
|
||||
/** 卡片标题 */
|
||||
cardTitle: string;
|
||||
/** 点击次数 */
|
||||
clicks: number;
|
||||
/** 点击率（CTR） */
|
||||
clickRate: number;
|
||||
/** 平均点击时间（距离页面加载的毫秒数） */
|
||||
avgClickTime: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* 首页业务指标
|
||||
*/
|
||||
export interface HomePageBusinessMetrics {
|
||||
/** 页面浏览次数（PV） */
|
||||
pageViews: number;
|
||||
/** 独立访客数（UV） */
|
||||
uniqueVisitors: number;
|
||||
/** 平均停留时长（秒） */
|
||||
avgSessionDuration: number;
|
||||
/** 跳出率（0-1） */
|
||||
bounceRate: number;
|
||||
/** 登录转化率（0-1） */
|
||||
loginConversionRate: number;
|
||||
/** 功能卡片点击统计 */
|
||||
featureCards: FeatureCardMetrics[];
|
||||
}
|
||||
|
||||
// ============================================================
|
||||
// PostHog 事件属性
|
||||
// ============================================================
|
||||
|
||||
/**
|
||||
* PostHog 性能事件通用属性
|
||||
*/
|
||||
export interface PerformanceEventProperties {
|
||||
/** 页面类型 */
|
||||
page_type: string;
|
||||
/** 设备类型 */
|
||||
device_type?: string;
|
||||
/** 网络类型 */
|
||||
network_type?: string;
|
||||
/** 浏览器 */
|
||||
browser?: string;
|
||||
/** 是否已登录 */
|
||||
is_authenticated?: boolean;
|
||||
/** 测量时间戳 */
|
||||
measured_at: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Web Vitals 事件属性
|
||||
*/
|
||||
export interface WebVitalsEventProperties extends PerformanceEventProperties {
|
||||
/** 指标名称 */
|
||||
metric_name: 'LCP' | 'FCP' | 'CLS' | 'FID' | 'TTFB';
|
||||
/** 指标值 */
|
||||
metric_value: number;
|
||||
/** 评级 */
|
||||
metric_rating: MetricRating;
|
||||
/** 与上周对比 */
|
||||
delta?: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* 资源加载事件属性
|
||||
*/
|
||||
export interface ResourceLoadEventProperties extends PerformanceEventProperties {
|
||||
/** JS 总大小（KB） */
|
||||
js_size_kb: number;
|
||||
/** CSS 总大小（KB） */
|
||||
css_size_kb: number;
|
||||
/** 图片总大小（KB） */
|
||||
image_size_kb: number;
|
||||
/** 总加载时间（秒） */
|
||||
total_load_time_s: number;
|
||||
/** 缓存命中率（百分比） */
|
||||
cache_hit_rate_percent: number;
|
||||
/** 资源总数 */
|
||||
resource_count: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* 首屏可交互事件属性
|
||||
*/
|
||||
export interface FirstScreenInteractiveEventProperties extends PerformanceEventProperties {
|
||||
/** 可交互时间（秒） */
|
||||
tti_seconds: number;
|
||||
/** 骨架屏展示时长（秒） */
|
||||
skeleton_duration_seconds: number;
|
||||
/** API 请求数 */
|
||||
api_request_count: number;
|
||||
/** API 平均响应时间（毫秒） */
|
||||
api_avg_response_time_ms: number;
|
||||
}
|
||||
|
||||
// ============================================================
|
||||
// Hook 配置
|
||||
// ============================================================
|
||||
|
||||
/**
|
||||
* useFirstScreenMetrics Hook 配置选项
|
||||
*/
|
||||
export interface UseFirstScreenMetricsOptions {
|
||||
/** 页面类型（用于区分不同页面） */
|
||||
pageType: string;
|
||||
/** 是否启用控制台日志 */
|
||||
enableConsoleLog?: boolean;
|
||||
/** 是否自动上报到 PostHog */
|
||||
trackToPostHog?: boolean;
|
||||
/** 自定义事件属性 */
|
||||
customProperties?: Record<string, any>;
|
||||
}
|
||||
|
||||
/**
|
||||
* useFirstScreenMetrics Hook 返回值
|
||||
*/
|
||||
export interface UseFirstScreenMetricsResult {
|
||||
/** 是否正在测量 */
|
||||
isLoading: boolean;
|
||||
/** 首屏指标（测量完成后） */
|
||||
metrics: FirstScreenMetrics | null;
|
||||
/** 手动触发重新测量 */
|
||||
remeasure: () => void;
|
||||
/** 导出指标为 JSON */
|
||||
exportMetrics: () => string;
|
||||
}
|
||||
|
||||
// ============================================================
|
||||
// 性能阈值配置
|
||||
// ============================================================
|
||||
|
||||
/**
|
||||
* 单个指标的阈值配置
|
||||
*/
|
||||
export interface MetricThreshold {
|
||||
/** good 阈值（小于此值为 good） */
|
||||
good: number;
|
||||
/** needs-improvement 阈值（小于此值为 needs-improvement，否则 poor） */
|
||||
needsImprovement: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* 所有性能指标的阈值配置
|
||||
*/
|
||||
export interface PerformanceThresholds {
|
||||
LCP: MetricThreshold;
|
||||
FCP: MetricThreshold;
|
||||
CLS: MetricThreshold;
|
||||
FID: MetricThreshold;
|
||||
TTFB: MetricThreshold;
|
||||
TTI: MetricThreshold;
|
||||
}
|
||||
|
||||
// ============================================================
|
||||
// 调试面板
|
||||
// ============================================================
|
||||
|
||||
/**
|
||||
* 调试面板配置
|
||||
*/
|
||||
export interface DebugPanelConfig {
|
||||
/** 是否启用 */
|
||||
enabled: boolean;
|
||||
/** 默认是否展开 */
|
||||
defaultExpanded?: boolean;
|
||||
/** 刷新间隔（毫秒） */
|
||||
refreshInterval?: number;
|
||||
/** 位置 */
|
||||
position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
|
||||
}
|
||||
|
||||
/**
|
||||
* 调试面板数据
|
||||
*/
|
||||
export interface DebugPanelData {
|
||||
/** Web Vitals 指标 */
|
||||
webVitals: Partial<WebVitalsMetrics>;
|
||||
/** 资源统计 */
|
||||
resources: ResourceStats;
|
||||
/** API 统计 */
|
||||
api: ApiRequestStats;
|
||||
/** 首屏时间 */
|
||||
firstScreen: {
|
||||
tti: number;
|
||||
skeletonDuration: number;
|
||||
};
|
||||
/** 最后更新时间 */
|
||||
lastUpdated: number;
|
||||
}
|
||||
Reference in New Issue
Block a user