botrun-horse 2.31.0 → 2.34.0

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

@@ -1,431 +0,0 @@
-# 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

@@ -1,5 +0,0 @@
-# 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

@@ -1,133 +0,0 @@
-# 🚀 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)