@qhr123/sa2kit 0.7.2 → 0.8.0

package/dist/analytics/server/index.d.ts

@@ -0,0 +1,499 @@
+import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
+
+/**
+ * 埋点系统数据库 Schema
+ * Analytics Database Schema
+ *
+ * 使用方式：
+ * 在 backend/drizzle/migrations/schema.ts 中导入并导出：
+ * export { analyticsEvents } from '@lyricnote/shared/analytics/server/schema'
+ */
+/**
+ * 埋点事件表
+ */
+declare const analyticsEvents: drizzle_orm_pg_core.PgTableWithColumns<{
+    name: "analytics_events";
+    schema: undefined;
+    columns: {
+        id: drizzle_orm_pg_core.PgColumn<{
+            name: "id";
+            tableName: "analytics_events";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        eventType: drizzle_orm_pg_core.PgColumn<{
+            name: "event_type";
+            tableName: "analytics_events";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        eventName: drizzle_orm_pg_core.PgColumn<{
+            name: "event_name";
+            tableName: "analytics_events";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        timestamp: drizzle_orm_pg_core.PgColumn<{
+            name: "timestamp";
+            tableName: "analytics_events";
+            dataType: "string";
+            columnType: "PgTimestampString";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        priority: drizzle_orm_pg_core.PgColumn<{
+            name: "priority";
+            tableName: "analytics_events";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        userId: drizzle_orm_pg_core.PgColumn<{
+            name: "user_id";
+            tableName: "analytics_events";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        sessionId: drizzle_orm_pg_core.PgColumn<{
+            name: "session_id";
+            tableName: "analytics_events";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        deviceId: drizzle_orm_pg_core.PgColumn<{
+            name: "device_id";
+            tableName: "analytics_events";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        pageUrl: drizzle_orm_pg_core.PgColumn<{
+            name: "page_url";
+            tableName: "analytics_events";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        pageTitle: drizzle_orm_pg_core.PgColumn<{
+            name: "page_title";
+            tableName: "analytics_events";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        referrer: drizzle_orm_pg_core.PgColumn<{
+            name: "referrer";
+            tableName: "analytics_events";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        properties: drizzle_orm_pg_core.PgColumn<{
+            name: "properties";
+            tableName: "analytics_events";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: unknown;
+            driverParam: unknown;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        platform: drizzle_orm_pg_core.PgColumn<{
+            name: "platform";
+            tableName: "analytics_events";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        appVersion: drizzle_orm_pg_core.PgColumn<{
+            name: "app_version";
+            tableName: "analytics_events";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        sdkVersion: drizzle_orm_pg_core.PgColumn<{
+            name: "sdk_version";
+            tableName: "analytics_events";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        createdAt: drizzle_orm_pg_core.PgColumn<{
+            name: "createdAt";
+            tableName: "analytics_events";
+            dataType: "string";
+            columnType: "PgTimestampString";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
+
+/**
+ * 服务端类型定义
+ * Server-side Types
+ */
+interface AnalyticsEvent {
+    id: string;
+    eventType: string;
+    eventName: string;
+    timestamp: string;
+    priority: number;
+    userId?: string | null;
+    sessionId: string;
+    deviceId: string;
+    pageUrl?: string | null;
+    pageTitle?: string | null;
+    referrer?: string | null;
+    properties?: any;
+    platform: string;
+    appVersion: string;
+    sdkVersion: string;
+}
+interface AnalyticsQueryParams {
+    startDate?: string;
+    endDate?: string;
+    eventType?: string;
+    eventTypes?: string[];
+    userId?: string;
+    platform?: string;
+    platforms?: string[];
+    sessionId?: string;
+    limit?: number;
+    offset?: number;
+    orderBy?: 'timestamp' | 'eventType' | 'platform';
+    orderDirection?: 'asc' | 'desc';
+}
+interface AnalyticsStats {
+    totalEvents: number;
+    uniqueUsers: number;
+    uniqueSessions: number;
+    uniqueDevices: number;
+    eventsByType: {
+        eventType: string;
+        count: number;
+    }[];
+    eventsByPlatform: {
+        platform: string;
+        count: number;
+    }[];
+    topPages: {
+        pageUrl: string;
+        count: number;
+    }[];
+}
+interface UserBehavior {
+    userId: string;
+    eventCount: number;
+    lastActive: string;
+    platforms: string[];
+    topEvents: {
+        eventType: string;
+        count: number;
+    }[];
+}
+interface SessionAnalytics {
+    sessionId: string;
+    userId?: string;
+    deviceId: string;
+    platform: string;
+    startTime: string;
+    endTime: string;
+    duration: number;
+    eventCount: number;
+    events: AnalyticsEvent[];
+}
+interface DatabaseInstance {
+    select: (...args: any[]) => any;
+    insert: (...args: any[]) => any;
+    delete: (...args: any[]) => any;
+}
+
+/**
+ * 埋点分析服务
+ * Analytics Service
+ *
+ * 使用方式：
+ * import { createAnalyticsService } from '@lyricnote/shared/analytics/server'
+ * const service = createAnalyticsService(db, analyticsEvents, logger)
+ */
+
+interface Logger {
+    info: (message: string, data?: any) => void;
+    error: (message: string, error: Error) => void;
+}
+/**
+ * 创建埋点服务实例
+ * @param db - Drizzle 数据库实例
+ * @param analyticsEventsTable - analytics_events 表定义
+ * @param logger - 日志实例（可选）
+ */
+declare function createAnalyticsService(db: DatabaseInstance, analyticsEventsTable: any, logger?: Logger): {
+    /**
+     * 批量插入埋点事件
+     */
+    insertAnalyticsEvents(events: AnalyticsEvent[]): Promise<void>;
+    /**
+     * 查询埋点事件
+     */
+    queryAnalyticsEvents(params: AnalyticsQueryParams): Promise<{
+        events: AnalyticsEvent[];
+        total: number;
+    }>;
+    /**
+     * 获取统计数据
+     */
+    getAnalyticsStats(startDate?: string, endDate?: string, platform?: string): Promise<AnalyticsStats>;
+    /**
+     * 获取用户行为分析
+     */
+    getUserBehavior(userId: string, startDate?: string, endDate?: string): Promise<UserBehavior | null>;
+    /**
+     * 获取会话分析
+     */
+    getSessionAnalytics(sessionId: string): Promise<SessionAnalytics | null>;
+    /**
+     * 获取漏斗分析
+     */
+    getFunnelAnalysis(steps: string[], startDate?: string, endDate?: string): Promise<{
+        step: string;
+        count: number;
+        conversionRate: number;
+    }[]>;
+    /**
+     * 删除旧数据（数据清理）
+     */
+    cleanOldAnalyticsEvents(daysToKeep?: number): Promise<number>;
+};
+
+/**
+ * 埋点 API 路由处理器
+ * Analytics API Route Handlers
+ *
+ * 使用方式（Next.js）：
+ * import { createAnalyticsHandlers } from '@lyricnote/shared/analytics/server'
+ * const handlers = createAnalyticsHandlers(analyticsService)
+ * export const POST = handlers.handleEventsPost
+ */
+
+interface AnalyticsService {
+    insertAnalyticsEvents: (events: AnalyticsEvent[]) => Promise<void>;
+    queryAnalyticsEvents: (params: AnalyticsQueryParams) => Promise<{
+        events: AnalyticsEvent[];
+        total: number;
+    }>;
+    getAnalyticsStats: (startDate?: string, endDate?: string, platform?: string) => Promise<any>;
+    getUserBehavior: (userId: string, startDate?: string, endDate?: string) => Promise<any>;
+    getSessionAnalytics: (sessionId: string) => Promise<any>;
+    getFunnelAnalysis: (steps: string[], startDate?: string, endDate?: string) => Promise<any>;
+}
+interface Request {
+    json: () => Promise<any>;
+    url?: string;
+    nextUrl?: {
+        searchParams: URLSearchParams;
+    };
+}
+/**
+ * 创建埋点 API 处理器
+ */
+declare function createAnalyticsHandlers(service: AnalyticsService, ResponseClass?: any): {
+    /**
+     * POST /api/analytics/events
+     * 处理事件上报
+     */
+    handleEventsPost(request: Request): Promise<any>;
+    /**
+     * GET /api/analytics/query
+     * 查询埋点事件
+     */
+    handleQueryGet(request: Request): Promise<any>;
+    /**
+     * GET /api/analytics/stats
+     * 获取统计数据
+     */
+    handleStatsGet(request: Request): Promise<any>;
+    /**
+     * GET /api/analytics/user/[userId]
+     * 获取用户行为分析
+     */
+    handleUserBehaviorGet(request: Request, params: {
+        userId: string;
+    }): Promise<any>;
+    /**
+     * GET /api/analytics/session/[sessionId]
+     * 获取会话分析
+     */
+    handleSessionAnalyticsGet(_request: Request, params: {
+        sessionId: string;
+    }): Promise<any>;
+    /**
+     * POST /api/analytics/funnel
+     * 漏斗分析
+     */
+    handleFunnelPost(request: Request): Promise<any>;
+};
+
+export { type AnalyticsEvent, type AnalyticsQueryParams, type AnalyticsStats, type DatabaseInstance, type SessionAnalytics, type UserBehavior, analyticsEvents, createAnalyticsHandlers, createAnalyticsService };