botrun-horse 2.29.2 → 2.30.0

package/botrun-c/fastlane/ANDROID-DEPLOYMENT-SETUP.md

@@ -0,0 +1,825 @@
+# Android 自動部署設定指南
+
+本指南將帶你完成 Botrun Android App 的自動化部署設定，使用 Fastlane + Firebase App Distribution + Google Play Console。
+
+---
+
+## 📋 目錄
+
+### 快速開始（使用現有設定）
+
+1. [前置準備](#前置準備)
+2. [Android Studio 設定](#android-studio-設定)
+3. [取得 Service Account Keys](#取得-service-account-keys)
+4. [設定 Fastlane 配置檔](#設定-fastlane-配置檔)
+5. [執行第一次部署測試](#執行第一次部署測試)
+6. [部署流程](#部署流程)
+7. [疑難排解](#疑難排解)
+
+### 附錄：從零開始建立（首次設定參考）
+
+- [附錄 A：建立 Android 平台](#附錄-a建立-android-平台)
+- [附錄 B：Firebase Service Account 建立流程](#附錄-bfirebase-service-account-建立流程)
+- [附錄 C：Google Play Service Account 建立流程](#附錄-cgoogle-play-service-account-建立流程)
+- [附錄 D：首次手動上傳到 Google Play](#附錄-d首次手動上傳到-google-play)
+
+---
+
+# 快速開始（使用現有設定）
+
+> 💡 **適用對象：** 新加入的團隊成員，使用專案已建立好的 Service Accounts
+
+## 前置準備
+
+### ✅ 必須先完成
+
+1. **Ruby 環境已設定完成**
+   - 📖 參考 [README.md - Ruby 環境設定](./README.md#-ruby-環境設定共用)
+   - ✅ 確認指令可用：
+     ```bash
+     ruby --version              # 應顯示 3.3.0
+     bundle --version            # 應顯示 Bundler version 2.x
+     bundle exec fastlane --version  # 應顯示 fastlane 2.x
+     ```
+
+2. **本地開發環境**
+   - ✅ Node.js & npm 已安裝
+   - ✅ 專案可正常建置（`npm run build` 成功）
+
+3. **帳號權限（向管理員申請）**
+   - ✅ Firebase 專案檢視權限（可選，用於查看部署狀態）
+   - ✅ Google Play Console 檢視權限（可選，用於查看部署狀態）
+
+---
+
+## Android Studio 設定
+
+### 1. 安裝 Android Studio
+
+從 [Android Studio 官網](https://developer.android.com/studio) 下載並安裝。
+
+### 2. 安裝 Android SDK 和 Build Tools
+
+在 Android Studio 中：
+- 開啟 **Preferences / Settings**
+- 導航到 **Appearance & Behavior → System Settings → Android SDK**
+- 安裝至少一個 **Android SDK Platform**（建議最新穩定版）
+- 安裝 **Android SDK Build-Tools**（建議最新版）
+
+### 3. 設定 ANDROID_HOME 環境變數
+
+**macOS/Linux:**
+```bash
+# 加入到 ~/.zshrc 或 ~/.bashrc
+export ANDROID_HOME=$HOME/Library/Android/sdk
+export PATH=$PATH:$ANDROID_HOME/emulator
+export PATH=$PATH:$ANDROID_HOME/tools
+export PATH=$PATH:$ANDROID_HOME/tools/bin
+export PATH=$PATH:$ANDROID_HOME/platform-tools
+
+# 重新載入 shell
+source ~/.zshrc  # 或 source ~/.bashrc
+```
+
+**Windows (PowerShell):**
+```powershell
+# 設定用戶環境變數（永久）
+[System.Environment]::SetEnvironmentVariable('ANDROID_HOME', "$env:LOCALAPPDATA\Android\Sdk", 'User')
+[System.Environment]::SetEnvironmentVariable('Path', "$env:Path;$env:LOCALAPPDATA\Android\Sdk\platform-tools", 'User')
+
+# 重新開啟 PowerShell
+```
+
+### 4. 驗證安裝
+
+```bash
+# 檢查 ANDROID_HOME
+echo $ANDROID_HOME  # macOS/Linux
+echo $env:ANDROID_HOME  # Windows PowerShell
+
+# 檢查 adb
+adb --version
+# 應顯示 Android Debug Bridge 版本資訊
+```
+
+---
+
+## 取得 Service Account Keys
+
+### 需要的檔案
+
+向專案管理員（目前是 Seba）索取以下兩個 JSON 檔案：
+
+1. **Firebase Service Account Key**
+   - 用於：上傳 APK 到 Firebase App Distribution
+   - 檔案名稱：`botrun-c-xxxxx.json`（或類似名稱）
+
+2. **Google Play Service Account Key**
+   - 用於：上傳 AAB 到 Google Play Console
+   - 檔案名稱：`botrun-c-xxxxx.json`（或類似名稱）
+
+### 設定步驟
+
+收到檔案後，執行以下指令：
+
+```bash
+# 進入專案目錄
+cd /path/to/botrun-c
+
+# 建立目錄（如果不存在）
+mkdir -p mobile-android/fastlane
+
+# 複製 Firebase Service Account Key
+cp ~/Downloads/firebase-檔案名稱.json mobile-android/fastlane/firebase-service-account.json
+
+# 複製 Google Play Service Account Key
+cp ~/Downloads/google-play-檔案名稱.json mobile-android/fastlane/google-play-service-account.json
+
+# 設定安全權限（只有你可以讀寫）
+chmod 600 mobile-android/fastlane/firebase-service-account.json
+chmod 600 mobile-android/fastlane/google-play-service-account.json
+
+# 驗證檔案已被 git ignore
+git check-ignore -v mobile-android/fastlane/firebase-service-account.json
+git check-ignore -v mobile-android/fastlane/google-play-service-account.json
+# 兩個都應該顯示被 .gitignore 排除
+```
+
+✅ **安全提醒：** 這兩個檔案已自動被 `.gitignore` 排除，**絕對不要** commit 到 git！
+
+---
+
+## 設定 Fastlane 配置檔
+
+### 1. 建立 .env 檔案
+
+```bash
+cd /path/to/botrun-c/mobile-android/fastlane
+
+# 複製現有的 .env（如果不存在的話，向管理員索取）
+# .env 檔案已經在 mobile-android/fastlane/.env
+```
+
+### 2. 確認 .env 內容
+
+確認 `mobile-android/fastlane/.env` 包含以下資訊：
+
+```bash
+# === Firebase ===
+FIREBASE_APP_ID=1:257949799705:android:2806947bf699e29d0d6188
+
+# Service Account JSON 檔案路徑（相對於此 Fastfile 的路徑）
+FIREBASE_SERVICE_ACCOUNT=./firebase-service-account.json
+
+# === Google Play ===
+GOOGLE_PLAY_SERVICE_ACCOUNT=./google-play-service-account.json
+
+# === Build Paths ===
+ANDROID_PROJECT_PATH=../android
+```
+
+### 3. 設定權限
+
+```bash
+chmod 600 mobile-android/fastlane/.env
+```
+
+✅ **安全提醒：** `.env` 檔案已被 `.gitignore` 排除，不要 commit 到 git！
+
+---
+
+## 建立 Firebase Tester Group
+
+⚠️ **重要：必須先建立 tester group，否則部署會失敗（404 錯誤）**
+
+### 步驟
+
+1. 前往 [Firebase Console](https://console.firebase.google.com/)
+2. 選擇你的專案（botrun-c）
+3. 左側選單點擊 **"App Distribution"**
+4. 如果是第一次使用，點擊 **"Get started"**
+5. 切換到 **"Testers & Groups"** tab
+6. 點擊 **"Add Group"**
+7. 輸入 Group name: `internal-testers`（必須與 Fastfile 中的名稱一致）
+8. 點擊 **"Create group"**
+9. 點擊剛建立的 `internal-testers` group
+10. 點擊 **"Add testers"**
+11. 輸入測試人員的 email（一行一個）
+12. 點擊 **"Add testers"**
+
+✅ **完成！** 現在可以開始部署了。
+
+**常見 tester group 名稱：**
+- `internal-testers` - 內部測試人員（預設）
+- `beta-testers` - Beta 測試人員
+- `qa-team` - QA 團隊
+
+💡 **提示：** Fastfile 中的 `groups: "internal-testers"` 必須與 Firebase Console 中的 group 名稱完全一致（包含大小寫）。
+
+---
+
+## 設定 Android Keystore（用於 Google Play 發佈）
+
+⚠️ **重要：** 發佈到 Google Play 需要簽署的 AAB。如果你只使用 Firebase App Distribution，可以跳過此步驟。
+
+### 選項 A：使用現有 Keystore（推薦）
+
+如果你已經有 keystore（例如之前建立過），請按照以下步驟：
+
+#### 1. 複製 Keystore 到專案
+
+```bash
+# 將你的 keystore 複製到 Android 專案目錄
+cp /path/to/your-keystore.keystore /path/to/botrun-c/mobile-android/android/app/botrun-release.keystore
+
+# 設定權限
+chmod 600 /path/to/botrun-c/mobile-android/android/app/botrun-release.keystore
+```
+
+#### 2. 建立 keystore.properties
+
+在 `mobile-android/android/keystore.properties` 建立檔案：
+
+```properties
+storePassword=你的_keystore_密碼
+keyPassword=你的_key_密碼
+keyAlias=你的_key_alias
+storeFile=app/botrun-release.keystore
+```
+
+**設定權限：**
+```bash
+chmod 600 /path/to/botrun-c/mobile-android/android/keystore.properties
+```
+
+✅ **安全提醒：** keystore 和 keystore.properties 都已被 `.gitignore` 排除，不會 commit 到 git。
+
+#### 3. 驗證 Keystore 規格
+
+確認你的 keystore 符合 Google Play 要求（2024/2025 規範）：
+
+```bash
+keytool -list -v -keystore /path/to/botrun-c/mobile-android/android/app/botrun-release.keystore -alias 你的_alias
+```
+
+**必須符合：**
+- ✅ 2048 bit RSA key
+- ✅ SHA256withRSA 簽章演算法
+- ✅ 有效期至少 25 年
+
+### 選項 B：建立新的 Keystore
+
+如果這是第一次建立 keystore：
+
+```bash
+cd /path/to/botrun-c/mobile-android/android/app
+
+# 建立 keystore（2024/2025 規範）
+keytool -genkeypair -v -storetype PKCS12 \
+  -keystore botrun-release.keystore \
+  -alias botrun-release-key \
+  -keyalg RSA \
+  -keysize 2048 \
+  -validity 9125 \
+  -storepass 你的密碼 \
+  -keypass 你的密碼 \
+  -dname "CN=你的公司名稱, OU=Development, O=你的公司, L=城市, ST=省份, C=國家代碼"
+```
+
+然後按照「選項 A」的步驟 2-3 建立 `keystore.properties`。
+
+⚠️ **極重要：** 備份 keystore 檔案！一旦遺失，將無法再更新已發佈的 app。
+
+### 配置完成檢查
+
+確認以下檔案存在且已被 gitignore：
+
+```bash
+# 檢查檔案
+ls -la mobile-android/android/app/botrun-release.keystore
+ls -la mobile-android/android/keystore.properties
+
+# 確認已被 gitignore
+git check-ignore -v mobile-android/android/app/botrun-release.keystore
+git check-ignore -v mobile-android/android/keystore.properties
+```
+
+✅ 兩個檔案都應該顯示被 `.gitignore` 排除。
+
+---
+
+## 啟用 Google Play Android Developer API
+
+⚠️ **重要：** 如果你計劃使用 Google Play 部署功能（`internal_play` 或 `production`），必須先啟用 Google Play Android Developer API。
+
+### 步驟
+
+1. **前往 API 啟用頁面：**
+
+   前往以下連結（替換 `PROJECT_ID` 為你的專案 ID）：
+   ```
+   https://console.developers.google.com/apis/api/androidpublisher.googleapis.com/overview?project=PROJECT_ID
+   ```
+
+   💡 **如何找到專案 ID？**
+   - 打開 `mobile-android/fastlane/google-play-service-account.json`
+   - 搜尋 `"project_id"` 欄位
+   - 或在 [Google Cloud Console](https://console.cloud.google.com/) 的頂部下拉選單中查看
+
+2. **點擊「Enable」（啟用）按鈕**
+
+3. **等待 2-5 分鐘**讓設定生效
+
+### 驗證
+
+部署時如果看到以下錯誤，表示 API 未啟用或剛啟用尚未生效：
+
+```
+PERMISSION_DENIED: Google Play Android Developer API has not been used in project...
+```
+
+**解決方法：**
+- 確認已點擊「Enable」按鈕
+- 等待 2-5 分鐘後重試
+- 如果剛啟用，可能需要最多 10 分鐘才會完全生效
+
+✅ **完成！** 現在可以開始使用 Google Play 部署功能。
+
+---
+
+## 執行第一次部署測試
+
+### 測試 Firebase App Distribution 部署
+
+```bash
+cd /path/to/botrun-c/mobile-android
+
+# 初始化 rbenv（如果使用 rbenv）
+eval "$(rbenv init - zsh)"
+
+# 執行內部測試部署（Firebase）
+bundle exec fastlane internal_firebase
+```
+
+**預期結果：**
+- ✅ Web 專案建置成功
+- ✅ Android 專案同步成功
+- ✅ APK 建置成功
+- ✅ 上傳到 Firebase App Distribution 成功
+- ✅ 測試人員收到通知 email
+
+**如果失敗：** 參考 [疑難排解](#疑難排解)
+
+### 測試 Google Play 部署（可選）
+
+⚠️ **注意：** Google Play 部署需要先完成「首次手動上傳」（參考 [附錄 D](#附錄-d首次手動上傳到-google-play)）
+
+```bash
+cd /path/to/botrun-c/mobile-android
+
+# 執行 Google Play 內部測試部署
+bundle exec fastlane internal_play
+```
+
+---
+
+## 部署流程
+
+### 🧪 內部測試（Firebase App Distribution）
+
+**使用時機：** 快速分發給內部測試人員，不需要經過 Google Play 審核。
+
+```bash
+cd /path/to/botrun-c/mobile-android
+bundle exec fastlane internal_firebase
+```
+
+**流程：**
+1. 建置 web 專案
+2. 同步到 Android
+3. 建置 Debug APK
+4. 上傳到 Firebase App Distribution
+5. 自動發送通知給測試人員
+
+**測試人員如何取得：**
+- 收到 email 通知
+- 點擊連結下載 APK
+- 安裝測試
+
+### 📦 Google Play 內部測試
+
+**使用時機：** 測試 Google Play 商店的更新流程，需要經過 Google Play 審核（通常數小時）。
+
+```bash
+cd /path/to/botrun-c/mobile-android
+bundle exec fastlane internal_play
+```
+
+**流程：**
+1. 建置 web 專案
+2. 同步到 Android
+3. 建置 Release AAB（已簽署）
+4. 上傳到 Google Play Internal Testing track
+5. 等待 Google Play 審核
+
+**測試人員如何取得：**
+- 需要先被加入 Play Console 的 Internal Testing testers list
+- 使用 Play Store 下載測試版本
+
+### 🚀 正式發佈（Production - 100% 發佈）
+
+**使用時機：** 發佈到 Production，所有用戶立即可見。
+
+```bash
+cd /path/to/botrun-c/mobile-android
+bundle exec fastlane production
+```
+
+**流程：**
+1. 建置 web 專案
+2. 同步到 Android
+3. 建置 Release AAB（已簽署）
+4. 上傳到 Google Play Production track（100% 發佈）
+5. 所有用戶將在數小時內收到更新
+
+**特點（2024/2025 最佳實踐）：**
+- ✅ 使用 `release_status: "completed"` - 直接 100% 發佈
+- ✅ 使用 Google Play App Signing - Google 管理 signing key
+- ✅ 需要先完成「首次手動上傳」（僅需一次）
+
+**首次發佈前必須：**
+- ✅ Keystore 已設定（參考上方章節）
+- ✅ 手動上傳過至少一次 AAB 到 production track
+- ✅ Google Play App Signing 已啟用
+
+---
+
+## 疑難排解
+
+### ❌ 錯誤：找不到 Service Account JSON 檔案
+
+**症狀：**
+```
+No such file or directory @ rb_sysopen - .../firebase-service-account.json
+```
+
+**解決：**
+1. 確認檔案位置正確：
+   ```bash
+   ls -la mobile-android/fastlane/*.json
+   ```
+2. 確認檔案名稱正確（firebase-service-account.json 或 google-play-service-account.json）
+3. 確認 `.env` 檔案中的路徑設定正確
+
+### ❌ 錯誤：Service account does not have permission
+
+**問題：** Service Account 權限不足。
+
+**解決：** 聯絡專案管理員，確認：
+1. **Firebase Service Account** 已加入 "Firebase App Distribution Admin" 角色（在 Google Cloud Console）
+2. **Google Play Service Account** 已在 Play Console 授權（2024+ 版本：透過 "Users and permissions" → "Invite new users"）
+
+**補充：** Service Account 權限可能需要最多 24 小時才會完全生效。如果剛剛才設定，請稍後再試。
+
+### ❌ 錯誤：Android platform has not been added
+
+**解決：**
+```bash
+cd /path/to/botrun-c/mobile-android
+npx cap add android
+```
+
+### ❌ 錯誤：No signing key found
+
+**問題：** 尚未設定 Android 簽署金鑰。
+
+**解決：** 聯絡專案管理員取得 keystore 檔案和設定。
+
+### ❌ Fastlane 找不到 或 Ruby 相關錯誤
+
+**解決：** 參考 [README.md - Ruby 環境問題](./README.md#ruby-環境問題)
+
+### ❌ 執行 fastlane 命令時的常見錯誤
+
+#### 錯誤 1: `parse error near ';&'`
+
+**症狀：**
+```bash
+cd /path && bundle exec fastlane internal_play
+# Error: (eval):1: parse error near `;&'
+```
+
+**原因：** Bash 命令中的 `&&` 符號在某些環境中會導致解析錯誤。
+
+**解決：** 使用分號 `;` 代替 `&&`
+```bash
+cd /Users/seba/Projects/botrun-c/mobile-android; bundle exec fastlane internal_play
+```
+
+#### 錯誤 2: `bundler: command not found: fastlane`
+
+**症狀：**
+```bash
+cd /path; bundle exec fastlane internal_play
+# Error: bundler: command not found: fastlane
+# Your RubyGems version (3.0.3.1) has a bug...
+```
+
+**原因：** Ruby 環境 PATH 未正確設定，Bundler 找不到 fastlane gem。
+
+**解決：** 必須先設定 rbenv PATH 再執行 fastlane
+```bash
+cd /Users/seba/Projects/botrun-c/mobile-android; export PATH="$HOME/.rbenv/shims:$PATH"; bundle exec fastlane internal_play
+```
+
+#### ✅ 正確的執行方式（範本）
+
+**部署到 Google Play Internal Testing:**
+```bash
+cd /Users/seba/Projects/botrun-c/mobile-android; export PATH="$HOME/.rbenv/shims:$PATH"; bundle exec fastlane internal_play
+```
+
+**部署到 Firebase App Distribution:**
+```bash
+cd /Users/seba/Projects/botrun-c/mobile-android; export PATH="$HOME/.rbenv/shims:$PATH"; bundle exec fastlane internal_firebase
+```
+
+**部署到 Google Play Production:**
+```bash
+cd /Users/seba/Projects/botrun-c/mobile-android; export PATH="$HOME/.rbenv/shims:$PATH"; bundle exec fastlane production
+```
+
+**重點：**
+- ✅ 使用 `;` 分隔命令（不要用 `&&`）
+- ✅ 必須先 `export PATH="$HOME/.rbenv/shims:$PATH"` 設定 Ruby 環境
+- ✅ 從 `mobile-android` 目錄執行（不是 `mobile-android/fastlane`）
+
+---
+
+# 附錄：從零開始建立（首次設定參考）
+
+> 💡 **適用對象：** 第一次設定專案，或需要重新建立 Service Accounts 的管理員
+
+---
+
+## 附錄 A：建立 Android 平台
+
+如果專案尚未建立 Android 平台（使用 Capacitor）：
+
+### 1. 進入 mobile-android 目錄
+
+```bash
+cd /path/to/botrun-c/mobile-android
+```
+
+### 2. 新增 Android 平台
+
+```bash
+npx cap add android
+```
+
+這會建立 `android/` 子目錄，包含完整的 Android 專案結構。
+
+### 3. 同步 Web 資源
+
+```bash
+npm run build
+```
+
+這會：
+- 建置 web 專案
+- 將建置結果同步到 Android 專案
+
+### 4. 驗證 Android 專案
+
+```bash
+npx cap open android
+```
+
+這會開啟 Android Studio，確認專案可以正常開啟。
+
+---
+
+## 附錄 B：Firebase Service Account 建立流程
+
+### 1. 取得 Firebase App ID
+
+前往 [Firebase Console](https://console.firebase.google.com/)：
+
+1. 選擇你的專案
+2. 點擊左側齒輪圖示 **⚙️ Project settings**
+3. 往下滾動到 **"Your apps"**
+4. 找到 Android app（package name: `ai.botrun.botrunapp`）
+5. 複製 **App ID**（格式：`1:123456789:android:abcd1234xxxx`）
+6. 將此 App ID 記錄下來，稍後需要填入 `.env` 檔案
+
+### 2. 建立 Firebase Service Account
+
+前往 [Google Cloud Console - Service Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts)：
+
+1. **選擇對應的 Firebase 專案**（確認專案名稱正確）
+2. 點擊 **"+ Create Service Account"**
+3. 填寫資訊：
+   - **Service account name**: `firebase-app-distribution`
+   - **Description**: "Fastlane Firebase App Distribution 部署用"
+4. 點擊 **"Create and Continue"**
+5. 選擇角色：**"Firebase App Distribution Admin"**
+   - 在 "Select a role" 下拉選單中搜尋 "Firebase"
+   - 選擇 **"Firebase App Distribution Admin"**
+6. 點擊 **"Continue"** → **"Done"**
+
+### 3. 下載 Service Account Key
+
+1. 在 Service Accounts 列表中，找到剛建立的 `firebase-app-distribution@xxx.iam.gserviceaccount.com`
+2. 點擊該 Service Account
+3. 切換到 **"Keys"** tab
+4. 點擊 **"Add Key"** → **"Create new key"**
+5. 選擇 **JSON** 格式
+6. 點擊 **"Create"** → JSON 檔案會自動下載
+
+### 4. 移動檔案到專案
+
+```bash
+# 建立目錄（如果不存在）
+mkdir -p mobile-android/fastlane
+
+# 移動並重新命名檔案（替換成你的檔案名稱）
+cp ~/Downloads/你的專案名稱-xxxxx.json mobile-android/fastlane/firebase-service-account.json
+
+# 設定安全權限（只有你可以讀寫）
+chmod 600 mobile-android/fastlane/firebase-service-account.json
+
+# 驗證檔案已被 git ignore
+git check-ignore -v mobile-android/fastlane/firebase-service-account.json
+# 應該顯示：.gitignore:xxx:mobile-android/fastlane/*-service-account.json
+```
+
+✅ **已自動被 .gitignore 排除**
+
+---
+
+## 附錄 C：Google Play Service Account 建立流程
+
+### 1. 建立 Google Play Service Account
+
+前往 [Google Cloud Console - Service Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts)：
+
+1. **確保選擇與 Firebase 相同的專案**
+2. 點擊 **"+ Create Service Account"**
+3. 填寫資訊：
+   - **Service account name**: `google-play-api`
+   - **Description**: "Fastlane Google Play 部署用"
+4. 點擊 **"Create and Continue"**
+5. **跳過角色選擇**（點擊 "Continue"）- 權限稍後在 Play Console 設定
+6. 點擊 **"Done"**
+
+### 2. 下載 Service Account Key
+
+1. 在 Service Accounts 列表中，找到剛建立的 `google-play-api@xxx.iam.gserviceaccount.com`
+2. 點擊該 Service Account
+3. 切換到 **"Keys"** tab
+4. 點擊 **"Add Key"** → **"Create new key"**
+5. 選擇 **JSON** 格式
+6. 點擊 **"Create"** → JSON 檔案會自動下載
+
+### 3. 移動檔案到專案
+
+```bash
+# 移動並重新命名檔案
+cp ~/Downloads/你的專案名稱-xxxxx.json mobile-android/fastlane/google-play-service-account.json
+
+# 設定安全權限
+chmod 600 mobile-android/fastlane/google-play-service-account.json
+
+# 驗證檔案已被 git ignore
+git check-ignore -v mobile-android/fastlane/google-play-service-account.json
+```
+
+### 4. 在 Play Console 授權 Service Account
+
+⚠️ **重要：2024+ 版本更新** - Google Play Console 已改版，不再有 "Settings → API Access" 選項。
+
+前往 [Google Play Console](https://play.google.com/console/)：
+
+#### 步驟 1：取得 Service Account Email
+
+1. 前往 [Google Cloud Console - Service Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts)
+2. 確保選擇正確的專案
+3. 找到剛建立的 `google-play-api` Service Account
+4. **複製完整的 email**（格式：`google-play-api@你的專案ID.iam.gserviceaccount.com`）
+
+#### 步驟 2：在 Play Console 邀請 Service Account
+
+1. 在 Google Play Console 選擇你的開發者帳號
+2. 點擊左側邊欄的 **"Users and permissions"**（使用者和權限）
+3. 點擊右上角的 **"Invite new users"**（邀請新使用者）按鈕
+4. 在 Email address 欄位貼上剛複製的 Service Account email
+
+#### 步驟 3：設定權限
+
+**Account permissions（帳戶權限）tab：**
+- 選擇 **"Admin (all permissions)"**（推薦）
+- 或至少勾選：
+  - ✅ View app information and download bulk reports
+  - ✅ Manage production releases
+  - ✅ Manage testing track releases
+
+**App permissions（應用程式權限）tab：**
+- 點擊 **"Add app"**
+- 選擇你的 app（`Botrun` / package name: `ai.botrun.botrunapp`）
+- 或選擇 **"All apps"**（套用到所有目前和未來的 apps）
+
+#### 步驟 4：發送邀請
+
+1. 點擊 **"Invite user"**
+2. 點擊 **"Send invitation"**
+
+✅ **完成！** Service Account 現在有權限透過 API 上傳 APK/AAB 到 Google Play。
+
+⏱️ **注意：** Service Account 權限可能需要最多 24 小時才會完全生效。通常幾分鐘內就可以使用，但如果遇到權限錯誤，請稍後再試。
+
+### 5. 啟用 Google Play Android Developer API
+
+⚠️ **重要：** 必須啟用此 API，否則無法透過 Fastlane 上傳到 Google Play。
+
+1. **取得專案 ID：**
+   - 打開剛下載的 `google-play-service-account.json`
+   - 搜尋 `"project_id"` 欄位並複製值
+
+2. **前往 API 啟用頁面：**
+   ```
+   https://console.developers.google.com/apis/api/androidpublisher.googleapis.com/overview?project=你的專案ID
+   ```
+   （替換 `你的專案ID` 為上一步複製的值）
+
+3. **點擊「Enable」（啟用）按鈕**
+
+4. **等待 2-5 分鐘**讓設定生效
+
+**常見錯誤：**
+```
+PERMISSION_DENIED: Google Play Android Developer API has not been used in project...
+```
+- **原因：** API 未啟用或剛啟用尚未生效
+- **解決：** 確認已啟用，等待 2-5 分鐘後重試
+
+✅ **Service Account 設定完成！** 現在可以使用 Fastlane 自動部署到 Google Play。
+
+---
+
+## 附錄 D：首次手動上傳到 Google Play
+
+⚠️ **重要：** 在使用 Fastlane API 上傳到 Google Play 之前，**必須先手動上傳一次 APK/AAB** 到 Internal Testing track。
+
+### 為什麼需要首次手動上傳？
+
+Google Play API 要求 app 必須先有至少一個手動上傳的版本，才能使用 API 進行後續的自動化上傳。
+
+### 步驟
+
+#### 1. 建置 Release AAB
+
+```bash
+cd /path/to/botrun-c/mobile-android
+
+# 建置 web 專案
+npm run build
+
+# 進入 Android 專案
+cd android
+
+# 建置 release AAB
+./gradlew bundleRelease
+
+# AAB 檔案位置
+ls -la app/build/outputs/bundle/release/app-release.aab
+```
+
+#### 2. 在 Play Console 手動上傳
+
+1. 前往 [Google Play Console](https://play.google.com/console/)
+2. 選擇你的 app
+3. 導航到 **"Release"** → **"Testing"** → **"Internal testing"**
+4. 點擊 **"Create new release"**
+5. 上傳 AAB 檔案：
+   - 拖曳或選擇 `app/build/outputs/bundle/release/app-release.aab`
+6. 填寫 **Release notes**（例如：`Initial release for testing`）
+7. 點擊 **"Save"**
+8. 點擊 **"Review release"**
+9. 確認無誤後，點擊 **"Start rollout to Internal testing"**
+
+#### 3. 等待審核
+
+- Google Play 審核通常需要數小時
+- 審核通過後，可以開始使用 Fastlane 自動化部署
+
+✅ **完成！** 之後就可以使用 `bundle exec fastlane internal_play` 進行自動化部署。
+
+---
+
+## 參考資源
+
+- [Fastlane 官方文件](https://docs.fastlane.tools/)
+- [Firebase App Distribution](https://firebase.google.com/docs/app-distribution)
+- [Google Play Console API](https://developers.google.com/android-publisher)
+- [Capacitor Android](https://capacitorjs.com/docs/android)