botrun-horse 2.29.2 → 2.30.0

package/botrun-c/fastlane/README.md

@@ -0,0 +1,424 @@
+# Fastlane 自動化部署系統
+
+Botrun 專案的自動化建置和部署系統，支援 Android 和 iOS。
+
+---
+
+## 🚀 快速開始
+
+### 第一次使用？
+
+按照以下順序完成設定：
+
+1. **設定 Ruby 環境**（Android 和 iOS 共用）
+   - 📖 參考下方 [Ruby 環境設定](#-ruby-環境設定共用)
+   - ⏱️ 預計時間：15-20 分鐘
+
+2. **設定部署平台**
+   - 📖 [Android 部署設定](./ANDROID-DEPLOYMENT-SETUP.md) - Firebase + Google Play
+   - 📖 [iOS 部署設定](./IOS-DEPLOYMENT-SETUP.md) - Firebase + TestFlight + App Store
+   - ⏱️ 預計時間：30-60 分鐘
+
+3. **開始部署！**
+   - 📖 [快速部署指令](./QUICK-START.md)
+
+### 已經設定好了？
+
+直接使用 [快速部署指令](./QUICK-START.md)
+
+---
+
+## 📚 文件導航
+
+| 文件 | 說明 | 適用對象 |
+|------|------|----------|
+| **共用設定** |
+| [RUBY-SETUP.md](./RUBY-SETUP.md) | Ruby 環境詳細設定指南 | 所有開發者（詳細版） |
+| **平台特定設定** |
+| [ANDROID-DEPLOYMENT-SETUP.md](./ANDROID-DEPLOYMENT-SETUP.md) | Android 部署完整設定 | Android 開發者 |
+| [IOS-DEPLOYMENT-SETUP.md](./IOS-DEPLOYMENT-SETUP.md) | iOS 部署完整設定 | iOS 開發者 |
+| **快速參考** |
+| [QUICK-START.md](./QUICK-START.md) | 常用部署指令 | 所有人 |
+
+---
+
+## 🛠️ Ruby 環境設定（共用）
+
+Fastlane 需要 Ruby 環境。本專案使用 **Ruby 3.3.0**。
+
+### macOS / Linux 環境
+
+#### 1. 安裝 rbenv（Ruby 版本管理器）
+
+```bash
+# macOS
+brew install rbenv ruby-build
+
+# 初始化 rbenv（加入到 ~/.zshrc 或 ~/.bashrc）
+echo 'eval "$(rbenv init - zsh)"' >> ~/.zshrc
+
+# 重新載入 shell
+exec zsh -l
+```
+
+#### 2. 安裝 Ruby 3.3.0
+
+```bash
+# 安裝 Ruby 3.3.0（需要 10-15 分鐘）
+rbenv install 3.3.0
+
+# 設為全域版本
+rbenv global 3.3.0
+
+# 驗證
+ruby --version   # 應顯示：ruby 3.3.0
+which ruby       # 應顯示：~/.rbenv/shims/ruby
+```
+
+#### 3. 安裝 Bundler 和 Fastlane
+
+```bash
+# 進入專案目錄
+cd /path/to/botrun-c
+
+# 安裝 Bundler
+gem install bundler
+
+# 安裝 Fastlane 和相依套件
+bundle install
+
+# 驗證
+bundle exec fastlane --version
+```
+
+#### 疑難排解
+
+**問題：gem 指令權限錯誤**
+```bash
+# 解決：確保使用 rbenv 的 Ruby
+exec zsh -l
+gem install bundler
+```
+
+**問題：找不到 rbenv**
+```bash
+# 確認 rbenv 初始化
+which rbenv  # 應顯示 rbenv 路徑
+rbenv init   # 檢查是否正確設定
+```
+
+### Windows 環境
+
+#### 1. 安裝 RubyInstaller
+
+1. 前往 [RubyInstaller 官網](https://rubyinstaller.org/)
+2. 下載 **Ruby 3.3.0 (x64) with DevKit**
+3. 執行安裝程式（確保勾選 "Add Ruby to PATH"）
+4. 安裝完成後，開啟 PowerShell 或 CMD
+
+#### 2. 驗證安裝
+
+```powershell
+# 確認 Ruby 版本
+ruby --version   # 應顯示：ruby 3.3.0
+
+# 確認 gem 可用
+gem --version
+```
+
+#### 3. 安裝 Bundler 和 Fastlane
+
+```powershell
+# 進入專案目錄
+cd C:\path\to\botrun-c
+
+# 安裝 Bundler
+gem install bundler
+
+# 安裝 Fastlane 和相依套件
+bundle install
+
+# 驗證
+bundle exec fastlane --version
+```
+
+### 完成檢查清單
+
+確認以下指令都可以正常執行：
+
+```bash
+ruby --version         # ✅ ruby 3.3.0
+bundle --version       # ✅ Bundler version 2.x
+bundle exec fastlane --version  # ✅ fastlane 2.x
+cat .ruby-version      # ✅ 3.3.0
+```
+
+---
+
+## 🎯 支援的部署方式
+
+### Android
+
+- **🧪 內部測試**：Firebase App Distribution
+  ```bash
+  cd mobile-android
+  bundle exec fastlane internal_firebase
+  ```
+
+- **📦 Google Play 內部測試**
+  ```bash
+  cd mobile-android
+  bundle exec fastlane internal_play
+  ```
+
+- **🚀 正式發佈**
+  ```bash
+  cd mobile-android
+  bundle exec fastlane production
+  ```
+
+詳見 [Android 部署設定指南](./ANDROID-DEPLOYMENT-SETUP.md)
+
+### iOS
+
+- **🔨 本地測試建置**
+  ```bash
+  cd mobile-ios
+  bundle exec fastlane build_local
+  ```
+
+- **🧪 內部測試**：Firebase App Distribution
+  ```bash
+  cd mobile-ios
+  bundle exec fastlane internal_firebase
+  ```
+
+- **📦 TestFlight 內部測試**
+  ```bash
+  cd mobile-ios
+  bundle exec fastlane internal_testflight
+  ```
+
+- **🚀 正式發佈**
+  ```bash
+  cd mobile-ios
+  bundle exec fastlane production
+  ```
+
+詳見 [iOS 部署設定指南](./IOS-DEPLOYMENT-SETUP.md)
+
+---
+
+## 📂 目錄結構
+
+```
+botrun-c/                              # 專案根目錄
+├── .ruby-version                      # ⭐ Ruby 版本指定（3.3.0）- 要上 git
+├── Gemfile                            # Ruby gems 定義 - 要上 git
+├── Gemfile.lock                       # Gems 版本鎖定 - 要上 git
+├── mobile-android/                    # Android 專案
+│   └── fastlane/
+│       ├── Fastfile                   # Android 部署 lanes - 要上 git
+│       ├── .env.template              # 環境變數範本 - 要上 git
+│       ├── .env                       # 環境變數（機密）- 不要上 git
+│       ├── firebase-service-account.json  # Firebase 憑證（機密）- 不要上 git
+│       └── google-play-service-account.json  # Google Play 憑證（機密）- 不要上 git
+├── mobile-ios/                        # iOS 專案
+│   └── fastlane/
+│       ├── Fastfile                   # iOS 部署 lanes - 要上 git
+│       ├── .env.template              # 環境變數範本 - 要上 git
+│       ├── .env                       # 環境變數（機密）- 不要上 git
+│       ├── AuthKey_*.p8               # App Store Connect API Key（機密）- 不要上 git
+│       └── firebase-service-account.json  # Firebase 憑證（機密）- 不要上 git
+└── fastlane/
+    ├── README.md                      # 本檔案（共用入口）
+    ├── RUBY-SETUP.md                  # Ruby 詳細設定指南
+    ├── ANDROID-DEPLOYMENT-SETUP.md    # Android 完整設定
+    ├── IOS-DEPLOYMENT-SETUP.md        # iOS 完整設定
+    ├── QUICK-START.md                 # 快速指令參考
+    └── Pluginfile                     # ⭐ Fastlane plugins 定義 - 要上 git
+```
+
+### ⭐ 重要檔案說明
+
+**`.ruby-version`** - Ruby 版本控制
+- 📍 位置：專案根目錄
+- 🔒 版本：`3.3.0`
+- ✅ **必須 commit 到 git**
+- 🎯 作用：確保團隊成員使用相同 Ruby 版本
+- 💡 rbenv/RubyInstaller 會自動偵測此版本
+
+**`Gemfile` / `Gemfile.lock`** - Ruby gems 管理
+- 📍 位置：專案根目錄
+- ✅ **必須 commit 到 git**
+- 🎯 作用：定義和鎖定 Fastlane 及相依套件版本
+
+**`fastlane/Pluginfile`** - Fastlane Plugins 定義
+- 📍 位置：fastlane 目錄下
+- ✅ **必須 commit 到 git**
+- 🎯 作用：定義使用的 Fastlane plugins（如 firebase_app_distribution）
+
+---
+
+## 🌍 跨平台注意事項
+
+### Ruby 版本管理工具
+
+| 平台 | 推薦工具 | 支援狀態 |
+|------|---------|---------|
+| macOS | rbenv | ✅ 完整支援 |
+| Linux | rbenv | ✅ 完整支援 |
+| Windows | RubyInstaller | ✅ 支援 |
+| Windows (WSL) | rbenv | ✅ 支援 |
+
+### 跨平台共用檔案
+
+以下檔案在所有平台都適用，**必須 commit 到 git**：
+
+- ✅ `.ruby-version` - 確保所有人使用 Ruby 3.3.0
+- ✅ `Gemfile` / `Gemfile.lock` - 確保相依套件版本一致
+- ✅ `fastlane/Pluginfile` - Fastlane plugins 定義
+
+### 常見平台差異
+
+**路徑表示：**
+- macOS/Linux: `/Users/seba/Projects/botrun-c`
+- Windows: `C:\Users\seba\Projects\botrun-c`
+- Ruby 程式碼中建議使用正斜線 `/`（跨平台）
+
+**Shell 環境：**
+- macOS/Linux: bash / zsh
+- Windows: PowerShell / CMD
+
+**環境變數：**
+- macOS/Linux: `export VAR_NAME=value`
+- Windows PowerShell: `$env:VAR_NAME = "value"`
+
+---
+
+## 👥 團隊協作
+
+### 新同事加入？
+
+1. **設定 Ruby 環境**
+   - macOS/Linux: 按照本文 [Ruby 環境設定](#-ruby-環境設定共用)
+   - Windows: 使用 RubyInstaller
+   - 詳細疑難排解：參考 [RUBY-SETUP.md](./RUBY-SETUP.md)
+
+2. **安裝專案相依套件**
+   ```bash
+   cd /path/to/botrun-c
+   bundle install
+   ```
+
+3. **設定部署平台**
+   - Android: 參考 [ANDROID-DEPLOYMENT-SETUP.md](./ANDROID-DEPLOYMENT-SETUP.md)
+   - iOS: 參考 [IOS-DEPLOYMENT-SETUP.md](./IOS-DEPLOYMENT-SETUP.md)
+
+4. **取得存取權限**
+   - Firebase 專案存取權
+   - Google Play Console 存取權
+   - Apple Developer 存取權（iOS）
+
+### 更新部署設定？
+
+當修改 Fastlane 設定時：
+
+1. 修改對應的 Fastfile（如 `fastlane/android/Fastfile`）
+2. 本地測試確認無誤
+3. Commit 變更到 git
+4. 通知團隊成員執行：
+   ```bash
+   git pull
+   bundle install  # 如果有更新 Gemfile
+   ```
+
+### 更新 Ruby 版本？
+
+當需要升級 Ruby 版本時：
+
+1. 更新 `.ruby-version` 檔案
+2. 更新 `Gemfile`（如果需要）
+3. 本地測試：
+   ```bash
+   rbenv install <new-version>
+   rbenv global <new-version>
+   bundle install
+   ```
+4. 確認所有 lanes 都能正常執行
+5. Commit 變更並通知團隊
+
+---
+
+## ⚡ 常見任務
+
+### 部署新版本到內部測試
+
+```bash
+cd /path/to/botrun-c/mobile-android
+bundle exec fastlane internal_firebase
+```
+
+### 新增測試人員
+
+```bash
+cd /path/to/botrun-c/mobile-android
+bundle exec fastlane add_testers emails:"test@example.com"
+```
+
+### 查看最新發佈
+
+```bash
+cd /path/to/botrun-c/mobile-android
+bundle exec fastlane latest_firebase_release
+```
+
+更多指令參考 [QUICK-START.md](./QUICK-START.md)
+
+---
+
+## 🆘 遇到問題？
+
+### Ruby 環境問題
+
+**快速檢查：**
+```bash
+ruby --version        # 確認版本是 3.3.0
+which ruby           # macOS/Linux: 應指向 rbenv
+bundle --version     # 確認 Bundler 已安裝
+```
+
+**常見問題：**
+- gem 指令權限錯誤 → 確保使用 rbenv/RubyInstaller 的 Ruby
+- 找不到 fastlane → 執行 `bundle install`
+- rbenv 無效 → 確認 shell 配置檔已加入 `eval "$(rbenv init - zsh)"`
+
+詳細疑難排解：[RUBY-SETUP.md](./RUBY-SETUP.md#疑難排解)
+
+### 部署問題
+
+- **Android 部署問題** → [ANDROID-DEPLOYMENT-SETUP.md](./ANDROID-DEPLOYMENT-SETUP.md#疑難排解)
+- **iOS 部署問題** → [IOS-DEPLOYMENT-SETUP.md](./IOS-DEPLOYMENT-SETUP.md#疑難排解)
+- **找不到指令** → [QUICK-START.md](./QUICK-START.md)
+
+---
+
+## 🔗 相關資源
+
+- [Fastlane 官方文件](https://docs.fastlane.tools/)
+- [Firebase App Distribution](https://firebase.google.com/docs/app-distribution)
+- **Android:**
+  - [Google Play Console](https://play.google.com/console/)
+  - [Capacitor Android](https://capacitorjs.com/docs/android)
+- **iOS:**
+  - [App Store Connect](https://appstoreconnect.apple.com/)
+  - [TestFlight](https://developer.apple.com/testflight/)
+  - [Capacitor iOS](https://capacitorjs.com/docs/ios)
+  - [iOS Code Signing Guide](https://docs.fastlane.tools/codesigning/getting-started/)
+- **Ruby:**
+  - [rbenv GitHub](https://github.com/rbenv/rbenv)
+  - [RubyInstaller for Windows](https://rubyinstaller.org/)
+
+---
+
+**📝 Note:** 本文件為共用入口。平台特定設定請參考對應文件（Android / iOS）。