01-firebase-setup.md

Firebase 設定指南

1. 帳號與專案設定

• 前往 Firebase Console 建立新專案。
• 啟用驗證提供者：在 Authentication 區塊，啟用 Google、電子郵件/密碼、與匿名登入。
• 建立 Realtime Database：在您偏好的區域建立一個全新的 Realtime Database 實例。
• 啟用 Crashlytics：導覽至 Crashlytics 並為您的專案啟用它。
• 啟用 App Check：前往 App Check 並使用網頁的 reCAPTCHA、Android 的 Play Integrity，以及 iOS 的 DeviceCheck/App Attest 來註冊您的應用程式。

2. 控制台/儀表板設定

1. 在 Firebase Console 註冊您的 Android、iOS 及網頁應用程式。
2. 下載 Android 的 google-services.json 檔案與 iOS 的 GoogleService-Info.plist。
3. 記下網頁應用程式的 Firebase 設定物件。

3. SDK 安裝

pubspec.yaml 依賴項目

將以下內容加入 pubspec.yaml：

dependencies:
  firebase_core: latest
  firebase_auth: latest
  firebase_database: latest
  firebase_crashlytics: latest
  firebase_app_check: latest

平台設定

• Android：將 google-services.json 放置於 android/app/。在 build.gradle 加上必需的 Google Services 與 Crashlytics 外掛程式。
• iOS：將 GoogleService-Info.plist 放置於 ios/Runner/。
• Web：在 web/index.html 加入 Firebase 設定物件。

4. 程式碼整合

import 'package:firebase_core/firebase_core.dart';
import 'package:firebase_crashlytics/firebase_crashlytics.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  // 初始化 Firebase
  await Firebase.initializeApp();
  
  // 初始化驗證服務
  final authService = AuthService();
  
  // 初始化資料庫服務
  final dbService = DatabaseService();
  
  // 註冊 Crashlytics 錯誤處理程序
  FlutterError.onError = FirebaseCrashlytics.instance.recordFlutterFatalError;
  
  runApp(MyApp());
}

5. 必要的環境變數

6. 安全性規則

透過 Firebase CLI 部署 database.rules.json。

{
  "rules": {
    ".read": "auth != null",
    ".write": "auth != null && root.child('users').child(auth.uid).child('role').val() == 'admin'"
  }
}

基於角色的讀寫規則概述：
在參考實作中，只有經過驗證的使用者可以讀取公開資料。測驗題庫或是認證考試資料的寫入權限，則僅限於擁有 admin 角色的使用者。如果您在設定模擬器的 IP 位址或預設閘道時遇到問題，請確保規則允許該網路存取。

7. 常見問題排除

• 遺失 google-services.json：確保該檔案精確地放置於 android/app/ 目錄中。
• App Check 阻擋請求：確保您在 Firebase Console 已註冊正確的 SHA-256 指紋。

02-supabase-setup.md

Supabase 設定指南

1. 帳號與專案設定

• 在 Supabase 建立一個 Supabase 專案。
• 從專案設定中記下專案 URL 與 anon key。
• 在資料庫設定中啟用 pgvector 擴充功能。
• 為您的資料表設定 RLS (Row Level Security) 政策。

2. 資料庫綱要 (Schema)

• 透過 SQL 編輯器或 Supabase CLI 依序執行遷移檔 (共 8 個遷移檔)。
• 建立具備 vector(768) 欄位的 questions 資料表，以支援語意搜尋。
• 建立 profiles 資料表與基於角色的觸發程序，來同步使用者角色。
• 部署 Edge Functions。

3. SDK 安裝

pubspec.yaml 依賴項目

dependencies:
  supabase_flutter: latest

平台設定

除了基本的網際網路存取權限外，無需特定的平台設定。

4. 程式碼整合

import 'package:supabase_flutter/supabase_flutter.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  await Supabase.initialize(
    url: 'YOUR_SUPABASE_URL',
    anonKey: 'YOUR_SUPABASE_ANON_KEY',
  );
  
  runApp(MyApp());
}

5. 必要的環境變數

6. Edge Functions

透過 Supabase CLI 部署以下 7 個 Edge Functions：

1. generate-embeddings：為測驗題庫產生向量嵌入 (Vector Embeddings)。
2. search-questions：執行向量相似度搜尋。
3. user-role-sync：同步角色變更至 profile 資料表。
4. process-payment：處理付款的 Webhook。
5. export-data：為使用者產生資料匯出。
6. send-notification：觸發推播通知。
7. validate-test-score：驗證認證考試的成績。

supabase functions deploy <function-name>

7. PowerSync 整合

• PowerSync 會直接讀取 Supabase 的 PostgreSQL 資料庫。
• 在 PowerSync 儀表板中設定同步規則，根據使用者的角色限制哪些資料表與資料列可被同步。若是網路設備相關題目，如路由器或交換器的設定，也會依照權限同步。

8. 常見問題排除

• 向量搜尋失敗：確保 pgvector 擴充功能已安裝，且嵌入維度相符 (768)。
• Edge function CORS 問題：請確定在您的 Edge functions 中處理了 OPTIONS 請求，並回傳正確的 CORS 標頭。

03-mongodb-setup.md

MongoDB 設定指南

1. 帳號與專案設定

• 在 MongoDB Atlas 建立一個 MongoDB Atlas 叢集。
• 建立資料庫 (例如 mockexam_db) 與集合 (Questions, Discussions)。
• 設定網路存取權限以允許 IP 位址連線 (針對行動裝置廣泛存取可設為 0.0.0.0/0，但請考量安全性影響)。
• 建立具有適當讀寫權限的資料庫使用者。

2. 控制台/儀表板設定

• 在 Atlas 儀表板，前往 Database Deployments 並點擊「Connect」。
• 選擇「Connect your application」並複製連線字串。

3. SDK 安裝

pubspec.yaml 依賴項目

dependencies:
  mongo_dart: latest

4. 程式碼整合

直接連線 (行動裝置)

import 'package:mongo_dart/mongo_dart.dart';

class MongoService {
  static final MongoService _instance = MongoService._internal();
  late Db _db;

  factory MongoService() {
    return _instance;
  }

  MongoService._internal();

  Future<void> init(String connectionString) async {
    _db = await Db.create(connectionString);
    await _db.open();
  }
}

Cloudflare Worker 代理伺服器 (網頁)

原因：瀏覽器無法透過 Dart 驅動程式使用的標準 TCP 協定直接連線至 MongoDB。

• 設定 Cloudflare Worker 腳本。
• 設定 API 端點以透過 HTTP 代理請求至 MongoDB Atlas Data API。
• 確保腳本中的 CORS 設定允許您的網頁應用程式網域。

5. 必要的環境變數

6. 常見問題排除

• 連線逾時：檢查 Atlas 網路存取清單 (Network Access)。確保您目前的 IP 位址已加入白名單。
• 網頁版連線失敗：確認 Cloudflare Worker 代理伺服器已部署，且 CORS 標頭設定正確。例如，在模擬考試應用程式中查詢路由器的封包狀態時，若發生錯誤，通常與代理設定有關。