botrun-horse 2.29.2 → 2.30.0

package/botrun-c/fastlane/RUBY-SETUP.md

@@ -0,0 +1,449 @@
+# Ruby 環境設定指南
+
+本指南適用於 macOS 開發者，設定 Ruby 和 rbenv 環境以使用 Fastlane。
+
+**適用範圍：** Android 和 iOS 開發（共用）
+
+---
+
+## 📋 為什麼需要 rbenv？
+
+### ❌ 不使用系統 Ruby 的原因
+
+macOS 預裝的 Ruby（通常是 2.6.x）有以下問題：
+
+1. **權限問題** - 需要 `sudo` 安裝 gems，有安全風險
+2. **版本過舊** - 無法使用新功能
+3. **無法版本控制** - 所有專案共用同一版本
+4. **macOS 更新可能破壞設定**
+5. **與 CI/CD 環境不一致**
+
+### ✅ rbenv 的優勢
+
+> **Fastlane 官方明確指出：**
+> "If you use macOS, system Ruby is not recommended."
+> "rbenv is one of the most popular ways to manage your Ruby environment."
+
+**優點：**
+- ✅ 專案隔離（每個專案可以用不同 Ruby 版本）
+- ✅ 不需要 sudo
+- ✅ 團隊成員環境一致
+- ✅ CI/CD 友善
+- ✅ 業界標準
+
+---
+
+## 🚀 設定步驟
+
+### 步驟 1：檢查目前的 Ruby
+
+```bash
+# 檢查 Ruby 版本
+ruby --version
+
+# 檢查 Ruby 路徑
+which ruby
+```
+
+**如果顯示 `/usr/bin/ruby`**，代表使用系統 Ruby，需要安裝 rbenv。
+
+---
+
+### 步驟 2：安裝 rbenv（使用 Homebrew）
+
+#### 2.1 確認 Homebrew 已安裝
+
+```bash
+brew --version
+```
+
+如果沒有安裝 Homebrew，先執行：
+```bash
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+```
+
+#### 2.2 安裝 rbenv 和 ruby-build
+
+```bash
+brew install rbenv ruby-build
+```
+
+**說明：**
+- `rbenv` - Ruby 版本管理器
+- `ruby-build` - rbenv 的 plugin，用於安裝 Ruby
+
+---
+
+### 步驟 3：設定 Shell 環境
+
+#### 3.1 初始化 rbenv
+
+```bash
+rbenv init
+```
+
+你會看到類似這樣的輸出：
+```
+# Load rbenv automatically by appending
+# the following to ~/.zshrc:
+
+eval "$(rbenv init - zsh)"
+```
+
+#### 3.2 加入 rbenv 到 shell profile
+
+**對於 zsh（macOS 預設）：**
+
+```bash
+echo 'eval "$(rbenv init - zsh)"' >> ~/.zshrc
+```
+
+**對於 bash：**
+
+```bash
+echo 'eval "$(rbenv init - bash)"' >> ~/.bashrc
+```
+
+#### 3.3 重新載入 shell
+
+```bash
+# 方法 1：重新載入 profile
+source ~/.zshrc
+
+# 方法 2：重新啟動 terminal
+# 關閉並重新打開 Terminal
+```
+
+#### 3.4 驗證 rbenv 安裝
+
+```bash
+# 檢查 rbenv 是否正確設定
+curl -fsSL https://github.com/rbenv/rbenv-installer/raw/main/bin/rbenv-doctor | bash
+```
+
+應該看到：
+```
+Checking for `rbenv' in PATH: /usr/local/bin/rbenv
+Checking for rbenv shims in PATH: OK
+Checking `rbenv install' support: OK
+Counting installed Ruby versions: none
+  There aren't any Ruby versions installed under `~/.rbenv/versions'.
+```
+
+---
+
+### 步驟 4：安裝 Ruby
+
+#### 4.1 查看可用的 Ruby 版本
+
+```bash
+rbenv install --list | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | tail -10
+```
+
+#### 4.2 安裝 Ruby 3.3.0（推薦）
+
+```bash
+rbenv install 3.3.0
+```
+
+**⏱️ 注意：** 這會花費 10-15 分鐘，因為要從原始碼編譯。
+
+**編譯過程中你會看到：**
+```
+Downloading ruby-3.3.0.tar.gz...
+-> https://cache.ruby-lang.org/pub/ruby/3.3/ruby-3.3.0.tar.gz
+Installing ruby-3.3.0...
+```
+
+#### 4.3 設定全域 Ruby 版本
+
+```bash
+rbenv global 3.3.0
+```
+
+**說明：** 這會將 Ruby 3.3.0 設定為系統預設版本。
+
+#### 4.4 驗證 Ruby 安裝
+
+```bash
+# 檢查版本
+ruby --version
+# 應該顯示：ruby 3.3.0 (...)
+
+# 檢查路徑
+which ruby
+# 應該顯示：/Users/你的使用者名稱/.rbenv/shims/ruby
+
+# 檢查 gem 路徑
+gem env home
+# 應該顯示：/Users/你的使用者名稱/.rbenv/versions/3.3.0/lib/ruby/gems/3.3.0
+```
+
+**✅ 如果都正確，Ruby 安裝成功！**
+
+---
+
+### 步驟 5：設定專案的 Ruby 版本
+
+#### 5.1 在專案根目錄建立 `.ruby-version`
+
+```bash
+cd /Users/seba/Projects/botrun-c
+echo "3.3.0" > .ruby-version
+```
+
+**作用：** 當你進入這個專案目錄時，rbenv 會自動切換到 Ruby 3.3.0。
+
+#### 5.2 驗證專案 Ruby 版本
+
+```bash
+cd /Users/seba/Projects/botrun-c
+ruby --version
+# 應該顯示：ruby 3.3.0
+```
+
+---
+
+### 步驟 6：安裝 Bundler
+
+```bash
+gem install bundler
+```
+
+**驗證：**
+```bash
+bundle --version
+# 應該顯示：Bundler version 2.x.x
+```
+
+---
+
+### 步驟 7：安裝 Fastlane（透過 Bundler）
+
+#### 7.1 確認 Gemfile 存在
+
+```bash
+cd /Users/seba/Projects/botrun-c
+cat Gemfile
+```
+
+應該包含：
+```ruby
+source "https://rubygems.org"
+gem "fastlane"
+```
+
+#### 7.2 安裝 gems
+
+```bash
+bundle install
+```
+
+**⏱️ 預計時間：** 2-3 分鐘
+
+#### 7.3 驗證 Fastlane 安裝
+
+```bash
+bundle exec fastlane --version
+```
+
+應該看到 Fastlane 的版本資訊。
+
+---
+
+## ✅ 設定完成檢查清單
+
+- [ ] rbenv 已安裝並初始化
+- [ ] `which ruby` 顯示 `.rbenv/shims/ruby`
+- [ ] `ruby --version` 顯示 `3.3.0`
+- [ ] `.ruby-version` 檔案已建立
+- [ ] Bundler 已安裝
+- [ ] `bundle install` 執行成功
+- [ ] `bundle exec fastlane --version` 可以執行
+
+**全部打勾？** 恭喜！你可以繼續 [Android 部署設定](./ANDROID-DEPLOYMENT-SETUP.md)
+
+---
+
+## 🛠️ 疑難排解
+
+### ❌ `rbenv: command not found`
+
+**原因：** rbenv 未正確加入 PATH。
+
+**解決：**
+```bash
+# 確認 ~/.zshrc 包含以下內容
+echo 'eval "$(rbenv init - zsh)"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+---
+
+### ❌ `ruby --version` 仍顯示系統 Ruby
+
+**原因：** shell 尚未重新載入。
+
+**解決：**
+```bash
+# 方法 1：重新載入
+source ~/.zshrc
+
+# 方法 2：重新啟動 Terminal
+
+# 方法 3：強制 rehash
+rbenv rehash
+```
+
+---
+
+### ❌ 安裝 Ruby 時出現編譯錯誤
+
+**可能原因：** 缺少必要的編譯工具。
+
+**解決：**
+```bash
+# 安裝 Xcode Command Line Tools
+xcode-select --install
+
+# 重新安裝 Ruby
+rbenv install 3.3.0
+```
+
+---
+
+### ❌ `bundle install` 失敗
+
+**錯誤範例：**
+```
+You don't have write permissions for the /Library/Ruby/Gems/2.6.0 directory
+```
+
+**原因：** 仍在使用系統 Ruby。
+
+**解決：**
+```bash
+# 確認使用 rbenv Ruby
+which ruby
+# 應該顯示 .rbenv/shims/ruby
+
+# 如果不是，重新載入 shell
+source ~/.zshrc
+ruby --version
+```
+
+---
+
+### ❌ 安裝 Ruby 非常慢
+
+**原因：** 從原始碼編譯需要時間（10-15 分鐘）。
+
+**這是正常的！** 請耐心等待。你會看到：
+```
+Installing ruby-3.3.0...
+Installed ruby-3.3.0 to /Users/你的使用者名稱/.rbenv/versions/3.3.0
+```
+
+---
+
+## 📚 常用指令參考
+
+### rbenv 指令
+
+```bash
+# 列出所有已安裝的 Ruby 版本
+rbenv versions
+
+# 列出可安裝的 Ruby 版本
+rbenv install --list
+
+# 安裝特定版本
+rbenv install 3.3.0
+
+# 解除安裝特定版本
+rbenv uninstall 3.3.0
+
+# 設定全域 Ruby 版本
+rbenv global 3.3.0
+
+# 設定當前目錄的 Ruby 版本
+rbenv local 3.3.0
+
+# 重新載入 shims
+rbenv rehash
+```
+
+### Bundler 指令
+
+```bash
+# 安裝 Gemfile 中的所有 gems
+bundle install
+
+# 更新 gems
+bundle update
+
+# 執行特定版本的 gem
+bundle exec [command]
+
+# 檢查 Bundler 版本
+bundle --version
+```
+
+---
+
+## 🔄 更新 Ruby 版本
+
+### 未來要升級 Ruby？
+
+```bash
+# 1. 安裝新版本
+rbenv install 3.4.0
+
+# 2. 更新專案設定
+cd /Users/seba/Projects/botrun-c
+echo "3.4.0" > .ruby-version
+
+# 3. 重新安裝 gems
+bundle install
+
+# 4. 驗證
+ruby --version
+bundle exec fastlane --version
+```
+
+---
+
+## 👥 團隊協作
+
+### 新同事加入團隊
+
+請他們按照本文件步驟 1-7 設定環境。
+
+**關鍵檔案（需要 commit 到 git）：**
+- `.ruby-version` - 確保團隊使用相同 Ruby 版本
+- `Gemfile` - 定義 gem 相依性
+- `Gemfile.lock` - 鎖定 gem 版本
+
+### CI/CD 環境
+
+在 GitHub Actions / Cloud Build 中使用相同的 Ruby 版本：
+
+```yaml
+# GitHub Actions 範例
+- uses: ruby/setup-ruby@v1
+  with:
+    ruby-version: '3.3.0'
+    bundler-cache: true
+```
+
+---
+
+## 🔗 相關資源
+
+- [rbenv 官方文件](https://github.com/rbenv/rbenv)
+- [Fastlane 安裝指南](https://docs.fastlane.tools/getting-started/ios/setup/)
+- [Bundler 官方文件](https://bundler.io/)
+
+---
+
+**下一步：** 繼續 [Android 部署設定](./ANDROID-DEPLOYMENT-SETUP.md) 或返回 [總覽](./README.md)

package/botrun-c/fastlane/android/Appfile

@@ -0,0 +1,11 @@
+# Appfile for Botrun Android
+# 定義 Android app 的基本資訊
+
+# Google Play Console API 的 Service Account JSON key
+json_key_file("../../mobile-android/fastlane/google-play-service-account.json")
+
+# Android app 的 package name
+package_name("ai.botrun.botrunapp")
+
+# 可選：指定 Firebase App ID（也可以在 .env 設定）
+# firebase_app_id("1:123456789:android:abcd1234")

package/botrun-c/fastlane/android/Fastfile

@@ -0,0 +1,240 @@
+# Fastfile for Botrun Android Deployment
+# 自動化 Android 部署流程
+
+default_platform(:android)
+
+# 載入環境變數
+import_from_git(
+  url: "https://github.com/fastlane/fastlane",
+  path: ".env"
+)
+
+platform :android do
+  # === 前置作業 ===
+
+  before_all do
+    # 確認環境變數
+    ensure_env_vars(
+      env_vars: ["FIREBASE_APP_ID", "ANDROID_PROJECT_PATH"]
+    )
+  end
+
+  # === 輔助 Lane ===
+
+  # 建置 Web 專案並同步到 Android
+  lane :build_web do
+    Dir.chdir("../../web") do
+      sh("npm run build")
+    end
+    UI.success("✅ Web 專案建置完成")
+  end
+
+  # 同步 Capacitor
+  lane :sync_capacitor do
+    Dir.chdir("../../mobile-android") do
+      sh("npx cap sync android")
+    end
+    UI.success("✅ Capacitor 同步完成")
+  end
+
+  # 建置 Debug APK（用於 Firebase App Distribution）
+  lane :build_debug_apk do
+    Dir.chdir(ENV["ANDROID_PROJECT_PATH"]) do
+      gradle(
+        task: "clean assembleDebug",
+        project_dir: "."
+      )
+    end
+    UI.success("✅ Debug APK 建置完成")
+  end
+
+  # 建置 Release AAB（用於 Google Play）
+  lane :build_release_aab do
+    Dir.chdir(ENV["ANDROID_PROJECT_PATH"]) do
+      gradle(
+        task: "clean bundleRelease",
+        project_dir: "."
+      )
+    end
+    UI.success("✅ Release AAB 建置完成")
+  end
+
+  # === 主要部署 Lane ===
+
+  # 🧪 內部測試 - Firebase App Distribution
+  desc "部署到 Firebase App Distribution（內部快速測試）"
+  lane :internal_firebase do
+    UI.header("🧪 開始 Firebase App Distribution 部署流程")
+
+    # 1. 建置 Web
+    build_web
+
+    # 2. 同步 Capacitor
+    sync_capacitor
+
+    # 3. 建置 Debug APK
+    build_debug_apk
+
+    # 4. 上傳到 Firebase
+    firebase_app_distribution(
+      app: ENV["FIREBASE_APP_ID"],
+      android_artifact_type: "APK",
+      android_artifact_path: "#{ENV['ANDROID_PROJECT_PATH']}/app/build/outputs/apk/debug/app-debug.apk",
+      service_credentials_file: ENV["FIREBASE_SERVICE_ACCOUNT"],
+      groups: "internal-testers",  # 你可以在 Firebase Console 建立 tester groups
+      release_notes: "🔧 Internal build for testing\n\n#{changelog_from_git_commits(commits_count: 5, pretty: '- %s')}",
+      debug: true
+    )
+
+    UI.success("✅ Firebase App Distribution 部署完成！")
+    UI.important("📱 測試人員將收到 email 通知")
+  end
+
+  # 📦 Google Play 內部測試
+  desc "部署到 Google Play Internal Testing track"
+  lane :internal_play do
+    UI.header("📦 開始 Google Play Internal Testing 部署流程")
+
+    # 1. 建置 Web
+    build_web
+
+    # 2. 同步 Capacitor
+    sync_capacitor
+
+    # 3. 建置 Release AAB
+    build_release_aab
+
+    # 4. 上傳到 Google Play Internal Testing
+    upload_to_play_store(
+      track: "internal",
+      release_status: "completed",
+      aab: "#{ENV['ANDROID_PROJECT_PATH']}/app/build/outputs/bundle/release/app-release.aab",
+      json_key: ENV["GOOGLE_PLAY_SERVICE_ACCOUNT"],
+      skip_upload_metadata: true,
+      skip_upload_images: true,
+      skip_upload_screenshots: true
+    )
+
+    UI.success("✅ Google Play Internal Testing 部署完成！")
+    UI.important("⏳ 等待 Google Play 審核（通常數小時）")
+  end
+
+  # 🚀 正式發佈 - Production
+  desc "部署到 Google Play Production track"
+  lane :production do
+    UI.header("🚀 開始 Production 部署流程")
+
+    # 安全確認
+    answer = UI.confirm("⚠️  你確定要發佈到 Production 嗎？這將影響所有用戶。")
+    UI.user_error!("❌ 取消 Production 部署") unless answer
+
+    # 1. 建置 Web
+    build_web
+
+    # 2. 同步 Capacitor
+    sync_capacitor
+
+    # 3. 建置 Release AAB
+    build_release_aab
+
+    # 4. 上傳到 Google Play Production（分階段發佈）
+    upload_to_play_store(
+      track: "production",
+      release_status: "inProgress",  # 分階段發佈
+      rollout: "0.1",  # 10% rollout
+      aab: "#{ENV['ANDROID_PROJECT_PATH']}/app/build/outputs/bundle/release/app-release.aab",
+      json_key: ENV["GOOGLE_PLAY_SERVICE_ACCOUNT"],
+      skip_upload_metadata: true,
+      skip_upload_images: true,
+      skip_upload_screenshots: true
+    )
+
+    UI.success("✅ Production 部署完成（10% rollout）！")
+    UI.important("📊 監控數據後，使用 `fastlane promote_production` 增加 rollout")
+  end
+
+  # === 進階 Lane ===
+
+  # 增加 Production rollout 比例
+  desc "增加 Production rollout 比例"
+  lane :promote_production do |options|
+    rollout_percentage = options[:percentage] || 0.5  # 預設 50%
+
+    UI.header("📈 增加 Production rollout 到 #{rollout_percentage * 100}%")
+
+    upload_to_play_store(
+      track: "production",
+      rollout: rollout_percentage.to_s,
+      skip_upload_apk: true,
+      skip_upload_aab: true,
+      skip_upload_metadata: true,
+      skip_upload_images: true,
+      skip_upload_screenshots: true,
+      json_key: ENV["GOOGLE_PLAY_SERVICE_ACCOUNT"]
+    )
+
+    UI.success("✅ Production rollout 已更新到 #{rollout_percentage * 100}%")
+  end
+
+  # 完成 Production rollout（100%）
+  desc "完成 Production rollout 到 100%"
+  lane :complete_rollout do
+    UI.header("🎯 完成 Production rollout 到 100%")
+
+    upload_to_play_store(
+      track: "production",
+      rollout: "1.0",
+      skip_upload_apk: true,
+      skip_upload_aab: true,
+      skip_upload_metadata: true,
+      skip_upload_images: true,
+      skip_upload_screenshots: true,
+      json_key: ENV["GOOGLE_PLAY_SERVICE_ACCOUNT"]
+    )
+
+    UI.success("✅ Production rollout 完成！現在 100% 用戶可以看到更新")
+  end
+
+  # 新增測試人員到 Firebase
+  desc "新增測試人員到 Firebase App Distribution"
+  lane :add_testers do |options|
+    emails = options[:emails] || UI.input("請輸入 email（逗號分隔）：")
+
+    firebase_app_distribution_add_testers(
+      app: ENV["FIREBASE_APP_ID"],
+      emails: emails,
+      service_credentials_file: ENV["FIREBASE_SERVICE_ACCOUNT"]
+    )
+
+    UI.success("✅ 測試人員已新增到 Firebase App Distribution")
+  end
+
+  # 取得最新 Firebase 發佈資訊
+  desc "取得最新 Firebase App Distribution 發佈資訊"
+  lane :latest_firebase_release do
+    release = firebase_app_distribution_get_latest_release(
+      app: ENV["FIREBASE_APP_ID"],
+      service_credentials_file: ENV["FIREBASE_SERVICE_ACCOUNT"]
+    )
+
+    UI.message("📱 最新 Firebase 發佈：")
+    UI.message("   版本：#{release[:displayVersion]}")
+    UI.message("   建置：#{release[:buildVersion]}")
+    UI.message("   發佈時間：#{release[:createTime]}")
+  end
+
+  # === 錯誤處理 ===
+
+  after_all do |lane|
+    # 成功後的清理工作
+    UI.success("🎉 Lane '#{lane}' 執行成功！")
+  end
+
+  error do |lane, exception|
+    # 失敗後的處理
+    UI.error("❌ Lane '#{lane}' 執行失敗")
+    UI.error("錯誤訊息：#{exception.message}")
+
+    # 可以在這裡加入通知（Slack, Discord 等）
+  end
+end