botrun-horse 2.29.2 → 2.31.0

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

@@ -0,0 +1,85 @@
+/**
+ * 命令實現：list 命令
+ * 列出使用者資訊
+ */
+
+import { Command } from 'commander';
+import { getAuth, getFirestore } from '../firebase.js';
+import { AbstractCommand } from './AbstractCommand.js';
+
+export class ListCommand extends AbstractCommand {
+  constructor(parentCommand: Command) {
+    super(parentCommand);
+  }
+
+  getName(): string {
+    return 'list';
+  }
+
+  getDescription(): string {
+    return '列出使用者資訊';
+  }
+
+  protected setupOptions(): void {
+    this.command
+      .option('--auth', '列出所有 Firebase Auth 使用者')
+      .option('--firestore', '列出 Firestore users collection 使用者')
+      .option('--rate-limit', '列出有 rate limit 記錄的使用者')
+      .option('--subscription', '列出有訂閱記錄的使用者')
+      .option('--export <format>', '匯出格式 (csv|json)');
+  }
+
+  async execute(...args: any[]): Promise<void> {
+    // 最後一個參數是 options 物件
+    const options = args[args.length - 1] || {};
+
+    if (options.auth) {
+      await this.listAuthUsers();
+    } else if (options.firestore) {
+      await this.listFirestoreUsers();
+    } else if (options.rateLimit) {
+      console.log('⚠️  rate-limit 查詢需要額外實現');
+    } else if (options.subscription) {
+      console.log('⚠️  subscription 查詢需要額外實現');
+    } else {
+      console.log('請指定選項: --auth, --firestore, --rate-limit, 或 --subscription');
+      console.log('使用 --help 查看詳細說明');
+    }
+  }
+
+  private async listAuthUsers(): Promise<void> {
+    console.log('📋 列出所有 Firebase Auth 使用者...\n');
+    const auth = getAuth();
+    const listResult = await auth.listUsers(1000);
+
+    console.log(`找到 ${listResult.users.length} 位使用者:\n`);
+    listResult.users.forEach((user, index) => {
+      console.log(`${index + 1}. ${user.email || '(無 email)'}`);
+      console.log(`   UID: ${user.uid}`);
+      console.log(`   建立時間: ${user.metadata.creationTime}`);
+      console.log(`   最後登入: ${user.metadata.lastSignInTime || '從未登入'}`);
+      console.log('');
+    });
+  }
+
+  private async listFirestoreUsers(): Promise<void> {
+    console.log('📊 列出 Firestore users collection 使用者...\n');
+    const db = getFirestore();
+    const snapshot = await db.collection('users').get();
+
+    if (snapshot.empty) {
+      console.log('❌ users collection 是空的！');
+      return;
+    }
+
+    console.log(`✅ 找到 ${snapshot.size} 個使用者文件\n`);
+    snapshot.forEach((doc) => {
+      const data = doc.data();
+      console.log(`👤 User ID: ${doc.id}`);
+      console.log(`   Email: ${data.email || 'N/A'}`);
+      console.log(`   Display Name: ${data.displayName || 'N/A'}`);
+      console.log(`   Plan: ${data.plan || 'Lite (預設)'}`);
+      console.log('');
+    });
+  }
+}

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

@@ -0,0 +1,81 @@
+/**
+ * 命令實現：query 命令
+ * 查詢單一使用者的完整資訊（訂閱 + Rate Limit）
+ */
+
+import { Command } from 'commander';
+import { getFirestore } from '../firebase.js';
+import { UserService } from '../services/UserService.js';
+import { getUserRateLimitCounterIds } from '../firestore-safe.js';
+import { AbstractCommand } from './AbstractCommand.js';
+
+export class QueryCommand extends AbstractCommand {
+  private userService = new UserService();
+
+  constructor(parentCommand: Command) {
+    super(parentCommand);
+  }
+
+  getName(): string {
+    return 'query';
+  }
+
+  getDescription(): string {
+    return '查詢單一使用者的完整資訊（訂閱 + Rate Limit）';
+  }
+
+  protected setupOptions(): void {
+    this.command
+      .argument('<email-or-uid>', '使用者 email 或 UID')
+      .option('--json', '以 JSON 格式輸出');
+  }
+
+  async execute(...args: any[]): Promise<void> {
+    // commander 將參數傳遞為：emailOrUid, options, command
+    const emailOrUid = args[0];
+    const options = args[args.length - 2] || {};
+
+    console.log('🔍 正在查詢使用者資訊...\n');
+
+    // 解析使用者
+    const user = await this.userService.resolveUser(emailOrUid);
+    console.log(`✅ 找到使用者: ${user.email || user.uid}\n`);
+
+    const db = getFirestore();
+
+    // 查詢訂閱
+    console.log('==================================================');
+    console.log('📋 訂閱資訊');
+    console.log('==================================================\n');
+
+    const subDoc = await db.collection('user_subscriptions').doc(user.uid).get();
+    if (subDoc.exists) {
+      const subData = subDoc.data();
+      if (options.json) {
+        console.log(JSON.stringify(subData, null, 2));
+      } else {
+        console.log(`狀態: ${subData?.status}`);
+        console.log(`方案: ${subData?.plan}`);
+        console.log(`試用開始: ${subData?.trialStartDate?.toDate?.() || 'N/A'}`);
+        console.log(`試用結束: ${subData?.trialEndDate?.toDate?.() || 'N/A'}`);
+      }
+    } else {
+      console.log('❌ 沒有訂閱記錄');
+    }
+
+    // 查詢 Rate Limit
+    console.log('\n==================================================');
+    console.log('🔒 Rate Limit 狀態');
+    console.log('==================================================\n');
+
+    const counterIds = await getUserRateLimitCounterIds(user.uid);
+    if (counterIds.length > 0) {
+      console.log(`找到 ${counterIds.length} 個計數器記錄:`);
+      counterIds.forEach(id => console.log(`  - ${id}`));
+    } else {
+      console.log('❌ 沒有 Rate Limit 記錄');
+    }
+
+    console.log('\n==================================================\n');
+  }
+}

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

@@ -0,0 +1,83 @@
+/**
+ * Token 爆量分析指令
+ * 分析特定日期的 token 使用異常
+ *
+ * 用法：
+ *   users-cli spike --date 2025-12-06
+ *   users-cli spike --date 2025-12-06 --output /path/to/output
+ */
+
+import { AbstractCommand } from './AbstractCommand.js';
+import { SpikeAnalyzer } from '../analyzers/SpikeAnalyzer.js';
+import { writeFileSync } from 'fs';
+import { join } from 'path';
+
+export class SpikeCommand extends AbstractCommand {
+  getName(): string {
+    return 'spike';
+  }
+
+  getDescription(): string {
+    return '分析特定日期的 Token 爆量情況（UTC+8）';
+  }
+
+  protected setupOptions(): void {
+    this.command
+      .option('--date <date>', '分析日期（格式：YYYY-MM-DD）', this.getTodayDate())
+      .option('--output <path>', '輸出目錄', process.cwd())
+      .option('--format <format>', '輸出格式（text/json/both）', 'text');
+  }
+
+  private getTodayDate(): string {
+    // 取得 UTC+8 的今天日期
+    const now = new Date();
+    const utc8 = new Date(now.getTime() + 8 * 60 * 60 * 1000);
+    return utc8.toISOString().split('T')[0];
+  }
+
+  async execute(...args: any[]): Promise<void> {
+    const options = args[0] || {};
+
+    const dateStr = options.date || this.getTodayDate();
+    const outputDir = options.output || process.cwd();
+    const format = options.format || 'text';
+
+    // 驗證日期格式
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(dateStr)) {
+      throw new Error('日期格式錯誤，請使用 YYYY-MM-DD 格式');
+    }
+
+    try {
+      const analyzer = new SpikeAnalyzer();
+      const result = await analyzer.analyzeDate(dateStr);
+
+      // 生成文字報告
+      const report = analyzer.generateReport(result);
+
+      // 輸出到終端
+      console.log(report);
+
+      // 儲存報告
+      if (format === 'text' || format === 'both') {
+        const textPath = join(outputDir, `spike-report-${dateStr}.txt`);
+        writeFileSync(textPath, report);
+        console.log(`\n📄 文字報告已儲存：${textPath}`);
+      }
+
+      if (format === 'json' || format === 'both') {
+        const jsonPath = join(outputDir, `spike-report-${dateStr}.json`);
+        writeFileSync(jsonPath, JSON.stringify(result, null, 2));
+        console.log(`📄 JSON 報告已儲存：${jsonPath}`);
+      }
+
+      // 如果有異常，回傳非零 exit code
+      if (result.isAnomaly) {
+        console.log('\n⚠️  偵測到異常活動，請查看上方報告！');
+      }
+
+    } catch (error: any) {
+      console.error('❌ 錯誤：', error.message);
+      throw error;
+    }
+  }
+}

package/botrun-c/admin/lib/domain/User.ts

@@ -0,0 +1,38 @@
+/**
+ * 領域模型：使用者
+ * 代表系統中的核心使用者概念
+ */
+
+import type { PlanType, SubscriptionStatus } from '../types.js';
+
+export interface IUser {
+  uid: string;
+  email: string | null;
+  displayName?: string;
+  createdAt?: Date;
+  lastSignInTime?: Date;
+}
+
+export interface IUserSubscription {
+  userId: string;
+  plan: PlanType;
+  status: SubscriptionStatus;
+  trialStartDate?: Date;
+  trialEndDate?: Date;
+  subscriptionStartDate?: Date;
+  subscriptionEndDate?: Date;
+  createdAt?: Date;
+  updatedAt?: Date;
+}
+
+export interface IUserWithSubscription extends IUser {
+  subscription?: IUserSubscription;
+}
+
+export interface IBatchProvisionResult {
+  email: string;
+  success: boolean;
+  created: boolean;
+  uid?: string;
+  error?: string;
+}

package/botrun-c/admin/lib/firebase.ts

@@ -0,0 +1,92 @@
+/**
+ * Firebase Admin 統一初始化模組
+ */
+
+import admin from 'firebase-admin';
+import { Firestore } from '@google-cloud/firestore';
+import { readFileSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+// ESM __dirname
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+let initialized = false;
+let firestoreInstance: Firestore | null = null;
+
+/**
+ * 初始化 Firebase Admin
+ * 自動偵測並使用可用的認證金鑰
+ */
+export function initializeFirebase(): typeof admin {
+  if (initialized) {
+    return admin;
+  }
+
+  if (admin.apps.length > 0) {
+    initialized = true;
+    return admin;
+  }
+
+  try {
+    // 嘗試多個可能的金鑰路徑（相對於 admin/lib）
+    const possiblePaths = [
+      join(__dirname, '..', '..', 'keys', 'compute-sa-key.json'),
+      join(__dirname, '..', '..', 'keys', 'firebase-admin-key.json'),
+    ];
+
+    let keyFilePath: string | undefined;
+    for (const path of possiblePaths) {
+      if (existsSync(path)) {
+        keyFilePath = path;
+        break;
+      }
+    }
+
+    if (keyFilePath) {
+      const serviceAccount = JSON.parse(readFileSync(keyFilePath, 'utf-8'));
+      admin.initializeApp({
+        credential: admin.credential.cert(serviceAccount),
+      });
+
+      // 同時初始化獨立的 Firestore 實例（避免 google-gax 問題）
+      firestoreInstance = new Firestore({
+        projectId: serviceAccount.project_id,
+        credentials: {
+          client_email: serviceAccount.client_email,
+          private_key: serviceAccount.private_key,
+        },
+      });
+    } else {
+      // 使用 Application Default Credentials
+      admin.initializeApp();
+      firestoreInstance = new Firestore();
+    }
+
+    initialized = true;
+    return admin;
+  } catch (error) {
+    console.error('⚠️  Firebase Admin 初始化失敗:', error);
+    throw error;
+  }
+}
+
+/**
+ * 取得 Firestore 實例（使用獨立實例避免 google-gax 問題）
+ */
+export function getFirestore(): Firestore {
+  initializeFirebase();
+  if (!firestoreInstance) {
+    throw new Error('Firestore not initialized');
+  }
+  return firestoreInstance;
+}
+
+/**
+ * 取得 Auth 實例
+ */
+export function getAuth() {
+  initializeFirebase();
+  return admin.auth();
+}

package/botrun-c/admin/lib/firestore-safe.ts

@@ -0,0 +1,105 @@
+/**
+ * 安全的 Firestore 操作模組
+ * 使用 REST API 避開 google-gax 套件問題
+ */
+
+import { execSync } from 'child_process';
+
+const PROJECT_ID = 'botrun-c';
+
+/**
+ * 使用 gcloud REST API 安全刪除 Firestore 文件
+ * 避開 google-gax 套件的 ERR_PACKAGE_PATH_NOT_EXPORTED 錯誤
+ */
+export async function safeDeleteDocument(
+  collection: string,
+  docId: string
+): Promise<boolean> {
+  try {
+    // 取得 access token
+    const accessToken = execSync('gcloud auth print-access-token', {
+      encoding: 'utf-8',
+    }).trim();
+
+    // URL encode 文件 ID（處理特殊字元如 :）
+    const encodedDocId = encodeURIComponent(docId);
+
+    // DELETE URL
+    const deleteUrl = `https://firestore.googleapis.com/v1/projects/${PROJECT_ID}/databases/(default)/documents/${collection}/${encodedDocId}`;
+
+    // 使用 curl 執行 DELETE
+    const curlCommand = `curl -s -X DELETE -H "Authorization: Bearer ${accessToken}" "${deleteUrl}"`;
+
+    const response = execSync(curlCommand, { encoding: 'utf-8' });
+
+    // 空回應或 {} 表示成功
+    return !response || response.trim() === '{}';
+  } catch (error: any) {
+    console.error(`  ✗ 刪除失敗: ${docId}`, error.message);
+    return false;
+  }
+}
+
+/**
+ * 批次刪除多個文件
+ */
+export async function safeDeleteBatch(
+  collection: string,
+  docIds: string[]
+): Promise<{ success: number; failed: number }> {
+  let success = 0;
+  let failed = 0;
+
+  for (const docId of docIds) {
+    const result = await safeDeleteDocument(collection, docId);
+    if (result) {
+      success++;
+    } else {
+      failed++;
+    }
+  }
+
+  return { success, failed };
+}
+
+/**
+ * 取得使用者的所有 rate limit 計數器 ID
+ */
+export async function getUserRateLimitCounterIds(
+  userId: string
+): Promise<string[]> {
+  try {
+    const accessToken = execSync('gcloud auth print-access-token', {
+      encoding: 'utf-8',
+    }).trim();
+
+    const collectionUrl = `https://firestore.googleapis.com/v1/projects/${PROJECT_ID}/databases/(default)/documents/rate_limit_counters`;
+
+    const response = execSync(
+      `curl -s -H "Authorization: Bearer ${accessToken}" "${collectionUrl}"`,
+      { encoding: 'utf-8' }
+    );
+
+    const data = JSON.parse(response);
+
+    if (!data.documents) {
+      return [];
+    }
+
+    // 解析文件名稱並過濾包含該 userId 的文件
+    const counterIds: string[] = [];
+    for (const doc of data.documents) {
+      const name = doc.name as string;
+      const docId = name.split('/').pop() || '';
+
+      if (docId.includes(userId)) {
+        counterIds.push(docId);
+      }
+    }
+
+    return counterIds;
+  } catch (error) {
+    console.error('❌ 取得計數器 ID 失敗:', error);
+    return [];
+  }
+}

package/botrun-c/admin/lib/formatters.ts

@@ -0,0 +1,154 @@
+/**
+ * 輸出格式化工具
+ */
+
+import { writeFileSync } from 'fs';
+import { execSync } from 'child_process';
+
+/**
+ * 格式化表格輸出
+ */
+export function formatTable(data: any[], columns: string[]): void {
+  if (data.length === 0) {
+    console.log('📭 沒有資料');
+    return;
+  }
+
+  // 計算每列的最大寬度
+  const widths: Record<string, number> = {};
+  for (const col of columns) {
+    widths[col] = col.length;
+    for (const row of data) {
+      const value = String(row[col] || '');
+      widths[col] = Math.max(widths[col], value.length);
+    }
+  }
+
+  // 列印表頭
+  const headerRow = columns.map(col => col.padEnd(widths[col])).join(' | ');
+  console.log(headerRow);
+  console.log(columns.map(col => '-'.repeat(widths[col])).join('-+-'));
+
+  // 列印資料列
+  for (const row of data) {
+    const dataRow = columns.map(col => {
+      const value = String(row[col] || '');
+      return value.padEnd(widths[col]);
+    }).join(' | ');
+    console.log(dataRow);
+  }
+
+  console.log(`\n共 ${data.length} 筆資料\n`);
+}
+
+/**
+ * 匯出 CSV 並自動開啟
+ */
+export async function exportCSV(
+  data: any[],
+  filename: string,
+  autoOpen = true
+): Promise<void> {
+  if (data.length === 0) {
+    console.log('❌ 沒有資料可匯出');
+    return;
+  }
+
+  // 取得所有欄位名稱
+  const headers = Object.keys(data[0]);
+
+  // 產生 CSV 內容
+  const csvLines: string[] = [headers.join(',')];
+
+  for (const row of data) {
+    const values = headers.map(header => {
+      const value = row[header];
+      // 處理包含逗號、引號、換行的值
+      if (value === null || value === undefined) {
+        return '';
+      }
+      const str = String(value);
+      if (str.includes(',') || str.includes('"') || str.includes('\n')) {
+        return `"${str.replace(/"/g, '""')}"`;
+      }
+      return str;
+    });
+    csvLines.push(values.join(','));
+  }
+
+  const csvContent = csvLines.join('\n');
+
+  // 儲存檔案
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, -5);
+  const csvPath = `/tmp/${filename}-${timestamp}.csv`;
+
+  writeFileSync(csvPath, csvContent, 'utf-8');
+
+  console.log(`\n✅ CSV 已儲存: ${csvPath}`);
+
+  // 自動開啟
+  if (autoOpen) {
+    try {
+      execSync(`open "${csvPath}"`, { stdio: 'inherit' });
+      console.log(`📊 正在開啟試算表...\n`);
+    } catch (error) {
+      console.log(`⚠️  無法自動開啟，請手動開啟: ${csvPath}\n`);
+    }
+  }
+}
+
+/**
+ * 格式化 JSON 輸出
+ */
+export function formatJSON(data: any): void {
+  console.log(JSON.stringify(data, null, 2));
+}
+
+/**
+ * 格式化百分比進度條
+ */
+export function formatProgressBar(
+  current: number,
+  limit: number,
+  length = 20
+): string {
+  const percentage = Math.round((current / limit) * 100);
+  const filled = Math.round((current / limit) * length);
+  const empty = length - filled;
+
+  // 顏色選擇
+  let color = '\x1b[32m'; // 綠色 (0-50%)
+  if (percentage >= 80) {
+    color = '\x1b[31m'; // 紅色 (80-100%)
+  } else if (percentage >= 50) {
+    color = '\x1b[33m'; // 黃色 (50-80%)
+  }
+
+  const bar = color + '█'.repeat(filled) + '\x1b[0m' + '░'.repeat(empty);
+  return `${bar} ${percentage}%`;
+}
+
+/**
+ * 格式化日期
+ */
+export function formatDate(date: Date | undefined): string {
+  if (!date) return 'N/A';
+  return date.toISOString().split('T')[0];
+}
+
+/**
+ * 格式化相對時間
+ */
+export function formatRelativeTime(date: Date | undefined): string {
+  if (!date) return 'N/A';
+
+  const now = new Date();
+  const diffMs = now.getTime() - date.getTime();
+  const diffDays = Math.floor(diffMs / (1000 * 60 * 60 * 24));
+
+  if (diffDays === 0) return '今天';
+  if (diffDays === 1) return '昨天';
+  if (diffDays < 7) return `${diffDays} 天前`;
+  if (diffDays < 30) return `${Math.floor(diffDays / 7)} 週前`;
+  return `${Math.floor(diffDays / 30)} 個月前`;
+}