Local Setup

本地開發環境設定與疑難排解 (Local Setup & Troubleshooting)

歡迎來到 Money2 的開發指南！本文件將引導您如何在本地機器上設定開發環境、設定必備的環境變數，以及如何執行測試。

1. 開發環境需求 (Prerequisites)

在開始之前，請確保您的開發環境符合以下要求：

• JDK 17: 專案編譯依賴 JDK 17。
• Android Studio: 請安裝 Android Studio Koala 或更新版本。
• Android SDK: 需要安裝 SDK (Min API 26 / Target API 37)。

2. 取得專案與初始設定 (Getting Started)

1. 複製專案原始碼到本地端：

   git clone https://github.com/Max97k/money2.git
   cd money2

2. 開啟 Android Studio，選擇 Open 並指向 money2 專案資料夾。
3. 等待 Gradle 同步完成。

3. 設定本機參數與測試 API 金鑰 (Configuration & API Keys)

基於安全性考量，Money2 不會將任何敏感的 API 金鑰或環境變數提交到版本控制系統。所有的敏感資料皆透過 local.properties 在編譯時安全地注入。

請在專案根目錄下找到（或建立）local.properties 檔案，並加入以下設定：

# 您的 PROXY_SECRET 金鑰
PROXY_SECRET=your_secret_here

# 開發與測試所需的 API 金鑰 (測試 API 金鑰)
TEST_API_KEY=your_test_api_key_here

注意: 請將 your_secret_here 及 your_test_api_key_here 替換為實際取得的測試環境金鑰。您可以向專案管理員索取開發專用的測試 API 金鑰。

4. 執行單元測試 (Running Unit Tests)

為了確保程式碼品質與架構的穩定性，在提交 Pull Request 前請務必執行單元測試。

• 透過 Android Studio: 在左側 Project 面板中，對著 app/src/test 目錄點擊右鍵，選擇 Run 'Tests in...'。

• 透過終端機指令 (Gradle): 您也可以使用 Gradle Wrapper 在終端機中執行所有的單元測試：

  # Windows
  gradlew test
  
  # macOS / Linux
  ./gradlew test

  如果需要執行 Android UI 或儀表板測試 (Instrumentation Tests)，請確保已連接模擬器或實體裝置，並執行：

  ./gradlew connectedAndroidTest

5. 常見疑難排解 (Troubleshooting)

• 無法編譯或 Gradle 同步失敗 請至 Android Studio 的 File > Settings > Build, Execution, Deployment > Build Tools > Gradle (macOS 為 Android Studio > Settings)，確認 Gradle JDK 是否已設定為 JDK 17。
• 找不到 PROXY_SECRET 請檢查您的 local.properties 中是否已正確設定 PROXY_SECRET 變數。如果遺漏，編譯器將會給予警告或錯誤。
• 快取造成的非預期錯誤 如果遇到難以解決的編譯問題，建議您可以點選頂部選單的 Build > Clean Project，接著執行 Build > Rebuild Project 來重新建置專案。