botrun-horse 2.29.2 → 2.31.0

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

@@ -0,0 +1,431 @@
+# iOS 自動化部署設定指南
+
+本文件說明如何設定 iOS Fastlane 自動化部署環境。
+
+## 📋 前置需求
+
+### 必要軟體
+- Xcode (已安裝)
+- Xcode Command Line Tools
+- Ruby 3.3.0 (使用 rbenv 管理)
+- Bundler (Ruby 套件管理器)
+- Homebrew (macOS 套件管理器)
+
+### 權限需求
+- Apple Developer 帳號
+- App Store Connect 存取權限（Admin 或 App Manager 角色）
+
+---
+
+## 🚀 快速開始（團隊成員）
+
+如果您是團隊成員接手現有設定，只需執行以下步驟：
+
+### 1. 取得 API Key 檔案
+
+向專案負責人索取 `AuthKey_8DU68C8R33.p8` 檔案，並複製到：
+
+```bash
+cp AuthKey_8DU68C8R33.p8 /Users/<your-username>/Projects/botrun-c/mobile-ios/fastlane/
+chmod 600 /Users/<your-username>/Projects/botrun-c/mobile-ios/fastlane/AuthKey_8DU68C8R33.p8
+```
+
+### 2. 確認環境變數
+
+確認 `mobile-ios/fastlane/.env` 已正確設定（已在 repo 中）：
+
+```bash
+cat fastlane/.env
+```
+
+應包含：
+```
+# 使用 IOS_ 前綴避免觸發 Fastlane 的環境變數自動對應機制
+IOS_API_KEY_PATH=AuthKey_8DU68C8R33.p8
+APP_STORE_CONNECT_API_KEY_ID=8DU68C8R33
+APP_STORE_CONNECT_API_ISSUER_ID=69a6de74-83e0-47e3-e053-5b8c7c11a4d1
+```
+
+### 3. 安裝依賴
+
+⚠️ **重要**：需要先安裝 Web 專案依賴，再安裝 Fastlane 依賴
+
+**步驟 3.1：安裝 Web 專案依賴**
+
+```bash
+cd /Users/<your-username>/Projects/botrun-c/web
+pnpm install
+
+# 驗證依賴安裝完成
+pnpm list | head -20
+```
+
+**步驟 3.2：安裝 Fastlane 依賴**
+
+```bash
+cd /Users/<your-username>/Projects/botrun-c/mobile-ios
+export PATH="$HOME/.rbenv/shims:$PATH"
+bundle install
+```
+
+### 4. 執行建置
+
+```bash
+export PATH="$HOME/.rbenv/shims:$PATH"
+bundle exec fastlane build_local
+```
+
+第一次執行時，macOS 會要求您輸入登入密碼來授權 Keychain 存取憑證：
+- 輸入您的 macOS 登入密碼
+- **建議選擇「永遠允許」**，避免每次都要輸入密碼
+
+### 5. 可用指令
+
+```bash
+# 本地測試建置（不上傳）
+bundle exec fastlane build_local
+
+# 部署到 TestFlight（內部測試）
+bundle exec fastlane internal_testflight
+
+# 部署到 Firebase App Distribution（快速測試）
+bundle exec fastlane internal_firebase
+
+# 正式發佈到 App Store
+bundle exec fastlane production
+```
+
+---
+
+## 🔧 完整初始設定（首次設定者）
+
+以下為首次設定整個環境的完整步驟。
+
+### 步驟 1: 選擇驗證方式
+
+iOS 部署有兩種驗證方式：
+- **方案 A: App Store Connect API Key（推薦）** - 不需要 2FA，適合 CI/CD
+- 方案 B: Apple ID + 應用程式專用密碼 - 需要 2FA，適合手動操作
+
+**本專案使用方案 A（API Key）**
+
+### 步驟 2: 建立 App Store Connect API Key
+
+#### 2.1 開啟 API 存取權（需 Account Holder 權限）
+
+1. 前往 [App Store Connect - Users and Access - Integrations](https://appstoreconnect.apple.com/access/integrations/api)
+2. 點選「Keys」分頁
+3. 如果顯示「Request Access」，請 Account Holder 點選並同意條款
+
+#### 2.2 建立 API Key（需 Admin 權限）
+
+1. 在「Keys」分頁點選「+」或「Generate API Key」
+2. 填寫：
+   - **Name**: `Fastlane CI`
+   - **Access**: `App Manager` 或 `Developer`（根據需求選擇）
+3. 點選「Generate」
+4. 記錄以下資訊：
+   - **Issuer ID**: `69a6de74-83e0-47e3-e053-5b8c7c11a4d1`
+   - **Key ID**: `8DU68C8R33`
+5. 點選「Download API Key」下載 `.p8` 檔案
+
+> **注意**: `.p8` 檔案只能下載一次，請妥善保管！
+
+#### 2.3 安全儲存 API Key
+
+```bash
+# 複製到 fastlane 目錄
+cp ~/Downloads/AuthKey_8DU68C8R33.p8 /Users/<your-username>/Projects/botrun-c/mobile-ios/fastlane/
+
+# 設定權限（僅當前使用者可讀寫）
+chmod 600 /Users/<your-username>/Projects/botrun-c/mobile-ios/fastlane/AuthKey_8DU68C8R33.p8
+
+# 驗證已被 git ignore
+cd /Users/<your-username>/Projects/botrun-c/mobile-ios
+git status | grep AuthKey  # 應該看不到任何輸出
+```
+
+### 步驟 3: 設定環境變數
+
+編輯 `mobile-ios/fastlane/.env`（範本已在 `.env.template`）：
+
+```bash
+# iOS Project Configuration
+IOS_PROJECT_PATH=../ios/App
+IOS_SCHEME=App
+
+# App Store Connect API Key（推薦方法）
+# 使用 IOS_ 前綴避免觸發 Fastlane 的環境變數自動對應機制
+IOS_API_KEY_PATH=AuthKey_8DU68C8R33.p8
+APP_STORE_CONNECT_API_KEY_ID=8DU68C8R33
+APP_STORE_CONNECT_API_ISSUER_ID=69a6de74-83e0-47e3-e053-5b8c7c11a4d1
+
+# Firebase App Distribution (optional)
+# FIREBASE_APP_ID=your-firebase-app-id
+# FIREBASE_GROUPS=internal-testers
+```
+
+### 步驟 4: 安裝 Web 專案依賴
+
+⚠️ **重要**：Fastlane 建置流程會先編譯 Web 專案，所以必須先安裝 Web 依賴
+
+```bash
+cd /Users/<your-username>/Projects/botrun-c/web
+pnpm install
+
+# 驗證依賴安裝完成
+pnpm list | head -20
+```
+
+### 步驟 5: 設定程式碼簽署
+
+本專案使用 **Xcode Automatic Signing**（最簡單的方式）。
+
+1. 打開 Xcode，開啟 `mobile-ios/ios/App/App.xcworkspace`
+2. 選擇「App」target
+3. 前往「Signing & Capabilities」
+4. 確認設定：
+   - ✅ Automatically manage signing
+   - Team: `D6Y5T3QYA3` (CHUAN-HSUAN HSU)
+   - Bundle Identifier: `com.cameoinfo.botrun`
+
+### 步驟 6: 安裝 Ruby 依賴
+
+#### 5.1 設定 Ruby 環境
+
+```bash
+# 確認 Ruby 版本
+cd /Users/<your-username>/Projects/botrun-c/mobile-ios
+cat .ruby-version  # 應顯示 3.3.0
+
+# 確認使用 rbenv 的 Ruby（不是系統 Ruby）
+export PATH="$HOME/.rbenv/shims:$PATH"
+which ruby  # 應顯示 /Users/<your-username>/.rbenv/shims/ruby
+ruby -v     # 應顯示 ruby 3.3.0
+```
+
+#### 5.2 安裝 Bundler 依賴
+
+```bash
+bundle install
+```
+
+這會安裝：
+- fastlane
+- cocoapods (~> 1.12)
+
+### 步驟 6: 設定 Bundle Config（重要！）
+
+**Capacitor 需要在 `ios/App` 目錄執行 `bundle exec pod install`，但 Gemfile 在上兩層。**
+
+建立 Bundle 配置指向正確的 Gemfile：
+
+```bash
+mkdir -p ios/App/.bundle
+cat > ios/App/.bundle/config << 'EOF'
+---
+BUNDLE_GEMFILE: "../../Gemfile"
+EOF
+```
+
+驗證配置：
+
+```bash
+cd ios/App
+bundle exec pod --version  # 應成功顯示版本號
+cd ../..
+```
+
+### 步驟 7: 測試本地建置
+
+```bash
+export PATH="$HOME/.rbenv/shims:$PATH"
+bundle exec fastlane build_local
+```
+
+建置流程：
+1. ✅ Web 專案建置
+2. ✅ Capacitor 同步（CocoaPods 安裝）
+3. ✅ iOS Archive 編譯
+4. ✅ IPA 簽署和導出
+
+**首次執行時，macOS 會要求授權 Keychain 存取：**
+- 彈出對話框：「"codesign" 想要取得您的鑰匙圈中的金鑰 "Apple Development: CHUAN-HSUAN HSU (CAMEO Info-Tech Inc.)" 的密碼」
+- 輸入您的 macOS 登入密碼
+- **建議選擇「永遠允許」**，避免每次建置都要輸入密碼
+
+成功後會產生：
+- `mobile-ios/build/app-local.ipa` (~5.8MB)
+
+### 步驟 8: 測試 TestFlight 部署
+
+```bash
+export PATH="$HOME/.rbenv/shims:$PATH"
+bundle exec fastlane internal_testflight
+```
+
+這會：
+1. 建置 Web + 同步 Capacitor
+2. 自動遞增 Build Number
+3. 建置 Release IPA
+4. 上傳到 TestFlight
+
+**TestFlight 處理時間**:
+- 上傳完成後，Apple 會進行 10-30 分鐘的處理（Binary 掃描、合規性檢查）
+- 可在 [App Store Connect](https://appstoreconnect.apple.com) → TestFlight 查看狀態
+- 處理完成後即可新增測試人員
+
+---
+
+## 🔑 版本號管理
+
+### Marketing Version (CFBundleShortVersionString)
+- 用戶可見的版本號 (例如 `1.2.1`)
+- 手動設定，遵循語義化版本
+- ⚠️ **需要更新兩個地方**：
+  1. `Info.plist` 中的 `CFBundleShortVersionString`
+  2. `project.pbxproj` 中的 `MARKETING_VERSION`
+
+#### 修改方式
+
+**步驟 1：使用 Fastlane 更新 Info.plist**
+
+```bash
+cd /Users/<your-username>/Projects/botrun-c/mobile-ios
+bundle exec fastlane run increment_version_number \
+  xcodeproj:/Users/<your-username>/Projects/botrun-c/mobile-ios/ios/App/App.xcodeproj \
+  version_number:"1.3.0"
+```
+
+**步驟 2：更新 Xcode 專案檔案中的 MARKETING_VERSION**
+
+⚠️ **重要**：Xcode 會優先顯示 `project.pbxproj` 中的版本號，所以必須手動更新：
+
+```bash
+# 使用 sed 更新（將 1.2.2 改為 1.3.0）
+sed -i '' 's/MARKETING_VERSION = 1.2.2;/MARKETING_VERSION = 1.3.0;/g' \
+  ios/App/App.xcodeproj/project.pbxproj
+
+# 驗證更新成功
+grep "MARKETING_VERSION" ios/App/App.xcodeproj/project.pbxproj
+```
+
+或在 Xcode 中手動更新：
+1. 開啟 `App.xcworkspace`
+2. 選擇專案 → App target → General tab
+3. 修改「Version」欄位為新版本號（例如 `1.3.0`）
+
+### Build Number (CFBundleVersion)
+- 內部版本號 (例如 `5`, `6`, `7`)
+- **自動遞增**（每次執行 `internal_testflight` 或 `production` 時）
+- Apple 要求每次上傳到 TestFlight/App Store 都必須是新的 Build Number
+- 不需手動管理
+
+---
+
+## 📁 重要檔案說明
+
+### 版本控制中的檔案
+- `Gemfile` - Ruby 依賴定義（fastlane, cocoapods）
+- `Gemfile.lock` - 依賴版本鎖定
+- `.ruby-version` - 指定 Ruby 版本 (3.3.0)
+- `fastlane/Fastfile` - Fastlane 自動化腳本
+- `fastlane/.env.template` - 環境變數範本
+- `ios/App/.bundle/config` - Bundle 配置（指向上層 Gemfile）
+
+### 不在版本控制中的檔案（敏感資訊）
+- `fastlane/.env` - 實際環境變數（包含 API Key 路徑）
+- `fastlane/AuthKey_*.p8` - App Store Connect API Key（極度機密！）
+- `build/` - 建置產出目錄
+
+---
+
+## 🛠️ 疑難排解
+
+### 問題 1: `bundle exec pod` 找不到
+
+**錯誤訊息**:
+```
+bundler: failed to load command: pod
+can't find executable pod for gem cocoapods
+```
+
+**解決方案**:
+確認 `ios/App/.bundle/config` 存在並指向正確的 Gemfile：
+
+```bash
+cat ios/App/.bundle/config
+# 應顯示:
+# ---
+# BUNDLE_GEMFILE: "../../Gemfile"
+```
+
+### 問題 2: Ruby 版本不對（使用系統 Ruby 2.6.10）
+
+**解決方案**:
+每次執行前先設定 PATH：
+
+```bash
+export PATH="$HOME/.rbenv/shims:$PATH"
+which ruby  # 確認路徑
+ruby -v     # 確認版本 3.3.0
+```
+
+或加入 `~/.zshrc` 永久生效：
+
+```bash
+echo 'export PATH="$HOME/.rbenv/shims:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+### 問題 3: Keychain 授權一直跳出
+
+**原因**: 第一次授權時選擇了「允許」而不是「永遠允許」
+
+**解決方案**:
+1. 打開「鑰匙圈存取」應用程式
+2. 搜尋「Apple Development」
+3. 雙擊憑證 → 「存取控制」
+4. 選擇「允許所有應用程式取用此項目」
+5. 儲存
+
+### 問題 4: TestFlight 上傳失敗 - "Couldn't find API key JSON file"
+
+**錯誤訊息**:
+```
+Error setting value 'AuthKey_8DU68C8R33.p8' for option 'api_key_path'
+Couldn't find API key JSON file at path 'AuthKey_8DU68C8R33.p8'
+```
+
+**原因**:
+環境變數命名觸發了 Fastlane 的自動對應機制：
+- `upload_to_testflight` 有參數 `api_key_path`（期待 JSON 檔案）
+- 環境變數 `APP_STORE_CONNECT_API_KEY_PATH` 會自動對應到此參數
+- Fastlane 優先使用環境變數，導致 Lane Context 被忽略
+- 因此嘗試將 `.p8` 檔案當作 JSON 解析而失敗
+
+**解決方案**:
+已在 `.env` 和 `Fastfile` 中修正：
+1. 環境變數改名為 `IOS_API_KEY_PATH`（避免自動對應）
+2. `Fastfile` 使用 `key_content` 參數傳遞檔案內容（更可靠）
+3. 明確設定 `is_key_content_base64: false`
+
+這是 Fastlane 2.210+ 的已知問題，使用 `key_content` 是 2024/2025 推薦做法。
+
+---
+
+## 📚 參考資源
+
+- [Fastlane 官方文件](https://docs.fastlane.tools/)
+- [App Store Connect API 文件](https://developer.apple.com/documentation/appstoreconnectapi)
+- [Capacitor iOS 文件](https://capacitorjs.com/docs/ios)
+- [CocoaPods 官方網站](https://cocoapods.org/)
+
+---
+
+**文件版本**: 1.1.0
+**最後更新**: 2025-11-19
+**維護者**: Claude Code
+**變更記錄**:
+- v1.1.0 (2025-11-19): 修正環境變數命名衝突問題，改用 `IOS_API_KEY_PATH` + `key_content` 方案
+- v1.0.0 (2025-11-19): 初版文件

package/botrun-c/fastlane/Pluginfile

@@ -0,0 +1,5 @@
+# Autogenerated by fastlane
+#
+# Ensure this file is checked in to source control!
+
+gem 'fastlane-plugin-firebase_app_distribution'

package/botrun-c/fastlane/QUICK-START.md

@@ -0,0 +1,133 @@
+# 🚀 Botrun Android 部署快速指南
+
+## 🎯 三種部署方式
+
+### 1. 🧪 內部測試（Firebase App Distribution）
+
+**最快速的測試方式，適合日常開發測試**
+
+```bash
+cd /Users/seba/Projects/botrun-c/mobile-android
+bundle exec fastlane internal_firebase
+```
+
+✅ **優點：**
+- 超快！幾分鐘就能分發
+- 不需要 Google Play 審核
+- 測試人員點擊 email 連結直接下載
+
+❌ **缺點：**
+- 需要測試人員允許安裝 APK
+- 無法測試 Play Store 更新流程
+
+---
+
+### 2. 📦 Google Play 內部測試
+
+**測試 Play Store 更新流程**
+
+```bash
+cd /Users/seba/Projects/botrun-c/mobile-android
+bundle exec fastlane internal_play
+```
+
+✅ **優點：**
+- 從 Play Store 下載，像正式版一樣
+- 測試 Play Store 更新機制
+
+❌ **缺點：**
+- 需要等 Google Play 審核（數小時）
+- 測試人員需要被加入 Internal Testing list
+
+---
+
+### 3. 🚀 正式發佈
+
+**發佈到 Production，所有用戶可見**
+
+```bash
+cd /Users/seba/Projects/botrun-c/mobile-android
+bundle exec fastlane production
+```
+
+**分階段發佈流程：**
+
+1. **初始發佈（10%）**
+   ```bash
+   bundle exec fastlane production
+   ```
+
+2. **增加到 50%**
+   ```bash
+   bundle exec fastlane promote_production percentage:0.5
+   ```
+
+3. **完成 rollout（100%）**
+   ```bash
+   bundle exec fastlane complete_rollout
+   ```
+
+---
+
+## 📋 首次設定檢查清單
+
+在第一次執行部署前，確認以下項目：
+
+- [ ] Android 平台已建立（`npx cap add android`）
+- [ ] Ruby 已安裝（`ruby --version`）
+- [ ] Bundler 已安裝（`bundle --version`）
+- [ ] Fastlane 已安裝（`bundle install`）
+- [ ] Firebase Service Account JSON 已下載並放在正確位置
+- [ ] Google Play Service Account JSON 已下載並放在正確位置
+- [ ] `.env` 檔案已建立並填入正確值
+- [ ] **Firebase Console 已建立 `internal-testers` group**（必須！否則會 404 錯誤）
+- [ ] Google Play Console 已手動上傳第一次 AAB（僅需一次）
+- [ ] Android Keystore 已建立（用於 release builds）
+
+詳細設定步驟請參考 [ANDROID-DEPLOYMENT-SETUP.md](./ANDROID-DEPLOYMENT-SETUP.md)
+
+---
+
+## 🛠️ 常用指令
+
+### 新增測試人員
+
+```bash
+bundle exec fastlane add_testers emails:"test1@example.com,test2@example.com"
+```
+
+### 查看最新 Firebase 發佈
+
+```bash
+bundle exec fastlane latest_firebase_release
+```
+
+### 本地建置測試
+
+```bash
+# 僅建置 Web
+bundle exec fastlane build_web
+
+# 僅同步 Capacitor
+bundle exec fastlane sync_capacitor
+
+# 僅建置 APK
+bundle exec fastlane build_debug_apk
+
+# 僅建置 AAB
+bundle exec fastlane build_release_aab
+```
+
+---
+
+## ❓ 遇到問題？
+
+參考 [疑難排解](./ANDROID-DEPLOYMENT-SETUP.md#疑難排解) 章節
+
+---
+
+## 📚 完整文件
+
+- [完整設定指南](./ANDROID-DEPLOYMENT-SETUP.md)
+- [Fastlane 官方文件](https://docs.fastlane.tools/)
+- [Firebase App Distribution](https://firebase.google.com/docs/app-distribution)