botrun-horse 2.29.2 → 2.30.0

package/botrun-c/admin/lib/analyzers/SpikeAnalyzer.ts

@@ -0,0 +1,608 @@
+/**
+ * Token 爆量分析器
+ * 分析特定日期的 token 使用異常，識別可疑活動
+ * 所有時間使用 UTC+8（台灣時間）
+ */
+
+import { getFirestore, getAuth } from '../firebase.js';
+
+export interface SpikeRecord {
+  userId: string;
+  email?: string;
+  inputTokens: number;
+  outputTokens: number;
+  totalTokens: number;
+  model: string;
+  endpoint: string;
+  timestamp: Date;
+  costUSD: number;
+}
+
+export interface UserSpikeSummary {
+  userId: string;
+  email: string;
+  totalTokens: number;
+  inputTokens: number;
+  outputTokens: number;
+  requestCount: number;
+  cost: number;
+  percentage: number;
+  avgTokensPerRequest: number;
+  peakHour: number;
+  isNewUser: boolean;
+  accountAgeDays: number;
+  nightActivityPercent: number;  // 00:00-06:00 佔比
+  largeRequests: number;  // > 50K tokens 的請求數
+  flags: string[];
+}
+
+export interface HourlySpike {
+  hour: number;
+  tokens: number;
+  requests: number;
+  percentage: number;
+}
+
+export interface SpikeAnalysisResult {
+  date: string;
+  timezone: string;
+
+  // 當日統計
+  totalTokens: number;
+  inputTokens: number;
+  outputTokens: number;
+  totalRequests: number;
+  totalCost: number;
+
+  // 對比統計（過去7天均值）
+  avgDailyTokens: number;
+  avgDailyRequests: number;
+  avgDailyCost: number;
+
+  // 偏離倍數
+  tokenDeviation: number;
+  requestDeviation: number;
+  costDeviation: number;
+
+  // 異常指標
+  isAnomaly: boolean;
+  anomalyReasons: string[];
+
+  // 使用者分析
+  userSummaries: UserSpikeSummary[];
+  topUsers: UserSpikeSummary[];
+
+  // 時段分析
+  hourlyDistribution: HourlySpike[];
+  peakHour: number;
+  nightActivityPercent: number;
+
+  // 大請求分析
+  largeRequestCount: number;
+  largeRequestUsers: string[];
+}
+
+// 大請求閾值
+const LARGE_REQUEST_THRESHOLD = 50000;
+// 異常偏離閾值
+const ANOMALY_THRESHOLD = 3;
+// 單一使用者佔比警告閾值
+const USER_DOMINANCE_THRESHOLD = 0.4;
+// 深夜活動警告閾值
+const NIGHT_ACTIVITY_THRESHOLD = 0.3;
+// 新帳號天數
+const NEW_USER_DAYS = 7;
+
+export class SpikeAnalyzer {
+  private db = getFirestore();
+  private auth = getAuth();
+
+  /**
+   * 將 UTC 時間轉換為 UTC+8
+   */
+  private toUTC8(date: Date): Date {
+    return new Date(date.getTime() + 8 * 60 * 60 * 1000);
+  }
+
+  /**
+   * 取得 UTC+8 的日期開始時間
+   */
+  private getDateStartUTC8(dateStr: string): Date {
+    // dateStr 格式: 2025-12-06
+    const [year, month, day] = dateStr.split('-').map(Number);
+    // 建立 UTC+8 的 00:00:00，轉換為 UTC
+    const utc8Start = new Date(Date.UTC(year, month - 1, day, 0, 0, 0));
+    // UTC+8 00:00 = UTC 前一天 16:00
+    return new Date(utc8Start.getTime() - 8 * 60 * 60 * 1000);
+  }
+
+  /**
+   * 取得 UTC+8 的日期結束時間
+   */
+  private getDateEndUTC8(dateStr: string): Date {
+    // dateStr 格式: 2025-12-06
+    const [year, month, day] = dateStr.split('-').map(Number);
+    // 建立 UTC+8 的 23:59:59，轉換為 UTC
+    const utc8End = new Date(Date.UTC(year, month - 1, day, 23, 59, 59, 999));
+    // UTC+8 23:59:59 = UTC 當天 15:59:59
+    return new Date(utc8End.getTime() - 8 * 60 * 60 * 1000);
+  }
+
+  /**
+   * 取得 UTC+8 的小時
+   */
+  private getHourUTC8(date: Date): number {
+    const utc8Date = this.toUTC8(date);
+    return utc8Date.getUTCHours();
+  }
+
+  /**
+   * 分析特定日期的 token 使用情況
+   */
+  async analyzeDate(dateStr: string): Promise<SpikeAnalysisResult> {
+    console.log(`📊 分析 ${dateStr} 的 Token 使用情況（UTC+8）...\n`);
+
+    const startDate = this.getDateStartUTC8(dateStr);
+    const endDate = this.getDateEndUTC8(dateStr);
+
+    // 查詢當日記錄
+    const records = await this.queryRecords(startDate, endDate);
+    console.log(`✅ 找到 ${records.length} 筆記錄\n`);
+
+    // 查詢過去 7 天的記錄（用於計算均值）
+    const past7DaysRecords = await this.queryPast7Days(dateStr);
+
+    // 查詢使用者資訊
+    const userEmails = await this.getUserEmails(records);
+    const userCreationDates = await this.getUserCreationDates(records);
+
+    // 計算當日統計
+    const dayStats = this.calculateDayStats(records);
+
+    // 計算 7 天均值
+    const avgStats = this.calculateAverageStats(past7DaysRecords);
+
+    // 計算偏離倍數
+    const tokenDeviation = avgStats.avgDailyTokens > 0
+      ? dayStats.totalTokens / avgStats.avgDailyTokens
+      : 0;
+    const requestDeviation = avgStats.avgDailyRequests > 0
+      ? dayStats.totalRequests / avgStats.avgDailyRequests
+      : 0;
+    const costDeviation = avgStats.avgDailyCost > 0
+      ? dayStats.totalCost / avgStats.avgDailyCost
+      : 0;
+
+    // 使用者分析
+    const userSummaries = this.analyzeUsers(
+      records,
+      dayStats.totalTokens,
+      userEmails,
+      userCreationDates
+    );
+
+    // 時段分析
+    const hourlyDistribution = this.analyzeHourly(records, dayStats.totalTokens);
+    const peakHour = hourlyDistribution.reduce(
+      (max, h) => h.tokens > max.tokens ? h : max,
+      hourlyDistribution[0]
+    ).hour;
+
+    // 深夜活動 (00:00-06:00)
+    const nightTokens = hourlyDistribution
+      .filter(h => h.hour >= 0 && h.hour < 6)
+      .reduce((sum, h) => sum + h.tokens, 0);
+    const nightActivityPercent = dayStats.totalTokens > 0
+      ? nightTokens / dayStats.totalTokens
+      : 0;
+
+    // 大請求分析
+    const largeRequests = records.filter(r => r.totalTokens > LARGE_REQUEST_THRESHOLD);
+    const largeRequestUsers = [...new Set(largeRequests.map(r => userEmails.get(r.userId) || r.userId))];
+
+    // 異常判斷
+    const anomalyReasons: string[] = [];
+    if (tokenDeviation >= ANOMALY_THRESHOLD) {
+      anomalyReasons.push(`Token 使用量為 7 日均值的 ${tokenDeviation.toFixed(1)}x`);
+    }
+    if (requestDeviation >= ANOMALY_THRESHOLD) {
+      anomalyReasons.push(`請求數為 7 日均值的 ${requestDeviation.toFixed(1)}x`);
+    }
+    if (userSummaries.length > 0 && userSummaries[0].percentage > USER_DOMINANCE_THRESHOLD) {
+      anomalyReasons.push(`單一使用者佔比 ${(userSummaries[0].percentage * 100).toFixed(1)}%`);
+    }
+    if (nightActivityPercent > NIGHT_ACTIVITY_THRESHOLD) {
+      anomalyReasons.push(`深夜活動佔比 ${(nightActivityPercent * 100).toFixed(1)}%`);
+    }
+
+    // 檢查新帳號異常
+    const newUserHighUsage = userSummaries.filter(
+      u => u.isNewUser && u.percentage > 0.1
+    );
+    if (newUserHighUsage.length > 0) {
+      anomalyReasons.push(`${newUserHighUsage.length} 個新帳號有高使用量`);
+    }
+
+    return {
+      date: dateStr,
+      timezone: 'UTC+8',
+
+      totalTokens: dayStats.totalTokens,
+      inputTokens: dayStats.inputTokens,
+      outputTokens: dayStats.outputTokens,
+      totalRequests: dayStats.totalRequests,
+      totalCost: dayStats.totalCost,
+
+      avgDailyTokens: avgStats.avgDailyTokens,
+      avgDailyRequests: avgStats.avgDailyRequests,
+      avgDailyCost: avgStats.avgDailyCost,
+
+      tokenDeviation,
+      requestDeviation,
+      costDeviation,
+
+      isAnomaly: anomalyReasons.length > 0,
+      anomalyReasons,
+
+      userSummaries,
+      topUsers: userSummaries.slice(0, 10),
+
+      hourlyDistribution,
+      peakHour,
+      nightActivityPercent,
+
+      largeRequestCount: largeRequests.length,
+      largeRequestUsers
+    };
+  }
+
+  /**
+   * 查詢特定時間範圍的記錄
+   */
+  private async queryRecords(startDate: Date, endDate: Date): Promise<SpikeRecord[]> {
+    const records: SpikeRecord[] = [];
+
+    const snapshot = await this.db.collection('billing-records').get();
+
+    snapshot.forEach(doc => {
+      const data = doc.data();
+      const timestamp = data.timestamp?.toDate?.();
+
+      if (timestamp && timestamp >= startDate && timestamp <= endDate) {
+        records.push({
+          userId: data.userId,
+          inputTokens: data.inputTokens || 0,
+          outputTokens: data.outputTokens || 0,
+          totalTokens: data.totalTokens || 0,
+          model: data.model || 'unknown',
+          endpoint: data.endpoint || 'unknown',
+          timestamp,
+          costUSD: data.costUSD || 0
+        });
+      }
+    });
+
+    return records;
+  }
+
+  /**
+   * 查詢過去 7 天的記錄
+   */
+  private async queryPast7Days(dateStr: string): Promise<SpikeRecord[]> {
+    const endDate = this.getDateStartUTC8(dateStr);  // 不包含當天
+    const startDate = new Date(endDate.getTime() - 7 * 24 * 60 * 60 * 1000);
+
+    return this.queryRecords(startDate, endDate);
+  }
+
+  /**
+   * 取得使用者 email 對應表
+   */
+  private async getUserEmails(records: SpikeRecord[]): Promise<Map<string, string>> {
+    const userIds = [...new Set(records.map(r => r.userId))];
+    const emailMap = new Map<string, string>();
+
+    for (const userId of userIds) {
+      try {
+        const user = await this.auth.getUser(userId);
+        emailMap.set(userId, user.email || 'Unknown');
+      } catch {
+        emailMap.set(userId, 'Unknown');
+      }
+    }
+
+    return emailMap;
+  }
+
+  /**
+   * 取得使用者建立日期
+   */
+  private async getUserCreationDates(records: SpikeRecord[]): Promise<Map<string, Date>> {
+    const userIds = [...new Set(records.map(r => r.userId))];
+    const dateMap = new Map<string, Date>();
+
+    for (const userId of userIds) {
+      try {
+        const user = await this.auth.getUser(userId);
+        if (user.metadata.creationTime) {
+          dateMap.set(userId, new Date(user.metadata.creationTime));
+        }
+      } catch {
+        // 忽略錯誤
+      }
+    }
+
+    return dateMap;
+  }
+
+  /**
+   * 計算當日統計
+   */
+  private calculateDayStats(records: SpikeRecord[]) {
+    const totalTokens = records.reduce((sum, r) => sum + r.totalTokens, 0);
+    const inputTokens = records.reduce((sum, r) => sum + r.inputTokens, 0);
+    const outputTokens = records.reduce((sum, r) => sum + r.outputTokens, 0);
+    const totalRequests = records.length;
+    const totalCost = (inputTokens / 1000000) * 1 + (outputTokens / 1000000) * 5;
+
+    return { totalTokens, inputTokens, outputTokens, totalRequests, totalCost };
+  }
+
+  /**
+   * 計算 7 天均值
+   */
+  private calculateAverageStats(records: SpikeRecord[]) {
+    if (records.length === 0) {
+      return { avgDailyTokens: 0, avgDailyRequests: 0, avgDailyCost: 0 };
+    }
+
+    const totalTokens = records.reduce((sum, r) => sum + r.totalTokens, 0);
+    const inputTokens = records.reduce((sum, r) => sum + r.inputTokens, 0);
+    const outputTokens = records.reduce((sum, r) => sum + r.outputTokens, 0);
+    const totalCost = (inputTokens / 1000000) * 1 + (outputTokens / 1000000) * 5;
+
+    return {
+      avgDailyTokens: totalTokens / 7,
+      avgDailyRequests: records.length / 7,
+      avgDailyCost: totalCost / 7
+    };
+  }
+
+  /**
+   * 分析使用者
+   */
+  private analyzeUsers(
+    records: SpikeRecord[],
+    totalTokens: number,
+    userEmails: Map<string, string>,
+    userCreationDates: Map<string, Date>
+  ): UserSpikeSummary[] {
+    const userMap = new Map<string, {
+      tokens: number;
+      input: number;
+      output: number;
+      count: number;
+      hourlyTokens: Map<number, number>;
+      largeRequests: number;
+    }>();
+
+    const now = new Date();
+
+    records.forEach(r => {
+      const existing = userMap.get(r.userId) || {
+        tokens: 0,
+        input: 0,
+        output: 0,
+        count: 0,
+        hourlyTokens: new Map(),
+        largeRequests: 0
+      };
+
+      existing.tokens += r.totalTokens;
+      existing.input += r.inputTokens;
+      existing.output += r.outputTokens;
+      existing.count++;
+
+      const hour = this.getHourUTC8(r.timestamp);
+      existing.hourlyTokens.set(hour, (existing.hourlyTokens.get(hour) || 0) + r.totalTokens);
+
+      if (r.totalTokens > LARGE_REQUEST_THRESHOLD) {
+        existing.largeRequests++;
+      }
+
+      userMap.set(r.userId, existing);
+    });
+
+    const summaries: UserSpikeSummary[] = [];
+
+    for (const [userId, data] of userMap.entries()) {
+      const email = userEmails.get(userId) || 'Unknown';
+      const creationDate = userCreationDates.get(userId);
+      const accountAgeDays = creationDate
+        ? Math.floor((now.getTime() - creationDate.getTime()) / (24 * 60 * 60 * 1000))
+        : -1;
+      const isNewUser = accountAgeDays >= 0 && accountAgeDays < NEW_USER_DAYS;
+
+      // 找出峰值時段
+      let peakHour = 0;
+      let peakTokens = 0;
+      for (const [hour, tokens] of data.hourlyTokens.entries()) {
+        if (tokens > peakTokens) {
+          peakTokens = tokens;
+          peakHour = hour;
+        }
+      }
+
+      // 深夜活動佔比
+      let nightTokens = 0;
+      for (const [hour, tokens] of data.hourlyTokens.entries()) {
+        if (hour >= 0 && hour < 6) {
+          nightTokens += tokens;
+        }
+      }
+      const nightActivityPercent = data.tokens > 0 ? nightTokens / data.tokens : 0;
+
+      const cost = (data.input / 1000000) * 1 + (data.output / 1000000) * 5;
+      const percentage = totalTokens > 0 ? data.tokens / totalTokens : 0;
+
+      // 標記可疑行為
+      const flags: string[] = [];
+      if (isNewUser && percentage > 0.1) {
+        flags.push('新帳號高使用量');
+      }
+      if (percentage > USER_DOMINANCE_THRESHOLD) {
+        flags.push('佔比過高');
+      }
+      if (nightActivityPercent > 0.5) {
+        flags.push('深夜活動');
+      }
+      if (data.largeRequests > 5) {
+        flags.push('多個大請求');
+      }
+
+      summaries.push({
+        userId,
+        email,
+        totalTokens: data.tokens,
+        inputTokens: data.input,
+        outputTokens: data.output,
+        requestCount: data.count,
+        cost,
+        percentage,
+        avgTokensPerRequest: data.count > 0 ? data.tokens / data.count : 0,
+        peakHour,
+        isNewUser,
+        accountAgeDays,
+        nightActivityPercent,
+        largeRequests: data.largeRequests,
+        flags
+      });
+    }
+
+    // 按 tokens 排序
+    return summaries.sort((a, b) => b.totalTokens - a.totalTokens);
+  }
+
+  /**
+   * 分析時段分佈
+   */
+  private analyzeHourly(records: SpikeRecord[], totalTokens: number): HourlySpike[] {
+    const hourlyMap = new Map<number, { tokens: number; requests: number }>();
+
+    // 初始化 24 小時
+    for (let h = 0; h < 24; h++) {
+      hourlyMap.set(h, { tokens: 0, requests: 0 });
+    }
+
+    records.forEach(r => {
+      const hour = this.getHourUTC8(r.timestamp);
+      const existing = hourlyMap.get(hour)!;
+      existing.tokens += r.totalTokens;
+      existing.requests++;
+    });
+
+    return Array.from(hourlyMap.entries())
+      .map(([hour, data]) => ({
+        hour,
+        tokens: data.tokens,
+        requests: data.requests,
+        percentage: totalTokens > 0 ? data.tokens / totalTokens : 0
+      }))
+      .sort((a, b) => a.hour - b.hour);
+  }
+
+  /**
+   * 生成報告文字
+   */
+  generateReport(result: SpikeAnalysisResult): string {
+    const lines: string[] = [];
+
+    lines.push('═'.repeat(65));
+    lines.push(`🚨 ${result.date} Token 爆量分析報告（${result.timezone}）`);
+    lines.push('═'.repeat(65));
+    lines.push('');
+
+    // 當日概況
+    lines.push('📊 當日概況 vs 7日均值：');
+    lines.push('─'.repeat(65));
+
+    const tokenDev = result.tokenDeviation >= ANOMALY_THRESHOLD ? ' ⚠️' : '';
+    const reqDev = result.requestDeviation >= ANOMALY_THRESHOLD ? ' ⚠️' : '';
+    const costDev = result.costDeviation >= ANOMALY_THRESHOLD ? ' ⚠️' : '';
+
+    lines.push(`   總 Tokens: ${(result.totalTokens / 1000000).toFixed(2)}M (均值 ${(result.avgDailyTokens / 1000000).toFixed(2)}M) ${result.tokenDeviation.toFixed(1)}x${tokenDev}`);
+    lines.push(`   ├─ 輸入: ${(result.inputTokens / 1000000).toFixed(2)}M`);
+    lines.push(`   └─ 輸出: ${(result.outputTokens / 1000000).toFixed(2)}M`);
+    lines.push(`   總請求: ${result.totalRequests} (均值 ${result.avgDailyRequests.toFixed(0)}) ${result.requestDeviation.toFixed(1)}x${reqDev}`);
+    lines.push(`   總成本: $${result.totalCost.toFixed(2)} (均值 $${result.avgDailyCost.toFixed(2)}) ${result.costDeviation.toFixed(1)}x${costDev}`);
+    lines.push('');
+
+    // 異常警告
+    if (result.isAnomaly) {
+      lines.push('🔥 異常警告：');
+      lines.push('─'.repeat(65));
+      result.anomalyReasons.forEach(reason => {
+        lines.push(`   ⚠️  ${reason}`);
+      });
+      lines.push('');
+    }
+
+    // 可疑活動
+    const flaggedUsers = result.userSummaries.filter(u => u.flags.length > 0);
+    if (flaggedUsers.length > 0) {
+      lines.push('🚨 可疑活動：');
+      lines.push('─'.repeat(65));
+      flaggedUsers.slice(0, 5).forEach(user => {
+        const level = user.flags.includes('新帳號高使用量') ? '高' : '中';
+        lines.push(`   [${level}] ${user.email}`);
+        lines.push(`       ${user.flags.join(', ')}`);
+        if (user.isNewUser) {
+          lines.push(`       帳號年齡: ${user.accountAgeDays} 天`);
+        }
+      });
+      lines.push('');
+    }
+
+    // Top 10 使用者
+    lines.push('🏆 當日 Top 10 使用者：');
+    lines.push('─'.repeat(65));
+    result.topUsers.forEach((user, i) => {
+      const flags = user.flags.length > 0 ? ` [${user.flags.join(', ')}]` : '';
+      lines.push(`   ${(i + 1).toString().padStart(2)}. ${user.email.padEnd(35).substring(0, 35)}`);
+      lines.push(`       ${(user.totalTokens / 1000000).toFixed(3)}M tokens | $${user.cost.toFixed(2)} | ${user.requestCount} 請求 | ${(user.percentage * 100).toFixed(1)}%${flags}`);
+    });
+    lines.push('');
+
+    // 時段分佈
+    lines.push('⏰ 時段分佈（UTC+8）：');
+    lines.push('─'.repeat(65));
+
+    const maxTokens = Math.max(...result.hourlyDistribution.map(h => h.tokens));
+    result.hourlyDistribution.forEach(h => {
+      const barLength = maxTokens > 0 ? Math.round((h.tokens / maxTokens) * 30) : 0;
+      const bar = '█'.repeat(barLength);
+      const warning = (h.hour >= 0 && h.hour < 6 && h.percentage > 0.1) ? ' ⚠️' : '';
+      lines.push(`   ${h.hour.toString().padStart(2)}:00 | ${bar.padEnd(30)} ${(h.percentage * 100).toFixed(1)}%${warning}`);
+    });
+    lines.push('');
+
+    // 深夜活動統計
+    if (result.nightActivityPercent > 0.1) {
+      lines.push(`   ⚠️  深夜活動 (00:00-06:00): ${(result.nightActivityPercent * 100).toFixed(1)}%`);
+      lines.push('');
+    }
+
+    // 大請求分析
+    if (result.largeRequestCount > 0) {
+      lines.push('📈 大請求分析 (> 50K tokens/請求)：');
+      lines.push('─'.repeat(65));
+      lines.push(`   共 ${result.largeRequestCount} 個大請求`);
+      lines.push(`   來自: ${result.largeRequestUsers.slice(0, 5).join(', ')}`);
+      lines.push('');
+    }
+
+    lines.push('═'.repeat(65));
+
+    return lines.join('\n');
+  }
+}