FatePal Firebase Emulator Setup Guide

1. 目标

使用 Firebase Emulator Suite 在本地模拟 Firebase 后端服务（Firestore, Auth, Functions），以便：

• 在没有网络连接或不希望影响线上数据的情况下进行开发和测试。
• 加快本地开发迭代速度。
• 方便进行集成测试。（尤其函数较多时）
• 更多好处：看日志快；删测试数据快；不需要fq；增删用户方便

2. 所需模拟器

主要使用以下模拟器：

• Firestore: 模拟 NoSQL 数据库。
• Authentication: 模拟用户认证。
• Functions: 模拟云函数。
• Remote Config: 无本地模拟器，测试时会连接到真实的 Firebase 项目获取配置。

3. 启动模拟器套件

在项目根目录下运行以下命令启动所需模拟器：

firebase emulators:start --only firestore,functions,auth --import=./emulator_data --export-on-exit=./emulator_data

• --only: 指定需要启动的服务。
• --import=./emulator_data: 启动时从 emulator_data 目录加载之前导出的数据（用户、Firestore 数据）。首次运行或想清空时可省略。
• --export-on-exit=./emulator_data: 模拟器关闭时，将当前状态（用户、Firestore 数据）导出到 emulator_data 目录。

模拟器端口 (根据 firebase.json):

• Firestore: 8081
• Auth: 9099
• Functions: 5001
• Emulator UI: 4000 (用于查看数据和管理用户)

4. 配置 Flutter 应用连接模拟器

4.1 全局开关

在 lib/core/config/app_config.dart 文件中设置全局常量 USE_EMULATORS：

// lib/core/config/app_config.dart
const bool USE_EMULATORS = true; // 设置为 true 连接模拟器, false 连接真实 Firebase

4.2 初始化配置 (lib/main.dart)

在 main.dart 的 main 函数中，根据 USE_EMULATORS 调用 _configureFirebaseEmulators：

// lib/main.dart
Future<void> _configureFirebaseEmulators() async {
  // --- 重要：根据测试设备调整 host ---
  // 物理 Android 设备: 使用 PC 在局域网中的 IP 地址 (需保持稳定)
  // Android/iOS 模拟器: 使用 'localhost'
  final String host = Platform.isAndroid ? '192.168.36.150' : 'localhost'; // <-- 当前 IP

  try {
    mainLogger.info('Configuring Firebase Emulators to host: $host');
    FirebaseFirestore.instance.useFirestoreEmulator(host, 8081); 
    FirebaseAuth.instance.useAuthEmulator(host, 9099);
    FirebaseFunctions.instanceFor(region: 'asia-east2').useFunctionsEmulator(host, 5001);
    mainLogger.info('Firebase Emulators configured successfully.');
  } catch (e, stackTrace) {
    mainLogger.severe('Error configuring Firebase Emulators', e, stackTrace);
  }
}

void main() async {
  // ...
  if (USE_EMULATORS) {
    await _configureFirebaseEmulators();
  }