04-sync-operations.md

同步操作 (Sync Operations)

AI Agent Target: Details the execution logic of sync_supabase_to_firebase.py and generate_ai_explanations.py, including data mapping and failure recovery.
Human Target: 說明資料如何在不同資料庫間同步，以及如何產生自動化解析。

sync_supabase_to_firebase.py

此腳本確保用於即時測驗的高可用性 Firebase RTDB 與主要的 Supabase 關聯式資料庫保持同步。

graph TD
    A[Supabase PostgreSQL] -->|讀取變更| B(sync_supabase_to_firebase.py)
    B -->|轉換格式| C{資料對應}
    C -->|寫入| D[Firebase RTDB]

操作內容

• 欄位對應 (Field Mapping): 將 Supabase 的 snake_case 欄位名稱轉換為 Flutter 客戶端所需的 camelCase JSON 鍵值。
• 索引產生: 在 Firebase 中建立 approvedKeys 索引節點，以快速擷取上線的問題。
• 錯誤處理: 遇到網路逾時時，在記錄失敗前最多重試 3 次。

generate_ai_explanations.py

批次為缺乏解析的問題產生具教育意義的解析。

• 多語言支援: 可產生英文、日文與繁體中文的解析。
• 接續執行 (Resume Capability): 讀取現有資料庫記錄，僅處理遺漏解析的問題。
• 一致性: 產生完成後，會更新 Supabase，進而觸發同步腳本更新 Firebase。

監控 (Monitoring)

檢查這些腳本輸出的日誌，以驗證跨資料庫的一致性。