botrun-horse 2.29.2 → 2.30.0

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

@@ -0,0 +1,344 @@
+/**
+ * 時間序列分析器
+ * 分析使用者在不同時間粒度上的 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

@@ -0,0 +1,40 @@
+/**
+ * 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

@@ -0,0 +1,69 @@
+/**
+ * 命令層基類：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

@@ -0,0 +1,215 @@
+/**
+ * 分析命令：生成使用者分析報告
+ * 整合 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;
+    }
+  }
+}