botrun-horse 2.30.0 → 2.34.0

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

@@ -1,344 +0,0 @@
-/**
- * 時間序列分析器
- * 分析使用者在不同時間粒度上的 token 使用情況
- * 支援：小時、日、週、月等多種時間維度
- */
-
-import { getFirestore } from '../firebase.js';
-
-export interface HourlyUsage {
-  hour: number;
-  count: number;
-  tokens: number;
-  percentage: number;
-}
-
-export interface DailyUsage {
-  date: string;
-  dayOfWeek: string;
-  count: number;
-  tokens: number;
-}
-
-export interface WeeklyUsage {
-  weekNumber: number;
-  startDate: string;
-  endDate: string;
-  count: number;
-  tokens: number;
-}
-
-export interface TimeSeriesAnalysisResult {
-  userId: string;
-  email: string;
-  totalTokens: number;
-  inputTokens: number;   // 輸入 tokens（$1/1M）
-  outputTokens: number;  // 輸出 tokens（$5/1M）
-  totalRequests: number;
-  analysisPeriod: {
-    startDate: Date;
-    endDate: Date;
-    days: number;
-  };
-  hourly: HourlyUsage[];
-  daily: DailyUsage[];
-  weekly: WeeklyUsage[];
-  peakHour: number;
-  peakDay: string;
-  peakWeek: number;
-}
-
-export class TimeSeriesAnalyzer {
-  private db = getFirestore();
-
-  /**
-   * 分析特定使用者的時間序列資料
-   * @param userId - 使用者 UID
-   * @param userEmail - 使用者 Email（選擇性，用於顯示）
-   * @param days - 分析天數（7, 30, 90 等）
-   */
-  async analyzeUser(userId: string, userEmail: string = '', days: number = 30): Promise<TimeSeriesAnalysisResult> {
-    const endDate = new Date();
-    const startDate = new Date(endDate);
-    startDate.setDate(startDate.getDate() - days);
-    startDate.setHours(0, 0, 0, 0);
-
-    // 查詢使用者基本資訊（如果沒有提供 email）
-    let email = userEmail;
-    if (!email) {
-      const userDoc = await this.db.collection('users').doc(userId).get();
-      const userData = userDoc.data() || {};
-      email = userData.email || 'Unknown';
-    }
-
-    // 查詢期間內的所有使用記錄
-    const usageRecords = await this.queryUsageRecords(userId, startDate, endDate);
-
-    // 分析時間序列資料
-    const hourly = this.analyzeHourly(usageRecords);
-    const daily = this.analyzeDaily(usageRecords);
-    const weekly = this.analyzeWeekly(usageRecords);
-
-    // 計算總量（分別統計輸入/輸出 tokens）
-    const totalTokens = usageRecords.reduce((sum, r) => sum + (r.tokens || 0), 0);
-    const inputTokens = usageRecords.reduce((sum, r) => sum + (r.inputTokens || 0), 0);
-    const outputTokens = usageRecords.reduce((sum, r) => sum + (r.outputTokens || 0), 0);
-    const totalRequests = usageRecords.length;
-
-    // 找出峰值
-    const peakHour = hourly.length > 0 ? hourly.reduce((max, h) => h.tokens > max.tokens ? h : max).hour : -1;
-    const peakDay = daily.length > 0 ? daily.reduce((max, d) => d.tokens > max.tokens ? d : max).date : '';
-    const peakWeek = weekly.length > 0 ? weekly.reduce((max, w) => w.tokens > max.tokens ? w : max).weekNumber : -1;
-
-    return {
-      userId,
-      email,
-      totalTokens,
-      inputTokens,
-      outputTokens,
-      totalRequests,
-      analysisPeriod: {
-        startDate,
-        endDate,
-        days
-      },
-      hourly,
-      daily,
-      weekly,
-      peakHour,
-      peakDay,
-      peakWeek
-    };
-  }
-
-  /**
-   * 查詢期間內的所有使用記錄
-   * 從 billing-records collection 讀取真實 Token 使用量
-   */
-  private async queryUsageRecords(
-    userId: string,
-    startDate: Date,
-    endDate: Date
-  ): Promise<any[]> {
-    const records: any[] = [];
-
-    try {
-      // 查詢 billing-records collection（真實 Token 使用量記錄）
-      // 注意：避免使用複合索引，先查詢所有該使用者的記錄，再在客戶端過濾
-      const snapshot = await this.db
-        .collection('billing-records')
-        .where('userId', '==', userId)
-        .get();
-
-      snapshot.forEach(doc => {
-        const data = doc.data();
-        const timestamp = data.timestamp?.toDate?.() || new Date();
-
-        // 客戶端過濾時間範圍
-        if (timestamp >= startDate && timestamp <= endDate) {
-          records.push({
-            userId: data.userId,
-            tokens: data.totalTokens || 0,  // inputTokens + outputTokens
-            inputTokens: data.inputTokens || 0,
-            outputTokens: data.outputTokens || 0,
-            costUSD: data.costUSD || 0,
-            timestamp: timestamp,
-            model: data.model || 'unknown',
-            endpoint: data.endpoint || 'chat',
-            id: doc.id
-          });
-        }
-      });
-    } catch (error: any) {
-      // 如果查詢失敗，記錄錯誤並返回空陣列
-      console.warn(`⚠️  查詢 billing-records 失敗: ${error.message}`);
-      return [];
-    }
-
-    return records;
-  }
-
-  /**
-   * 從 rate_limit_counters 推測使用情況（備用方案）
-   */
-  private async inferFromRateLimitCounters(userId: string): Promise<any[]> {
-    const records: any[] = [];
-
-    try {
-      const snapshot = await this.db
-        .collection('rate_limit_counters')
-        .where('userId', '==', userId)
-        .get();
-
-      snapshot.forEach(doc => {
-        const data = doc.data();
-        records.push({
-          userId,
-          tokens: data.tpm_usage || 0,
-          requests: data.rpm_usage || 0,
-          timestamp: new Date(data.resetTime || new Date()),
-          source: 'rate_limit_counters'
-        });
-      });
-    } catch (error) {
-      console.warn('⚠️  無法查詢使用記錄');
-    }
-
-    return records;
-  }
-
-  /**
-   * 按小時分析使用情況
-   */
-  private analyzeHourly(records: any[]): HourlyUsage[] {
-    const hourlyMap = new Map<number, { count: number; tokens: number }>();
-
-    // 初始化 24 小時
-    for (let h = 0; h < 24; h++) {
-      hourlyMap.set(h, { count: 0, tokens: 0 });
-    }
-
-    // 統計資料
-    records.forEach(record => {
-      const timestamp = record.timestamp instanceof Date ? record.timestamp : new Date(record.timestamp);
-      const hour = timestamp.getHours();
-      const current = hourlyMap.get(hour) || { count: 0, tokens: 0 };
-      current.count++;
-      current.tokens += record.tokens || 0;
-      hourlyMap.set(hour, current);
-    });
-
-    // 計算總量以便計算百分比
-    const totalTokens = Array.from(hourlyMap.values()).reduce((sum, h) => sum + h.tokens, 0);
-
-    // 轉換為陣列
-    return Array.from(hourlyMap.entries())
-      .map(([hour, data]) => ({
-        hour,
-        count: data.count,
-        tokens: data.tokens,
-        percentage: totalTokens > 0 ? ((data.tokens / totalTokens) * 100).toFixed(2) as any : 0
-      }))
-      .sort((a, b) => a.hour - b.hour);
-  }
-
-  /**
-   * 按日期分析使用情況
-   */
-  private analyzeDaily(records: any[]): DailyUsage[] {
-    const dailyMap = new Map<string, { count: number; tokens: number }>();
-
-    records.forEach(record => {
-      const timestamp = record.timestamp instanceof Date ? record.timestamp : new Date(record.timestamp);
-      const dateStr = timestamp.toISOString().split('T')[0];
-      const current = dailyMap.get(dateStr) || { count: 0, tokens: 0 };
-      current.count++;
-      current.tokens += record.tokens || 0;
-      dailyMap.set(dateStr, current);
-    });
-
-    // 轉換為陣列，添加週幾資訊
-    return Array.from(dailyMap.entries())
-      .map(([date, data]) => {
-        const dateObj = new Date(date);
-        const dayOfWeek = ['日', '一', '二', '三', '四', '五', '六'][dateObj.getDay()];
-        return {
-          date,
-          dayOfWeek,
-          count: data.count,
-          tokens: data.tokens
-        };
-      })
-      .sort((a, b) => new Date(a.date).getTime() - new Date(b.date).getTime());
-  }
-
-  /**
-   * 按週分析使用情況
-   */
-  private analyzeWeekly(records: any[]): WeeklyUsage[] {
-    const weeklyMap = new Map<number, { count: number; tokens: number; dates: Date[] }>();
-
-    records.forEach(record => {
-      const timestamp = record.timestamp instanceof Date ? record.timestamp : new Date(record.timestamp);
-      const weekNumber = this.getWeekNumber(timestamp);
-      const current = weeklyMap.get(weekNumber) || { count: 0, tokens: 0, dates: [] };
-      current.count++;
-      current.tokens += record.tokens || 0;
-      current.dates.push(timestamp);
-      weeklyMap.set(weekNumber, current);
-    });
-
-    // 轉換為陣列，計算週起迄日期
-    return Array.from(weeklyMap.entries())
-      .map(([weekNumber, data]) => {
-        const dates = data.dates.sort((a, b) => a.getTime() - b.getTime());
-        const startDate = dates[0].toISOString().split('T')[0];
-        const endDate = dates[dates.length - 1].toISOString().split('T')[0];
-
-        return {
-          weekNumber,
-          startDate,
-          endDate,
-          count: data.count,
-          tokens: data.tokens
-        };
-      })
-      .sort((a, b) => a.weekNumber - b.weekNumber);
-  }
-
-  /**
-   * 取得 ISO 週號
-   */
-  private getWeekNumber(date: Date): number {
-    const d = new Date(Date.UTC(date.getFullYear(), date.getMonth(), date.getDate()));
-    const dayNum = d.getUTCDay() || 7;
-    d.setUTCDate(d.getUTCDate() + 4 - dayNum);
-    const yearStart = new Date(Date.UTC(d.getUTCFullYear(), 0, 1));
-    return Math.ceil((((d.getTime() - yearStart.getTime()) / 86400000) + 1) / 7);
-  }
-
-  /**
-   * 批量分析多個使用者
-   */
-  async analyzeMultipleUsers(
-    users: Array<{ id: string; email: string }> | string[],
-    days: number = 30
-  ): Promise<TimeSeriesAnalysisResult[]> {
-    const results: TimeSeriesAnalysisResult[] = [];
-
-    // 支援舊的簽名（只有 userIds 陣列）和新的簽名（包含 email）
-    const userList = Array.isArray(users) && users.length > 0 && typeof users[0] === 'string'
-      ? (users as string[]).map(id => ({ id, email: '' }))
-      : (users as Array<{ id: string; email: string }>);
-
-    for (const user of userList) {
-      try {
-        const result = await this.analyzeUser(user.id, user.email, days);
-        results.push(result);
-      } catch (error) {
-        console.warn(`⚠️  無法分析使用者 ${user.id}`);
-      }
-    }
-
-    return results;
-  }
-
-  /**
-   * 取得使用者排行榜（按 token 總量排序）
-   */
-  async getRankings(
-    userIds: string[],
-    days: number = 30,
-    limit: number = 10
-  ): Promise<(TimeSeriesAnalysisResult & { rank: number })[]> {
-    const analyses = await this.analyzeMultipleUsers(userIds, days);
-
-    return analyses
-      .sort((a, b) => b.totalTokens - a.totalTokens)
-      .slice(0, limit)
-      .map((analysis, index) => ({
-        ...analysis,
-        rank: index + 1
-      }));
-  }
-}

package/botrun-c/admin/lib/cli/CLIBootstrapper.ts

@@ -1,40 +0,0 @@
-/**
- * CLI 初始化器
- * 統一註冊和管理所有命令
- */
-
-import { Command } from 'commander';
-import { ListCommand } from '../commands/ListCommand.js';
-import { QueryCommand } from '../commands/QueryCommand.js';
-
-export class CLIBootstrapper {
-  private program: Command;
-
-  constructor(program: Command) {
-    this.program = program;
-  }
-
-  /**
-   * 初始化所有命令
-   */
-  initialize(): void {
-    // 主命令
-    this.registerCommand(new ListCommand(this.program));
-    this.registerCommand(new QueryCommand(this.program));
-
-    // TODO: 後續新增其他命令
-    // - RateLimitCommand（包含子命令）
-    // - SubscriptionCommand（包含子命令）
-    // - PlanCommand（包含子命令）
-    // - BatchCommand（包含子命令）
-    // - MigrateCommand（包含子命令）
-    // - SeedCommand
-  }
-
-  /**
-   * 註冊單一命令
-   */
-  private registerCommand(command: any): void {
-    command.registerHandler();
-  }
-}

package/botrun-c/admin/lib/commands/AbstractCommand.ts

@@ -1,69 +0,0 @@
-/**
- * 命令層基類：AbstractCommand
- * 所有 CLI 命令的共同基礎，遵循 DRY 原則
- */
-
-import { Command } from 'commander';
-
-export interface ICommandHandler {
-  execute(...args: any[]): Promise<void>;
-  getName(): string;
-  getDescription(): string;
-}
-
-export abstract class AbstractCommand implements ICommandHandler {
-  protected command: Command;
-
-  constructor(parentCommand?: Command) {
-    if (parentCommand) {
-      this.command = parentCommand.command(this.getName());
-    } else {
-      this.command = new Command(this.getName());
-    }
-
-    this.command.description(this.getDescription());
-    this.setupOptions();
-  }
-
-  /**
-   * 取得命令名稱
-   */
-  abstract getName(): string;
-
-  /**
-   * 取得命令描述
-   */
-  abstract getDescription(): string;
-
-  /**
-   * 執行命令的核心邏輯
-   * 使用可變參數以支援不同命令的不同簽名
-   */
-  abstract execute(...args: any[]): Promise<void>;
-
-  /**
-   * 設定命令選項（由子類覆寫）
-   */
-  protected setupOptions(): void {
-    // 空實現，由子類覆寫
-  }
-
-  /**
-   * 取得 Commander 命令物件
-   */
-  getCommandObject(): Command {
-    return this.command;
-  }
-
-  /**
-   * 註冊命令處理器
-   */
-  registerHandler(): void {
-    this.command.action((...args) => {
-      this.execute(...args).catch((error) => {
-        console.error('❌ 執行失敗:', error.message);
-        process.exit(1);
-      });
-    });
-  }
-}

package/botrun-c/admin/lib/commands/AnalyticsCommand.ts

@@ -1,215 +0,0 @@
-/**
- * 分析命令：生成使用者分析報告
- * 整合 TimeSeriesAnalyzer、BillingAnalyticsService、CsvExporter、HtmlChartGenerator
- *
- * 用法：
- *   users-cli analytics --days=7 --format=both
- *   users-cli analytics --days=30 --format=csv --output=/path/to/output
- */
-
-import { AbstractCommand } from './AbstractCommand.js';
-import { getAuth, getFirestore } from '../firebase.js';
-import { TimeSeriesAnalyzer } from '../analyzers/TimeSeriesAnalyzer.js';
-import { BillingAnalyticsService } from '../analyzers/BillingAnalyticsService.js';
-import { CsvExporter } from '../analyzers/CsvExporter.js';
-import { HtmlChartGenerator } from '../analyzers/HtmlChartGenerator.js';
-import { writeFileSync } from 'fs';
-import { join } from 'path';
-
-export class AnalyticsCommand extends AbstractCommand {
-  getName(): string {
-    return 'analytics';
-  }
-
-  getDescription(): string {
-    return '生成使用者分析報告（成本、使用量、時間序列分析）';
-  }
-
-  protected setupOptions(): void {
-    this.command
-      .option('--days <number>', '分析天數（7/30/90）', '7')
-      .option('--format <format>', '輸出格式（csv/html/both）', 'both')
-      .option('--output <path>', '輸出目錄', process.cwd());
-  }
-
-  async execute(...args: any[]): Promise<void> {
-    const options = args[0] || {};
-
-    // 解析選項
-    const days = parseInt(options.days || '7', 10);
-    const format = options.format || 'both';
-    const outputDir = options.output || process.cwd();
-
-    // 驗證參數
-    if (isNaN(days) || days < 1) {
-      throw new Error('天數必須是正整數');
-    }
-
-    if (!['csv', 'html', 'both'].includes(format)) {
-      throw new Error('格式必須是 csv、html 或 both');
-    }
-
-    console.log(`🚀 開始生成過去 ${days} 天的完整分析報告...\n`);
-
-    try {
-      const auth = getAuth();
-      const db = getFirestore();
-
-      // 查詢所有使用者（分頁查詢）
-      console.log('📋 查詢所有使用者...');
-      const allUsers = [];
-      let pageToken = undefined;
-
-      do {
-        const result = await auth.listUsers(1000, pageToken);
-        allUsers.push(...result.users);
-        console.log(`⏳ 已載入 ${allUsers.length} 位使用者...`);
-        pageToken = result.pageToken;
-      } while (pageToken);
-
-      if (allUsers.length === 0) {
-        console.log('❌ 沒有找到任何使用者');
-        return;
-      }
-
-      console.log(`✅ 找到 ${allUsers.length} 位使用者\n`);
-
-      // 查詢使用者的訂閱資訊
-      console.log('📊 查詢使用者訂閱資訊...');
-      const userDataList = [];
-
-      for (const user of allUsers) {
-        try {
-          const subDoc = await db.collection('user_subscriptions').doc(user.uid).get();
-
-          userDataList.push({
-            id: user.uid,
-            email: user.email || 'Unknown',
-            plan: subDoc.exists ? (subDoc.data()?.plan || 'Lite') : 'Lite'
-          });
-        } catch (error) {
-          console.warn(`⚠️  無法查詢使用者 ${user.uid} 的資訊`);
-        }
-      }
-
-      console.log(`✅ 查詢完成\n`);
-
-      // 生成時間序列分析
-      console.log('⏱️  生成時間序列分析...');
-      const timeSeriesAnalyzer = new TimeSeriesAnalyzer();
-      const analyses = await timeSeriesAnalyzer.analyzeMultipleUsers(userDataList, days);
-      console.log(`✅ 分析完成：${analyses.length} 位使用者\n`);
-
-      // 生成成本分析報告
-      console.log('💰 生成成本分析報告...');
-      const billingService = new BillingAnalyticsService();
-      const billingReport = await billingService.generateBillingReport(userDataList, days);
-      console.log(`✅ 成本分析完成\n`);
-
-      // 生成 CSV 報告
-      if (format === 'csv' || format === 'both') {
-        console.log('📄 生成 CSV 報告...');
-        const csvExporter = new CsvExporter();
-        const billingCsv = csvExporter.exportBillingReport(billingReport);
-        const billingCsvPath = join(outputDir, `botrun-billing-report-${Date.now()}.csv`);
-        writeFileSync(billingCsvPath, billingCsv);
-        console.log(`✅ CSV 報告已儲存：${billingCsvPath}\n`);
-      }
-
-      // 生成 HTML 儀表板
-      if (format === 'html' || format === 'both') {
-        console.log('🎨 生成 HTML 儀表板...');
-        const htmlGenerator = new HtmlChartGenerator();
-        const dashboardHtml = htmlGenerator.generateBillingDashboard(billingReport);
-        const dashboardPath = join(outputDir, `botrun-dashboard-${Date.now()}.html`);
-        writeFileSync(dashboardPath, dashboardHtml);
-        console.log(`✅ HTML 儀表板已儲存：${dashboardPath}\n`);
-
-        // 生成時間序列 HTML（前 3 個使用者）
-        if (analyses.length > 0) {
-          console.log('📊 生成時間序列 HTML 頁面...');
-          for (let i = 0; i < Math.min(3, analyses.length); i++) {
-            const timeSeriesHtml = htmlGenerator.generateTimeSeriesPage(analyses[i]);
-            const timeSeriesPath = join(
-              outputDir,
-              `botrun-timeseries-${analyses[i].userId}-${Date.now()}.html`
-            );
-            writeFileSync(timeSeriesPath, timeSeriesHtml);
-            console.log(`✅ 時間序列頁面已儲存：${timeSeriesPath}`);
-          }
-          console.log('');
-        }
-      }
-
-      // 列印摘要資訊
-      console.log('════════════════════════════════════════════════════════════');
-      console.log('📈 分析報告摘要');
-      console.log('════════════════════════════════════════════════════════════\n');
-
-      // 計算實際成本（輸入 + 輸出）
-      const totalInputTokens = billingReport.metrics.reduce((sum, m) => sum + (m.inputTokens || 0), 0);
-      const totalOutputTokens = billingReport.metrics.reduce((sum, m) => sum + (m.outputTokens || 0), 0);
-      const totalInputCost = billingReport.metrics.reduce((sum, m) => sum + (m.inputCost || 0), 0);
-      const totalOutputCost = billingReport.metrics.reduce((sum, m) => sum + (m.outputCost || 0), 0);
-      const actualTotalCost = totalInputCost + totalOutputCost;
-
-      console.log('📊 成本分析報告（Claude Haiku 4.5 定價）：');
-      console.log(`   總使用者數: ${billingReport.totalUsers}`);
-      console.log(`   總 Token 數: ${(billingReport.totalTokensAcrossUsers / 1000000).toFixed(2)}M`);
-      console.log(`   ├─ 輸入 Tokens: ${(totalInputTokens / 1000000).toFixed(2)}M`);
-      console.log(`   └─ 輸出 Tokens: ${(totalOutputTokens / 1000000).toFixed(2)}M`);
-      console.log(`   實際成本 (${days}天): $${actualTotalCost.toFixed(2)}`);
-      console.log(`   ├─ 輸入成本 ($1/1M): $${totalInputCost.toFixed(2)}`);
-      console.log(`   └─ 輸出成本 ($5/1M): $${totalOutputCost.toFixed(2)}`);
-      console.log(`   日均成本: $${(actualTotalCost / days).toFixed(2)}/日`);
-      console.log(`   預估月成本: $${billingReport.totalCostAcrossUsers.toFixed(2)}/月\n`);
-
-      console.log('🏆 成本最高的 5 位使用者：');
-      billingReport.topSpenders.slice(0, 5).forEach((user, index) => {
-        console.log(`   ${index + 1}. ${user.email}: $${user.estimatedMonthlyCost.toFixed(2)}/月`);
-      });
-      console.log('');
-
-      console.log('📦 按方案分佈：');
-      billingReport.costBreakdown.forEach((breakdown) => {
-        console.log(
-          `   ${breakdown.plan}: ${breakdown.userCount} 位使用者, $${breakdown.totalCost.toFixed(2)} (${breakdown.percentage.toFixed(1)}%)`
-        );
-      });
-      console.log('');
-
-      if (analyses.length > 0) {
-        const firstAnalysis = analyses[0];
-        console.log(`📅 時間序列分析（${firstAnalysis.email}）：`);
-        console.log(`   總 Token 數: ${(firstAnalysis.totalTokens / 1000000).toFixed(2)}M`);
-        console.log(`   總請求數: ${firstAnalysis.totalRequests}`);
-        console.log(`   峰值時段: ${firstAnalysis.peakHour}:00`);
-        console.log(`   峰值日期: ${firstAnalysis.peakDay}\n`);
-
-        console.log('⏰ 按小時使用量統計（前 5 個高峰）：');
-        const topHours = firstAnalysis.hourly.sort((a, b) => b.tokens - a.tokens).slice(0, 5);
-        if (topHours.length > 0) {
-          topHours.forEach((hour, index) => {
-            console.log(
-              `   ${index + 1}. ${hour.hour}:00 - ${(hour.tokens / 1000000).toFixed(4)}M Token (${hour.percentage}%)`
-            );
-          });
-        } else {
-          console.log('   ⚠️  沒有可用的小時統計資料');
-        }
-        console.log('');
-      }
-
-      console.log('════════════════════════════════════════════════════════════');
-      console.log('✅ 報告生成完成！\n');
-    } catch (error: any) {
-      console.error('❌ 錯誤：', error.message);
-      if (error.code === 'PERMISSION_DENIED') {
-        console.error('\n⚠️  Firebase 認證失敗');
-        console.error('   請確保設定了 GOOGLE_APPLICATION_CREDENTIALS 環境變數');
-        console.error('   或使用 firebase login 進行登入');
-      }
-      throw error;
-    }
-  }
-}