botrun-horse 2.29.2 → 2.30.0

package/botrun-c/admin/users.ts

@@ -0,0 +1,1321 @@
+#!/usr/bin/env tsx
+/**
+ * 波特人 Users CLI - 統一使用者管理工具
+ *
+ * 管理 Rate Limit、訂閱、使用者資訊等
+ *
+ * 注意：請透過 users-cli.sh 執行此腳本，以確保正確的環境變數設定
+ */
+
+import { Command } from 'commander';
+import { initializeFirebase, getFirestore, getAuth } from './lib/firebase.js';
+import { resolveUser } from './lib/user-resolver.js';
+import { formatJSON, exportCSV, formatProgressBar, formatDate } from './lib/formatters.js';
+import { safeDeleteBatch, getUserRateLimitCounterIds } from './lib/firestore-safe.js';
+
+// 初始化 Firebase
+initializeFirebase();
+
+const program = new Command();
+
+program
+  .name('users-cli')
+  .description('波特人使用者管理 CLI - 管理 Rate Limit、訂閱、使用者資訊')
+  .version('1.0.0');
+
+// ============================================================================
+// subscription-stats 命令 - 查詢真實方案分佈和成本統計
+// ============================================================================
+
+program
+  .command('subscription-stats')
+  .description('查詢使用者方案分佈和成本統計（基於真實 Token 使用量）')
+  .action(async () => {
+    try {
+      const db = getFirestore();
+      const auth = getAuth();
+
+      console.log('\n📊 查詢真實方案分佈...\n');
+
+      // 1. 查詢所有使用者
+      const allUsers = [];
+      let pageToken = undefined;
+      do {
+        const result = await auth.listUsers(1000, pageToken);
+        allUsers.push(...result.users);
+        pageToken = result.pageToken;
+      } while (pageToken);
+
+      console.log(`✅ 找到 ${allUsers.length} 位使用者\n`);
+
+      // 2. 查詢訂閱資訊和 Token 使用量
+      const planStats = new Map<string, { count: number; totalTokens: number; users: any[] }>();
+      let totalTokens = 0;
+      let userWithData = 0;
+
+      for (const user of allUsers) {
+        try {
+          const subDoc = await db.collection('user_subscriptions').doc(user.uid).get();
+          const plan = subDoc.exists ? (subDoc.data()?.plan || 'Lite') : 'Lite';
+
+          // 查詢 rate_limit_counters 取得 Token 使用量
+          const counterDocs = await db
+            .collection('rate_limit_counters')
+            .where('userId', '==', user.uid)
+            .get();
+
+          let userTokens = 0;
+          counterDocs.forEach(doc => {
+            const data = doc.data();
+            if (data.tokensUsed) userTokens += data.tokensUsed;
+          });
+
+          if (userTokens > 0) userWithData++;
+          totalTokens += userTokens;
+
+          const existing = planStats.get(plan) || { count: 0, totalTokens: 0, users: [] };
+          existing.count++;
+          existing.totalTokens += userTokens;
+          existing.users.push({
+            email: user.email || 'Unknown',
+            tokens: userTokens
+          });
+          planStats.set(plan, existing);
+        } catch (error) {
+          // 忽略查詢錯誤
+        }
+      }
+
+      // 3. 列印統計結果
+      console.log('════════════════════════════════════════════════════════════');
+      console.log('📋 方案分佈統計（基於 user_subscriptions）');
+      console.log('════════════════════════════════════════════════════════════\n');
+
+      let totalCostUSD = 0;
+      Array.from(planStats.entries())
+        .sort((a, b) => b[1].count - a[1].count)
+        .forEach(([plan, data]) => {
+          const tokensMT = (data.totalTokens / 1000000).toFixed(2);
+          const costUSD = (data.totalTokens / 1000000) * 5; // 1M tokens = $5
+          totalCostUSD += costUSD;
+
+          console.log(`📌 ${plan} 方案`);
+          console.log(`   使用者數: ${data.count} 位`);
+          console.log(`   總 Token: ${tokensMT}M (${data.totalTokens.toLocaleString()})`);
+          console.log(`   預估成本: $${costUSD.toFixed(2)} USD`);
+          console.log(`   平均每使用者: ${(data.totalTokens / data.count / 1000000).toFixed(4)}M tokens, $${(costUSD / data.count).toFixed(2)}`);
+          console.log('');
+        });
+
+      console.log('════════════════════════════════════════════════════════════');
+      console.log('📈 總體統計');
+      console.log('════════════════════════════════════════════════════════════\n');
+
+      console.log(`總使用者數: ${allUsers.length}`);
+      console.log(`有 Token 使用的使用者: ${userWithData} (${((userWithData / allUsers.length) * 100).toFixed(1)}%)`);
+      console.log(`總 Token 使用量: ${(totalTokens / 1000000).toFixed(2)}M (${totalTokens.toLocaleString()})`);
+      console.log(`總預估成本: $${totalCostUSD.toFixed(2)} USD`);
+      console.log(`平均每使用者成本: $${(totalCostUSD / allUsers.length).toFixed(2)}`);
+      console.log(`平均每活躍使用者: $${(totalCostUSD / (userWithData || 1)).toFixed(2)}`);
+      console.log('');
+
+      // 4. 計算日均成本（過去 7 天）
+      const dailyAvg = totalCostUSD / 7;
+      console.log('💰 過去 7 天成本評估');
+      console.log(`   總成本: $${totalCostUSD.toFixed(2)}`);
+      console.log(`   日均成本: $${dailyAvg.toFixed(2)}/日`);
+      console.log(`   小時均成本: $${(dailyAvg / 24).toFixed(4)}/小時\n`);
+
+    } catch (error: any) {
+      console.error('❌ 執行失敗:', error.message);
+      process.exit(1);
+    }
+  });
+
+// ============================================================================
+// list 命令 - 列出使用者
+// ============================================================================
+
+const listCommand = program
+  .command('list')
+  .description('列出使用者資訊');
+
+listCommand
+  .option('--auth', '列出所有 Firebase Auth 使用者')
+  .option('--firestore', '列出 Firestore users collection 使用者')
+  .option('--rate-limit', '列出有 rate limit 記錄的使用者')
+  .option('--subscription', '列出有訂閱記錄的使用者')
+  .option('--export <format>', '匯出格式 (csv|json)')
+  .action(async (options) => {
+    try {
+      if (options.auth) {
+        // 列出 Firebase Auth 使用者
+        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('');
+        });
+      } else if (options.firestore) {
+        // 列出 Firestore users collection
+        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('');
+        });
+      } else {
+        console.log('請指定選項: --auth, --firestore, --rate-limit, 或 --subscription');
+        console.log('使用 --help 查看詳細說明');
+      }
+    } catch (error) {
+      console.error('❌ 執行失敗:', error);
+      process.exit(1);
+    }
+  });
+
+// ============================================================================
+// query 命令 - 查詢單一使用者
+// ============================================================================
+
+program
+  .command('query')
+  .description('查詢單一使用者的完整資訊（訂閱 + Rate Limit）')
+  .argument('<email-or-uid>', '使用者 email 或 UID')
+  .option('--json', '以 JSON 格式輸出')
+  .action(async (emailOrUid, options) => {
+    try {
+      console.log('🔍 正在查詢使用者資訊...\n');
+
+      // 解析使用者
+      const user = await 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');
+
+    } catch (error: any) {
+      console.error('❌ 執行失敗:', error.message);
+      process.exit(1);
+    }
+  });
+
+// ============================================================================
+// rate-limit 命令
+// ============================================================================
+
+const rateLimitCommand = program
+  .command('rate-limit')
+  .description('Rate Limit 管理');
+
+rateLimitCommand
+  .command('list')
+  .description('列出所有使用者的 Rate Limit 狀態')
+  .option('--detailed', '顯示詳細資訊（包含 plan、custom limits）')
+  .option('--export <format>', '匯出格式 (csv)')
+  .action(async (options) => {
+    if (options.detailed) {
+      // 使用新的詳細列表功能
+      try {
+        const { getAllDetailedStatuses, displayDetailedStatus } = await import('./lib/rate-limit-detailed.js');
+
+        console.log('🔍 載入所有使用者的詳細 Rate Limit 狀態...\n');
+
+        const statuses = await getAllDetailedStatuses();
+
+        if (statuses.length === 0) {
+          console.log('📭 目前沒有任何使用者');
+          return;
+        }
+
+        console.log(`✅ 找到 ${statuses.length} 位使用者\n`);
+
+        statuses.forEach(status => {
+          displayDetailedStatus(status);
+        });
+
+        // 如果有匯出選項，產生 CSV
+        if (options.export === 'csv') {
+          const { exportToCSV } = await import('./lib/rate-limit-detailed.js');
+          const { writeFileSync } = await import('fs');
+          const { execSync } = await import('child_process');
+
+          const csv = exportToCSV(statuses);
+          const filename = `rate-limit-detailed-${Date.now()}.csv`;
+          writeFileSync(filename, csv);
+
+          console.log(`\n✅ CSV 已匯出: ${filename}`);
+          console.log('📂 正在開啟檔案...\n');
+
+          try {
+            execSync(`open "${filename}"`);
+          } catch (error) {
+            console.log('⚠️  無法自動開啟檔案，請手動開啟');
+          }
+        }
+      } catch (error) {
+        console.error('❌ 執行失敗:', error);
+        process.exit(1);
+      }
+    } else {
+      // 使用舊的列表功能
+      const {
+        getAllUserIds,
+        getUserStatus,
+        displayUserStatus,
+        displaySummary,
+        saveAndOpenCSV,
+      } = await import('./lib/rate-limit.js');
+
+      try {
+        // 取得所有使用者 ID
+        const userIds = await getAllUserIds();
+
+        if (userIds.length === 0) {
+          console.log('📭 目前沒有任何使用者有 Rate Limit 記錄');
+          return;
+        }
+
+        console.log(`\n找到 ${userIds.length} 位使用者\n`);
+
+        // 取得並顯示每個使用者的狀態
+        const statuses = [];
+
+        for (const userId of userIds) {
+          const status = await getUserStatus(userId);
+          statuses.push(status);
+          displayUserStatus(status);
+        }
+
+        // 顯示統計摘要
+        displaySummary(statuses);
+        console.log(`\n${'='.repeat(60)}\n`);
+
+        // 如果有匯出選項，產生 CSV
+        if (options.export === 'csv') {
+          await saveAndOpenCSV(statuses);
+        }
+      } catch (error) {
+        console.error('❌ 執行失敗:', error);
+        process.exit(1);
+      }
+    }
+  });
+
+rateLimitCommand
+  .command('query')
+  .description('查詢特定使用者的 Rate Limit 狀態')
+  .argument('<email-or-uid>', '使用者 email 或 UID')
+  .option('--detailed', '顯示詳細資訊（包含 plan、custom limits、當前值）')
+  .action(async (emailOrUid, options) => {
+    if (options.detailed) {
+      // 使用新的詳細查詢功能
+      try {
+        const { getDetailedRateLimitStatus, displayDetailedStatus } = await import('./lib/rate-limit-detailed.js');
+        const user = await resolveUser(emailOrUid);
+        const status = await getDetailedRateLimitStatus(user.uid);
+        displayDetailedStatus(status);
+      } catch (error: any) {
+        console.error('❌ 執行失敗:', error.message);
+        process.exit(1);
+      }
+    } else {
+      // 使用舊的查詢方式
+      console.log('🔍 查詢 Rate Limit 狀態...\n');
+      const { execSync } = await import('child_process');
+      execSync(`tsx ../api/scripts/query-user-info.ts ${emailOrUid}`, {
+        stdio: 'inherit',
+        cwd: __dirname
+      });
+    }
+  });
+
+rateLimitCommand
+  .command('reset')
+  .description('重置特定使用者的 Rate Limit')
+  .argument('<email-or-uid>', '使用者 email 或 UID')
+  .action(async (emailOrUid) => {
+    try {
+      console.log('🔄 正在重置 Rate Limit...\n');
+
+      // 解析使用者
+      const user = await resolveUser(emailOrUid);
+      console.log(`✅ 找到使用者: ${user.email || user.uid}`);
+      console.log(`👤 UID: ${user.uid}\n`);
+
+      // 取得所有計數器
+      const counterIds = await getUserRateLimitCounterIds(user.uid);
+
+      if (counterIds.length === 0) {
+        console.log('✅ 此使用者沒有任何 Rate Limit 記錄\n');
+        return;
+      }
+
+      console.log(`找到 ${counterIds.length} 個計數器:\n`);
+      counterIds.forEach(id => console.log(`  🗑️  ${id}`));
+
+      console.log(`\n🗑️  準備刪除 ${counterIds.length} 個計數器...\n`);
+
+      // 使用安全刪除（避開 google-gax 問題）
+      const result = await safeDeleteBatch('rate_limit_counters', counterIds);
+
+      console.log(`\n✅ Rate Limit 已成功清除！`);
+      console.log(`📊 成功: ${result.success}, 失敗: ${result.failed}\n`);
+      console.log('🎉 使用者現在可以重新開始使用服務\n');
+
+    } catch (error: any) {
+      console.error('❌ 執行失敗:', error.message);
+      process.exit(1);
+    }
+  });
+
+rateLimitCommand
+  .command('set-custom')
+  .description('設定特定使用者的自訂 Rate Limit')
+  .argument('<email-or-uid>', '使用者 email 或 UID')
+  .option('--rpm <number>', 'RPM (每分鐘請求數) 限制')
+  .option('--tpm <number>', 'TPM (每分鐘 Token 數) 限制')
+  .option('--rpd <number>', 'RPD (每日請求數) 限制')
+  .action(async (emailOrUid, options) => {
+    try {
+      console.log('⚙️  正在設定自訂 Rate Limit...\n');
+
+      // 解析使用者
+      const user = await resolveUser(emailOrUid);
+      console.log(`✅ 找到使用者: ${user.email || user.uid}`);
+      console.log(`👤 UID: ${user.uid}\n`);
+
+      // 建構自訂限制物件
+      const customLimits: any = {};
+      if (options.rpm) customLimits.rpm = parseInt(options.rpm, 10);
+      if (options.tpm) customLimits.tpm = parseInt(options.tpm, 10);
+      if (options.rpd) customLimits.rpd = parseInt(options.rpd, 10);
+
+      if (Object.keys(customLimits).length === 0) {
+        console.error('❌ 請至少指定一個限制值 (--rpm, --tpm, 或 --rpd)');
+        process.exit(1);
+      }
+
+      console.log('📝 設定的自訂限制:');
+      if (customLimits.rpm) console.log(`   RPM: ${customLimits.rpm}`);
+      if (customLimits.tpm) console.log(`   TPM: ${customLimits.tpm}`);
+      if (customLimits.rpd) console.log(`   RPD: ${customLimits.rpd}`);
+      console.log('');
+
+      // 使用新的 setCustomLimits 函數
+      const { setCustomLimits } = await import('./lib/rate-limit-detailed.js');
+      await setCustomLimits(user.uid, customLimits);
+
+      console.log('✅ 自訂限制已成功設定！\n');
+      console.log('📌 注意事項:');
+      console.log('   - 此設定會覆寫該使用者的方案預設限制');
+      console.log('   - 自訂限制在下次 API 請求時生效');
+      console.log('   - 若要移除自訂限制，請使用: rate-limit remove-custom\n');
+
+    } catch (error: any) {
+      console.error('❌ 執行失敗:', error.message);
+      process.exit(1);
+    }
+  });
+
+rateLimitCommand
+  .command('remove-custom')
+  .description('移除特定使用者的自訂 Rate Limit（恢復為方案預設值）')
+  .argument('<email-or-uid>', '使用者 email 或 UID')
+  .action(async (emailOrUid) => {
+    try {
+      console.log('🗑️  正在移除自訂 Rate Limit...\n');
+
+      // 解析使用者
+      const user = await resolveUser(emailOrUid);
+      console.log(`✅ 找到使用者: ${user.email || user.uid}`);
+      console.log(`👤 UID: ${user.uid}\n`);
+
+      // 先顯示目前的自訂限制（如果有）
+      const { getDetailedRateLimitStatus } = await import('./lib/rate-limit-detailed.js');
+      const status = await getDetailedRateLimitStatus(user.uid);
+
+      if (!status.hasCustomLimits) {
+        console.log('✅ 此使用者沒有自訂限制，無需移除\n');
+        return;
+      }
+
+      console.log('⚠️  目前的自訂限制:');
+      if (status.customLimits?.rpm !== undefined) {
+        console.log(`   RPM: ${status.customLimits.rpm}`);
+      }
+      if (status.customLimits?.tpm !== undefined) {
+        console.log(`   TPM: ${status.customLimits.tpm}`);
+      }
+      if (status.customLimits?.rpd !== undefined) {
+        console.log(`   RPD: ${status.customLimits.rpd}`);
+      }
+      console.log('');
+
+      // 移除自訂限制
+      const { removeCustomLimits } = await import('./lib/rate-limit-detailed.js');
+      await removeCustomLimits(user.uid);
+
+      console.log('✅ 自訂限制已成功移除！\n');
+      console.log('📌 結果:');
+      console.log(`   使用者現在使用 ${status.plan} 的預設限制：`);
+      console.log(`   - RPM: ${status.planDefaults.rpm}`);
+      console.log(`   - TPM: ${status.planDefaults.tpm}`);
+      console.log(`   - RPD: ${status.planDefaults.rpd}\n`);
+
+    } catch (error: any) {
+      console.error('❌ 執行失敗:', error.message);
+      process.exit(1);
+    }
+  });
+
+rateLimitCommand
+  .command('set-counter')
+  .description('設定特定使用者的計數器值（危險操作！僅供測試）')
+  .argument('<email-or-uid>', '使用者 email 或 UID')
+  .option('--rpm <number>', '設定 RPM 計數器值')
+  .option('--tpm <number>', '設定 TPM 計數器值')
+  .option('--rpd <number>', '設定 RPD 計數器值')
+  .action(async (emailOrUid, options) => {
+    try {
+      console.log('⚠️  設定計數器值（危險操作）\n');
+
+      // 解析使用者
+      const user = await resolveUser(emailOrUid);
+      console.log(`✅ 找到使用者: ${user.email || user.uid}`);
+      console.log(`👤 UID: ${user.uid}\n`);
+
+      const { setCounterValue } = await import('./lib/rate-limit-detailed.js');
+
+      let updated = 0;
+
+      if (options.rpm !== undefined) {
+        const value = parseInt(options.rpm, 10);
+        console.log(`📝 設定 RPM 計數器 = ${value}`);
+        await setCounterValue(user.uid, 'rpm', value);
+        updated++;
+      }
+
+      if (options.tpm !== undefined) {
+        const value = parseInt(options.tpm, 10);
+        console.log(`📝 設定 TPM 計數器 = ${value}`);
+        await setCounterValue(user.uid, 'tpm', value);
+        updated++;
+      }
+
+      if (options.rpd !== undefined) {
+        const value = parseInt(options.rpd, 10);
+        console.log(`📝 設定 RPD 計數器 = ${value}`);
+        await setCounterValue(user.uid, 'rpd', value);
+        updated++;
+      }
+
+      if (updated === 0) {
+        console.error('\n❌ 請至少指定一個計數器值 (--rpm, --tpm, 或 --rpd)');
+        process.exit(1);
+      }
+
+      console.log(`\n✅ 已成功設定 ${updated} 個計數器！\n`);
+      console.log('⚠️  警告：此操作直接修改計數器，僅供測試使用\n');
+
+    } catch (error: any) {
+      console.error('❌ 執行失敗:', error.message);
+      process.exit(1);
+    }
+  });
+
+rateLimitCommand
+  .command('export')
+  .description('快速匯出所有使用者的詳細 Rate Limit 資訊為 CSV')
+  .action(async () => {
+    try {
+      console.log('📊 匯出所有使用者的 Rate Limit 資訊...\n');
+
+      const { getAllDetailedStatuses, exportToCSV } = await import('./lib/rate-limit-detailed.js');
+      const { writeFileSync } = await import('fs');
+      const { execSync } = await import('child_process');
+
+      console.log('🔍 載入使用者資料...');
+      const statuses = await getAllDetailedStatuses();
+
+      if (statuses.length === 0) {
+        console.log('📭 目前沒有任何使用者\n');
+        return;
+      }
+
+      console.log(`✅ 找到 ${statuses.length} 位使用者\n`);
+
+      const csv = exportToCSV(statuses);
+      const filename = `rate-limit-export-${Date.now()}.csv`;
+      writeFileSync(filename, csv);
+
+      console.log(`✅ CSV 已匯出: ${filename}`);
+      console.log(`📊 包含欄位:`);
+      console.log(`   - 基本資訊: Email, UID, Plan`);
+      console.log(`   - Plan 預設限制: RPM, TPM, RPD`);
+      console.log(`   - 自訂限制: Custom RPM/TPM/RPD`);
+      console.log(`   - 實際生效限制: Effective RPM/TPM/RPD`);
+      console.log(`   - 當前使用量: Current RPM/TPM/RPD`);
+      console.log(`   - 使用率百分比\n`);
+
+      console.log('📂 正在開啟檔案...\n');
+
+      try {
+        execSync(`open "${filename}"`);
+      } catch (error) {
+        console.log('⚠️  無法自動開啟檔案，請手動開啟');
+      }
+
+    } catch (error: any) {
+      console.error('❌ 執行失敗:', error.message);
+      process.exit(1);
+    }
+  });
+
+// ============================================================================
+// subscription 命令
+// ============================================================================
+
+const subscriptionCommand = program
+  .command('subscription')
+  .description('訂閱管理');
+
+subscriptionCommand
+  .command('list')
+  .description('列出所有使用者的訂閱狀態')
+  .option('--export <format>', '匯出格式 (csv)')
+  .action(async (options) => {
+    console.log('📊 列出所有訂閱狀態...\n');
+
+    const { execSync } = await import('child_process');
+    execSync('tsx ../api/scripts/dump-subscriptions.ts', {
+      stdio: 'inherit',
+      cwd: __dirname
+    });
+  });
+
+subscriptionCommand
+  .command('query')
+  .description('查詢特定使用者的訂閱狀態')
+  .argument('<email-or-uid>', '使用者 email 或 UID')
+  .action(async (emailOrUid) => {
+    try {
+      console.log('🔍 查詢訂閱狀態...\n');
+
+      const user = await resolveUser(emailOrUid);
+      const db = getFirestore();
+      const subDoc = await db.collection('user_subscriptions').doc(user.uid).get();
+
+      if (!subDoc.exists) {
+        console.log('❌ 此使用者沒有訂閱記錄\n');
+        return;
+      }
+
+      const data = subDoc.data();
+      console.log('📋 訂閱資訊:');
+      console.log(`   狀態: ${data?.status}`);
+      console.log(`   方案: ${data?.plan}`);
+      console.log(`   試用開始: ${data?.trialStartDate?.toDate?.()}`);
+      console.log(`   試用結束: ${data?.trialEndDate?.toDate?.()}\n`);
+
+    } catch (error: any) {
+      console.error('❌ 執行失敗:', error.message);
+      process.exit(1);
+    }
+  });
+
+subscriptionCommand
+  .command('set-expiry')
+  .description('設定使用者的試用期結束日期（用於測試過期功能）')
+  .argument('<email-or-uid>', '使用者 email 或 UID')
+  .argument('<date>', '過期日期 (格式: YYYY-MM-DD 或 yesterday/today/tomorrow)')
+  .action(async (emailOrUid, dateStr) => {
+    try {
+      console.log('⚙️  正在設定試用期結束日期...\n');
+
+      const user = await resolveUser(emailOrUid);
+      console.log(`✅ 找到使用者: ${user.email || user.uid}`);
+      console.log(`👤 UID: ${user.uid}\n`);
+
+      const db = getFirestore();
+      const subRef = db.collection('user_subscriptions').doc(user.uid);
+      const subDoc = await subRef.get();
+
+      // 解析日期
+      let targetDate: Date;
+      const today = new Date();
+      today.setHours(0, 0, 0, 0);
+
+      if (dateStr === 'yesterday') {
+        targetDate = new Date(today);
+        targetDate.setDate(targetDate.getDate() - 1);
+      } else if (dateStr === 'today') {
+        targetDate = new Date(today);
+      } else if (dateStr === 'tomorrow') {
+        targetDate = new Date(today);
+        targetDate.setDate(targetDate.getDate() + 1);
+      } else {
+        // 嘗試解析 YYYY-MM-DD 格式
+        const parsed = new Date(dateStr);
+        if (isNaN(parsed.getTime())) {
+          console.error(`❌ 無效的日期格式: ${dateStr}`);
+          console.error('   支援格式: YYYY-MM-DD, yesterday, today, tomorrow');
+          process.exit(1);
+        }
+        targetDate = parsed;
+      }
+
+      // 設定結束時間為當天 23:59:59
+      targetDate.setHours(23, 59, 59, 999);
+
+      if (subDoc.exists) {
+        const data = subDoc.data();
+        console.log('📋 目前訂閱資訊:');
+        console.log(`   狀態: ${data?.status}`);
+        console.log(`   方案: ${data?.plan}`);
+        console.log(`   試用結束: ${data?.trialEndDate?.toDate?.() || 'N/A'}\n`);
+
+        // 更新試用結束日期，並根據新日期自動調整狀態
+        const now = new Date();
+        const newStatus = targetDate > now ? 'active' : 'expired';
+
+        await subRef.update({
+          trialEndDate: targetDate,
+          status: newStatus,
+          updatedAt: new Date(),
+        });
+
+        if (data?.status !== newStatus) {
+          console.log(`🔄 狀態已從 ${data?.status} 改為 ${newStatus}`);
+        }
+      } else {
+        // 如果沒有訂閱記錄，建立 trial 訂閱
+        const trialStart = new Date(targetDate);
+        trialStart.setDate(trialStart.getDate() - 14); // 假設 14 天前開始
+
+        await subRef.set({
+          userId: user.uid,
+          plan: 'Lite',
+          status: 'trial',
+          trialStartDate: trialStart,
+          trialEndDate: targetDate,
+          createdAt: new Date(),
+          updatedAt: new Date(),
+        });
+        console.log('📝 已建立新的試用訂閱記錄\n');
+      }
+
+      console.log(`✅ 試用期結束日期已設定為: ${targetDate.toISOString()}`);
+
+      // 判斷是否過期
+      const now = new Date();
+      if (targetDate < now) {
+        console.log(`⚠️  注意：此日期已過期！使用者將被視為試用期結束。\n`);
+      } else {
+        const daysLeft = Math.ceil((targetDate.getTime() - now.getTime()) / (1000 * 60 * 60 * 24));
+        console.log(`📅 距離過期還有 ${daysLeft} 天\n`);
+      }
+
+    } catch (error: any) {
+      console.error('❌ 執行失敗:', error.message);
+      process.exit(1);
+    }
+  });
+
+subscriptionCommand
+  .command('extend')
+  .description('延長使用者的訂閱期限')
+  .argument('<email-or-uid>', '使用者 email 或 UID')
+  .argument('<duration>', '延長時間 (例如: 2y=2年, 6m=6個月, 30d=30天)')
+  .action(async (emailOrUid, duration) => {
+    try {
+      console.log('📅 正在延長訂閱期限...\n');
+
+      // 解析延長時間
+      const match = duration.match(/^(\d+)(y|m|d)$/i);
+      if (!match) {
+        console.error(`❌ 無效的時間格式: ${duration}`);
+        console.error('   支援格式: 2y (2年), 6m (6個月), 30d (30天)');
+        process.exit(1);
+      }
+
+      const amount = parseInt(match[1], 10);
+      const unit = match[2].toLowerCase();
+
+      const user = await resolveUser(emailOrUid);
+      console.log(`✅ 找到使用者: ${user.email || user.uid}`);
+      console.log(`👤 UID: ${user.uid}\n`);
+
+      const db = getFirestore();
+      const subRef = db.collection('user_subscriptions').doc(user.uid);
+      const subDoc = await subRef.get();
+
+      // 計算新的結束日期
+      const now = new Date();
+      let baseDate: Date;
+
+      if (subDoc.exists) {
+        const data = subDoc.data();
+        console.log('📋 目前訂閱資訊:');
+        console.log(`   狀態: ${data?.status}`);
+        console.log(`   方案: ${data?.plan}`);
+
+        // 取得目前結束日期
+        const currentEndDate = data?.subscriptionEndDate?.toDate?.() || data?.trialEndDate?.toDate?.();
+        if (currentEndDate) {
+          console.log(`   目前到期: ${currentEndDate.toLocaleDateString('zh-TW')}`);
+        }
+        console.log('');
+
+        // 從目前結束日期或今天開始計算（取較晚者）
+        baseDate = currentEndDate && currentEndDate > now ? currentEndDate : now;
+      } else {
+        baseDate = now;
+      }
+
+      // 計算新結束日期
+      const newEndDate = new Date(baseDate);
+      switch (unit) {
+        case 'y':
+          newEndDate.setFullYear(newEndDate.getFullYear() + amount);
+          break;
+        case 'm':
+          newEndDate.setMonth(newEndDate.getMonth() + amount);
+          break;
+        case 'd':
+          newEndDate.setDate(newEndDate.getDate() + amount);
+          break;
+      }
+      newEndDate.setHours(23, 59, 59, 999);
+
+      // 更新或建立訂閱
+      const updateData = {
+        subscriptionEndDate: newEndDate,
+        status: 'active',
+        updatedAt: now,
+      };
+
+      if (subDoc.exists) {
+        await subRef.update(updateData);
+      } else {
+        await subRef.set({
+          userId: user.uid,
+          plan: 'Lite',
+          subscriptionStartDate: now,
+          createdAt: now,
+          ...updateData,
+        });
+      }
+
+      const unitNames: Record<string, string> = { y: '年', m: '個月', d: '天' };
+      console.log(`✅ 訂閱已延長 ${amount} ${unitNames[unit]}`);
+      console.log(`📅 新的到期日: ${newEndDate.toLocaleDateString('zh-TW')}`);
+
+      const daysLeft = Math.ceil((newEndDate.getTime() - now.getTime()) / (1000 * 60 * 60 * 24));
+      console.log(`⏳ 距離到期還有 ${daysLeft} 天\n`);
+
+    } catch (error: any) {
+      console.error('❌ 執行失敗:', error.message);
+      process.exit(1);
+    }
+  });
+
+subscriptionCommand
+  .command('reset-trial')
+  .description('重置使用者的試用期訂閱')
+  .argument('<email-or-uid>', '使用者 email 或 UID')
+  .action(async (emailOrUid) => {
+    try {
+      console.log('🔄 正在重置試用期...\n');
+
+      const user = await resolveUser(emailOrUid);
+      const db = getFirestore();
+
+      const subDoc = await db.collection('user_subscriptions').doc(user.uid).get();
+
+      if (subDoc.exists) {
+        console.log('📋 目前訂閱資訊:');
+        const data = subDoc.data();
+        console.log(`   狀態: ${data?.status}`);
+        console.log(`   方案: ${data?.plan}\n`);
+      }
+
+      console.log('🗑️  刪除訂閱記錄...');
+      await db.collection('user_subscriptions').doc(user.uid).delete();
+
+      console.log('\n✅ 訂閱記錄已成功刪除！');
+      console.log('\n🎉 使用者下次使用時將自動建立新的 14 天試用期\n');
+
+    } catch (error: any) {
+      console.error('❌ 執行失敗:', error.message);
+      process.exit(1);
+    }
+  });
+
+// ============================================================================
+// migrate 命令
+// ============================================================================
+
+const migrateCommand = program
+  .command('migrate')
+  .description('資料遷移工具');
+
+migrateCommand
+  .command('plan-free-rpd')
+  .description('遷移 Lite 方案的 RPD 限制（舊稱 plan-free）')
+  .action(async () => {
+    console.log('🔄 執行 Lite 方案 RPD 遷移...\n');
+
+    const { execSync } = await import('child_process');
+    execSync('tsx ../api/scripts/migrate-plan-free-rpd.ts', {
+      stdio: 'inherit',
+      cwd: __dirname
+    });
+  });
+
+// ============================================================================
+// plan 命令 - Plan 管理
+// ============================================================================
+
+const planCommand = program
+  .command('plan')
+  .description('使用者方案管理');
+
+planCommand
+  .command('set')
+  .description('設定特定使用者的方案')
+  .argument('<email-or-uid>', '使用者 email 或 UID')
+  .argument('<plan>', '方案類型 (Lite | Max-1 | Max-2)')
+  .action(async (emailOrUid, plan) => {
+    try {
+      console.log('⚙️  正在設定使用者方案...\n');
+
+      // 驗證方案類型
+      const validPlans = ['Lite', 'Max-1', 'Max-2'];
+      if (!validPlans.includes(plan)) {
+        console.error(`❌ 無效的方案類型: ${plan}`);
+        console.error(`   有效方案: ${validPlans.join(', ')}`);
+        process.exit(1);
+      }
+
+      // 解析使用者
+      const user = await resolveUser(emailOrUid);
+      console.log(`✅ 找到使用者: ${user.email || user.uid}`);
+      console.log(`👤 UID: ${user.uid}\n`);
+
+      const db = getFirestore();
+
+      // 1. 更新 user_subscriptions/{userId}
+      const subRef = db.collection('user_subscriptions').doc(user.uid);
+      const subDoc = await subRef.get();
+
+      if (subDoc.exists) {
+        console.log('📋 目前訂閱資訊:');
+        const data = subDoc.data();
+        console.log(`   狀態: ${data?.status}`);
+        console.log(`   方案: ${data?.plan}\n`);
+
+        // 更新方案，保留其他欄位
+        await subRef.update({
+          plan: plan,
+          updatedAt: new Date(),
+        });
+        console.log(`✅ user_subscriptions 已更新為: ${plan}`);
+      } else {
+        // 如果沒有訂閱記錄，建立 active 訂閱
+        const now = new Date();
+        await subRef.set({
+          userId: user.uid,
+          plan: plan,
+          status: 'active',
+          subscriptionStartDate: now,
+          createdAt: now,
+          updatedAt: now,
+        });
+        console.log(`✅ 已建立新的 active 訂閱，方案: ${plan}`);
+      }
+
+      // 2. 更新 users/{userId} 的 plan 欄位（如果存在）
+      const userRef = db.collection('users').doc(user.uid);
+      const userDoc = await userRef.get();
+
+      if (userDoc.exists) {
+        await userRef.update({
+          plan: plan,
+        });
+        console.log(`✅ users collection 的 plan 欄位已更新為: ${plan}\n`);
+      } else {
+        console.log(`⚠️  users/{userId} 文件不存在，跳過更新\n`);
+      }
+
+      console.log('🎉 方案設定完成！\n');
+      console.log('📌 注意事項:');
+      console.log('   - 新的 Rate Limit 將在下次 API 請求時生效');
+      console.log('   - 若要查看方案限制，請參考 Rate Limit Plans:');
+      console.log('     * Lite:  RPM=6, TPM=200K, RPD=32');
+      console.log('     * Max-1: RPM=6, TPM=600K, RPD=111');
+      console.log('     * Max-2: RPM=6, TPM=600K, RPD=450\n');
+
+    } catch (error: any) {
+      console.error('❌ 執行失敗:', error.message);
+      process.exit(1);
+    }
+  });
+
+planCommand
+  .command('get')
+  .description('查詢特定使用者的方案')
+  .argument('<email-or-uid>', '使用者 email 或 UID')
+  .action(async (emailOrUid) => {
+    try {
+      console.log('🔍 查詢使用者方案...\n');
+
+      const user = await resolveUser(emailOrUid);
+      const db = getFirestore();
+
+      console.log(`✅ 使用者: ${user.email || user.uid}`);
+      console.log(`👤 UID: ${user.uid}\n`);
+
+      // 查詢 user_subscriptions
+      const subDoc = await db.collection('user_subscriptions').doc(user.uid).get();
+
+      if (subDoc.exists) {
+        const data = subDoc.data();
+        console.log('📋 訂閱資訊 (user_subscriptions):');
+        console.log(`   方案: ${data?.plan}`);
+        console.log(`   狀態: ${data?.status}`);
+        if (data?.trialStartDate) {
+          console.log(`   試用開始: ${data.trialStartDate.toDate?.()}`);
+        }
+        if (data?.trialEndDate) {
+          console.log(`   試用結束: ${data.trialEndDate.toDate?.()}`);
+        }
+        if (data?.subscriptionStartDate) {
+          console.log(`   訂閱開始: ${data.subscriptionStartDate.toDate?.()}`);
+        }
+        console.log('');
+      } else {
+        console.log('❌ 沒有訂閱記錄\n');
+      }
+
+      // 查詢 users collection
+      const userDoc = await db.collection('users').doc(user.uid).get();
+      if (userDoc.exists) {
+        const userData = userDoc.data();
+        console.log('👤 使用者資訊 (users):');
+        console.log(`   Email: ${userData?.email || 'N/A'}`);
+        console.log(`   Display Name: ${userData?.displayName || 'N/A'}`);
+        console.log(`   Plan: ${userData?.plan || 'Lite (預設)'}\n`);
+      } else {
+        console.log('⚠️  users/{userId} 文件不存在\n');
+      }
+
+    } catch (error: any) {
+      console.error('❌ 執行失敗:', error.message);
+      process.exit(1);
+    }
+  });
+
+// ============================================================================
+// batch 命令 - 批次建立使用者
+// ============================================================================
+
+const batchCommand = program
+  .command('batch')
+  .description('批次使用者管理（適用於機關組織大量新增）');
+
+batchCommand
+  .command('provision')
+  .description('批次建立或更新使用者（自動建立不存在的使用者）')
+  .argument('<emails...>', 'Email 清單（空格分隔）或使用 --file 指定檔案')
+  .option('-p, --plan <plan>', '方案類型 (Lite | Max-1 | Max-2)', 'Lite')
+  .option('-e, --expiry <date>', '過期日期 (YYYY-MM-DD)', '2030-01-01')
+  .option('-f, --file <path>', '從檔案讀取 Email 清單（每行一個 Email）')
+  .action(async (emailArgs: string[], options) => {
+    try {
+      console.log('🚀 批次建立/更新使用者...\n');
+
+      // 驗證方案類型
+      const validPlans = ['Lite', 'Max-1', 'Max-2'];
+      if (!validPlans.includes(options.plan)) {
+        console.error(`❌ 無效的方案類型: ${options.plan}`);
+        console.error(`   有效方案: ${validPlans.join(', ')}`);
+        process.exit(1);
+      }
+
+      // 解析過期日期
+      const expiryDate = new Date(options.expiry);
+      if (isNaN(expiryDate.getTime())) {
+        console.error(`❌ 無效的日期格式: ${options.expiry}`);
+        console.error('   支援格式: YYYY-MM-DD');
+        process.exit(1);
+      }
+      expiryDate.setHours(23, 59, 59, 999);
+
+      // 收集 Email 清單
+      let emails: string[] = [];
+
+      // 從檔案讀取
+      if (options.file) {
+        const { readFileSync } = await import('fs');
+        const content = readFileSync(options.file, 'utf-8');
+        const fileEmails = content
+          .split('\n')
+          .map(line => line.trim())
+          .filter(line => line && line.includes('@'));
+        emails.push(...fileEmails);
+        console.log(`📂 從檔案讀取 ${fileEmails.length} 個 Email\n`);
+      }
+
+      // 從命令列參數讀取
+      if (emailArgs.length > 0) {
+        // 支援逗號分隔的格式
+        for (const arg of emailArgs) {
+          const argEmails = arg.split(',').map(e => e.trim()).filter(e => e);
+          emails.push(...argEmails);
+        }
+      }
+
+      // 去除重複
+      emails = [...new Set(emails)];
+
+      if (emails.length === 0) {
+        console.error('❌ 沒有提供任何 Email');
+        console.error('   用法: batch provision email1@example.com email2@example.com');
+        console.error('   或:   batch provision --file emails.txt');
+        process.exit(1);
+      }
+
+      console.log(`📋 準備處理 ${emails.length} 個使用者`);
+      console.log(`📦 方案: ${options.plan}`);
+      console.log(`📅 過期日期: ${expiryDate.toLocaleDateString('zh-TW')}\n`);
+      console.log('─'.repeat(60) + '\n');
+
+      // 執行批次建立
+      const { batchProvisionUsers } = await import('./lib/user-resolver.js');
+      const results = await batchProvisionUsers(emails, options.plan, expiryDate);
+
+      // 統計結果
+      const succeeded = results.filter(r => r.success);
+      const failed = results.filter(r => !r.success);
+      const created = results.filter(r => r.created);
+      const updated = succeeded.filter(r => !r.created);
+
+      console.log('\n' + '─'.repeat(60));
+      console.log('\n📊 執行結果:\n');
+
+      if (created.length > 0) {
+        console.log(`✨ 新建立 ${created.length} 位使用者:`);
+        created.forEach(r => console.log(`   + ${r.email}`));
+        console.log('');
+      }
+
+      if (updated.length > 0) {
+        console.log(`🔄 更新 ${updated.length} 位既有使用者:`);
+        updated.forEach(r => console.log(`   ✓ ${r.email}`));
+        console.log('');
+      }
+
+      if (failed.length > 0) {
+        console.log(`❌ 失敗 ${failed.length} 個:`);
+        failed.forEach(r => console.log(`   ✗ ${r.email}: ${r.error}`));
+        console.log('');
+      }
+
+      console.log('─'.repeat(60));
+      console.log(`\n🎉 完成！成功: ${succeeded.length}, 失敗: ${failed.length}\n`);
+
+      if (created.length > 0) {
+        console.log('📌 注意事項:');
+        console.log('   - 新建立的使用者需透過「Google 登入」或「重設密碼」來啟用帳號');
+        console.log('   - 建議通知使用者使用 Google 帳號登入波特人\n');
+      }
+
+    } catch (error: any) {
+      console.error('❌ 執行失敗:', error.message);
+      process.exit(1);
+    }
+  });
+
+batchCommand
+  .command('list-pending')
+  .description('列出尚未註冊的內部人員 Email（從指定清單比對）')
+  .argument('<emails...>', 'Email 清單')
+  .action(async (emailArgs: string[]) => {
+    try {
+      console.log('🔍 檢查使用者註冊狀態...\n');
+
+      const { resolveUser } = await import('./lib/user-resolver.js');
+
+      let emails: string[] = [];
+      for (const arg of emailArgs) {
+        const argEmails = arg.split(',').map(e => e.trim()).filter(e => e && e.includes('@'));
+        emails.push(...argEmails);
+      }
+      emails = [...new Set(emails)];
+
+      const registered: string[] = [];
+      const notRegistered: string[] = [];
+
+      for (const email of emails) {
+        try {
+          await resolveUser(email);
+          registered.push(email);
+        } catch {
+          notRegistered.push(email);
+        }
+      }
+
+      console.log(`✅ 已註冊 (${registered.length}):`);
+      registered.forEach(e => console.log(`   ${e}`));
+
+      console.log(`\n❌ 尚未註冊 (${notRegistered.length}):`);
+      notRegistered.forEach(e => console.log(`   ${e}`));
+
+      console.log('\n💡 提示: 使用 batch provision 可自動建立尚未註冊的使用者\n');
+
+    } catch (error: any) {
+      console.error('❌ 執行失敗:', error.message);
+      process.exit(1);
+    }
+  });
+
+// ============================================================================
+// analytics 命令 - 生成使用者分析報告
+// ============================================================================
+
+const analyticsCommand = program
+  .command('analytics')
+  .description('生成使用者分析報告（成本、使用量、時間序列分析）');
+
+analyticsCommand
+  .option('--days <number>', '分析天數（7/30/90）', '7')
+  .option('--format <format>', '輸出格式（csv/html/both）', 'both')
+  .option('--output <path>', '輸出目錄', process.cwd())
+  .action(async (options) => {
+    try {
+      const { AnalyticsCommand } = await import('./lib/commands/AnalyticsCommand.js');
+      const analyticsCmd = new AnalyticsCommand();
+      await analyticsCmd.execute(options);
+    } catch (error: any) {
+      console.error('❌ 執行失敗:', error.message);
+      process.exit(1);
+    }
+  });
+
+// ============================================================================
+// spike 命令 - Token 爆量分析
+// ============================================================================
+
+const spikeCommand = program
+  .command('spike')
+  .description('分析特定日期的 Token 爆量情況（UTC+8）');
+
+spikeCommand
+  .option('--date <date>', '分析日期（格式：YYYY-MM-DD）')
+  .option('--format <format>', '輸出格式（text/json/both）', 'text')
+  .option('--output <path>', '輸出目錄', process.cwd())
+  .action(async (options) => {
+    try {
+      const { SpikeCommand } = await import('./lib/commands/SpikeCommand.js');
+      const spikeCmd = new SpikeCommand();
+      await spikeCmd.execute(options);
+    } catch (error: any) {
+      console.error('❌ 執行失敗:', error.message);
+      process.exit(1);
+    }
+  });
+
+// ============================================================================
+// seed 命令
+// ============================================================================
+
+const seedCommand = program
+  .command('seed')
+  .description('建立測試資料（開發用）');
+
+seedCommand
+  .option('--rate-limit', '建立 rate limit 測試資料')
+  .option('--subscription', '建立訂閱測試資料')
+  .action(async (options) => {
+    const { execSync } = await import('child_process');
+
+    if (options.rateLimit) {
+      console.log('🌱 建立 Rate Limit 測試資料...\n');
+      execSync('tsx ../api/scripts/seed-rate-limit-test-data.ts', {
+        stdio: 'inherit',
+        cwd: __dirname
+      });
+    }
+
+    if (options.subscription) {
+      console.log('🌱 建立訂閱測試資料...\n');
+      execSync('tsx ../api/scripts/seed-subscription-test-data.ts', {
+        stdio: 'inherit',
+        cwd: __dirname
+      });
+    }
+
+    if (!options.rateLimit && !options.subscription) {
+      console.log('請指定選項: --rate-limit 或 --subscription');
+      console.log('使用 --help 查看詳細說明');
+    }
+  });
+
+// ============================================================================
+// 執行
+// ============================================================================
+
+program.parse(process.argv);