botrun-horse 2.29.2 → 2.30.0

package/botrun-c/mobile-ios/QUICK-START.md

@@ -0,0 +1,189 @@
+# 🚀 快速開始指南
+
+## 📋 前置需求
+
+- ✅ macOS (Monterey 12.0+)
+- ✅ Xcode 14+
+- ✅ Node.js 18+
+- ✅ Firebase 專案 (已啟用 Google Sign-In)
+
+## ⚡ 3 步驟啟動 iOS App
+
+### 1️⃣ 下載 Firebase iOS 設定檔
+
+```bash
+# 前往 Firebase Console
+open https://console.firebase.google.com
+
+# 步驟:
+# 1. 選擇專案 → 專案設定
+# 2. 新增 iOS App (如果還沒有)
+# 3. Bundle ID 填入: com.botrun.agent
+# 4. 下載 GoogleService-Info.plist
+# 5. 移動到此目錄:
+mv ~/Downloads/GoogleService-Info.plist ./
+```
+
+### 2️⃣ 執行自動化安裝腳本
+
+```bash
+./setup-ios.sh
+```
+
+這會自動：
+- ✅ 檢查環境 (Node.js, Xcode)
+- ✅ 安裝相依套件
+- ✅ 建置 Next.js Web
+- ✅ 初始化 iOS 專案
+- ✅ 同步 Web 內容
+- ✅ 複製 Firebase 設定
+
+### 3️⃣ 開啟 Xcode 並執行
+
+```bash
+npm run open
+```
+
+在 Xcode 中：
+1. 選擇 **Signing & Capabilities** → 選擇你的開發團隊
+2. 連接 iPhone (或選擇模擬器)
+3. 點擊 ▶️ **Run**
+
+---
+
+## 🔄 日常開發流程
+
+### 修改程式碼後重新建置
+
+```bash
+# 方法 1: 完整重建 + 開啟 Xcode
+npm run dev
+
+# 方法 2: 只建置並同步 (不開 Xcode)
+npm run build:web && npm run sync
+```
+
+### 只修改 web/ 內的 UI
+
+```bash
+# 在 web/ 目錄開發
+cd ../web
+npm run dev          # 啟動 Next.js dev server
+open http://localhost:3000
+
+# 確認 UI 後，回到 mobile-ios/
+cd ../mobile-ios
+npm run build:web    # 建置靜態檔
+npm run sync         # 同步到 iOS
+```
+
+---
+
+## 📱 測試 Firebase Gmail 登入
+
+### 確認清單
+
+- [ ] `GoogleService-Info.plist` 在 `ios/App/App/` 中
+- [ ] Firebase Console 已啟用 Google Sign-In
+- [ ] Firebase Console → Authentication → Sign-in method → Google → 已啟用
+- [ ] Xcode → Info.plist 有加入 `REVERSED_CLIENT_ID` 的 URL Scheme
+
+### 手動加入 URL Scheme (如果自動化腳本沒做)
+
+```bash
+# 1. 取得 REVERSED_CLIENT_ID
+cat GoogleService-Info.plist | grep -A1 "REVERSED_CLIENT_ID" | tail -1 | sed 's/.*<string>\(.*\)<\/string>/\1/'
+
+# 2. 在 Xcode 開啟 Info.plist
+# 3. 新增 URL Types → URL Schemes → 貼上剛剛的值
+```
+
+---
+
+## 🛠️ 常用除錯指令
+
+```bash
+# 檢查 Capacitor 狀態
+npx cap doctor
+
+# 更新 Capacitor 版本
+npx cap update ios
+
+# 清理重建
+rm -rf ios/
+npx cap add ios
+npm run sync
+
+# 檢查 Firebase 設定檔
+ls -la ios/App/App/GoogleService-Info.plist
+```
+
+---
+
+## 📦 產生 .ipa 發布檔
+
+### 使用 Xcode
+
+1. Product → Archive
+2. 等待建置完成
+3. Distribute App → App Store Connect / Ad Hoc / Development
+4. 選擇簽章方式
+5. Export .ipa
+
+### 使用指令列
+
+```bash
+# 安裝 fastlane
+gem install fastlane
+
+# 設定 fastlane (之後再做)
+# cd ios/App
+# fastlane init
+```
+
+---
+
+## ❓ 常見問題
+
+### Q: 我沒有 Apple Developer 付費帳號可以測試嗎？
+
+A: 可以！免費帳號可以：
+- ✅ 在實體 iPhone 測試 (7 天期限)
+- ✅ 使用模擬器 (無限制)
+- ❌ 無法上架 App Store
+
+### Q: Firebase Auth 在模擬器上無法運作？
+
+A: 部分 Firebase 功能在模擬器有限制，建議用實體裝置測試 Gmail 登入。
+
+### Q: 如何更新 web/ 的程式碼到 iOS？
+
+A: 每次修改 `web/` 後執行：
+```bash
+npm run build:web && npm run sync
+```
+
+### Q: 如何檢查 TypeScript 有沒有錯誤？
+
+A: Capacitor 設定檔已支援 TypeScript：
+```bash
+npx tsc --noEmit
+```
+
+---
+
+## 🎯 下一步
+
+- [ ] 測試 Gmail 登入功能
+- [ ] 設定 App Icon 和 Splash Screen
+- [ ] 設定 Push Notification (如需要)
+- [ ] 申請 Apple Developer Program ($99/年)
+- [ ] 上架 TestFlight 測試
+- [ ] 上架 App Store
+
+---
+
+**需要幫助？**
+- 📖 [完整文件](./README.md)
+- 🔧 [Capacitor Docs](https://capacitorjs.com/docs)
+- 🔥 [Firebase iOS Setup](https://firebase.google.com/docs/ios/setup)

package/botrun-c/mobile-ios/README.md

@@ -0,0 +1,231 @@
+# 📱 Botrun iOS App (Capacitor.js + TypeScript)
+
+## 🏗️ 技術棧
+
+- **Capacitor.js 6.x** - 原生 iOS 容器
+- **TypeScript + ES Modules** - 100% 類型安全
+- **Firebase Authentication** - Gmail 登入
+- **Next.js Static Export** - Web 內容來源
+
+## 📂 專案結構
+
+```
+mobile-ios/
+├── capacitor.config.ts          # Capacitor 設定 (TypeScript)
+├── tsconfig.json                # TypeScript 設定
+├── package.json                 # 相依套件
+├── GoogleService-Info.plist     # Firebase iOS 設定 (需自行下載)
+└── ios/                         # iOS 原生專案 (自動產生)
+```
+
+## 🚀 快速開始
+
+### 1️⃣ 安裝相依套件
+
+```bash
+cd mobile-ios
+npm install
+```
+
+### 2️⃣ 設定 Firebase iOS
+
+1. 前往 [Firebase Console](https://console.firebase.google.com)
+2. 選擇專案 → 專案設定 → iOS App
+3. 下載 `GoogleService-Info.plist`
+4. 放到 `mobile-ios/GoogleService-Info.plist`
+
+**重要欄位對照:**
+
+| Firebase Console | GoogleService-Info.plist |
+|------------------|--------------------------|
+| Bundle ID | `com.botrun.agent` (需與 capacitor.config.ts 一致) |
+| iOS API Key | `API_KEY` |
+| iOS Client ID | `CLIENT_ID` |
+
+### 3️⃣ 建置 Web 內容
+
+```bash
+npm run build:web
+```
+
+這會執行：
+```bash
+cd ../web && npm run build
+```
+
+產生靜態檔案到 `../web/out/`
+
+### 4️⃣ 初始化 iOS 專案
+
+```bash
+npx cap add ios
+```
+
+這會建立 `ios/` 目錄
+
+### 5️⃣ 同步 Web 內容到 iOS
+
+```bash
+npm run sync
+```
+
+等同於 `npx cap sync ios`
+
+### 6️⃣ 開啟 Xcode
+
+```bash
+npm run open
+```
+
+等同於 `npx cap open ios`
+
+在 Xcode 中：
+1. 連接實體 iPhone
+2. 選擇開發團隊 (Apple Developer Account)
+3. 點擊 ▶️ Run
+
+## 🔄 開發流程
+
+### 完整建置 + 開啟 Xcode
+
+```bash
+npm run dev
+```
+
+這會依序執行：
+1. 建置 Next.js (`npm run build:web`)
+2. 同步到 iOS (`npm run sync`)
+3. 開啟 Xcode (`npm run open`)
+
+### 只同步程式碼變更
+
+```bash
+npm run sync
+```
+
+## 🔐 Firebase Gmail 登入設定
+
+### iOS 專案額外設定
+
+在 Xcode 中：
+
+1. **開啟 Info.plist**
+   - 路徑: `ios/App/App/Info.plist`
+   - 新增 URL Scheme:
+
+```xml
+<key>CFBundleURLTypes</key>
+<array>
+  <dict>
+    <key>CFBundleURLSchemes</key>
+    <array>
+      <string>YOUR_REVERSED_CLIENT_ID_HERE</string>
+    </array>
+  </dict>
+</array>
+```
+
+`YOUR_REVERSED_CLIENT_ID_HERE` 從 `GoogleService-Info.plist` 的 `REVERSED_CLIENT_ID` 複製
+
+2. **複製 GoogleService-Info.plist 到 iOS 專案**
+
+```bash
+cp GoogleService-Info.plist ios/App/App/
+```
+
+或在 Xcode 中手動拖曳檔案到 `App/` 資料夾
+
+## 📦 套件說明
+
+### 核心套件
+
+```json
+{
+  "@capacitor/core": "^6.2.0",           // Capacitor 核心
+  "@capacitor/ios": "^6.2.0",            // iOS 平台支援
+  "@capacitor/cli": "^6.2.0"             // CLI 工具
+}
+```
+
+### 功能套件
+
+```json
+{
+  "@capacitor/app": "^6.0.1",            // App 生命週期
+  "@capacitor/haptics": "^6.0.1",        // 觸覺回饋
+  "@capacitor/keyboard": "^6.0.2",       // 鍵盤控制
+  "@capacitor/status-bar": "^6.0.1",     // 狀態列樣式
+  "@capacitor-firebase/authentication": "^6.1.0"  // Firebase Auth
+}
+```
+
+## 🛠️ 常用指令
+
+| 指令 | 說明 |
+|------|------|
+| `npm run build:web` | 建置 Next.js 靜態檔案 |
+| `npm run sync` | 同步 Web 內容到 iOS |
+| `npm run open` | 開啟 Xcode |
+| `npm run dev` | 完整開發流程 (build + sync + open) |
+| `npx cap add ios` | 初始化 iOS 專案 |
+| `npx cap update ios` | 更新 Capacitor iOS 版本 |
+| `npx cap doctor` | 檢查環境設定 |
+
+## ⚠️ 注意事項
+
+1. **需要 macOS + Xcode**
+   - iOS 開發只能在 Mac 上進行
+   - 需安裝 Xcode 14+ 和 Command Line Tools
+
+2. **Apple Developer Account**
+   - 測試實體裝置需要免費或付費帳號
+   - 模擬器不需帳號
+
+3. **Bundle ID 一致性**
+   - `capacitor.config.ts` 的 `appId`
+   - Firebase Console 的 iOS Bundle ID
+   - Xcode 專案的 Bundle Identifier
+   - 三者必須完全相同：`com.botrun.agent`
+
+4. **Firebase 設定檔**
+   - `GoogleService-Info.plist` 不要提交到 Git
+   - 已加入 `.gitignore`
+   - 團隊成員需各自下載
+
+## 🐛 疑難排解
+
+### 問題: `npx: command not found`
+
+```bash
+npm install -g npx
+```
+
+### 問題: Xcode 無法找到 GoogleService-Info.plist
+
+手動複製到 iOS 專案：
+```bash
+cp GoogleService-Info.plist ios/App/App/
+```
+
+然後在 Xcode 中 Add Files to "App"
+
+### 問題: Firebase Auth 無法運作
+
+確認：
+1. ✅ `GoogleService-Info.plist` 在 `ios/App/App/` 中
+2. ✅ `Info.plist` 有加入 `REVERSED_CLIENT_ID` 的 URL Scheme
+3. ✅ Firebase Console 有啟用 Google Sign-In
+
+### 問題: Web 內容未更新
+
+```bash
+# 完整重新建置
+npm run build:web
+npm run sync
+```
+
+## 📚 參考文件
+
+- [Capacitor 官方文件](https://capacitorjs.com/docs)
+- [Capacitor Firebase Auth Plugin](https://github.com/capawesome-team/capacitor-firebase)
+- [Firebase iOS Setup](https://firebase.google.com/docs/ios/setup)

package/botrun-c/mobile-ios/capacitor.config.ts

@@ -0,0 +1,46 @@
+import type { CapacitorConfig } from '@capacitor/cli';
+
+const config: CapacitorConfig = {
+  appId: 'ai.botrun.botrunapp',
+  appName: 'Botrun',
+  webDir: '../web/out',
+  server: {
+    androidScheme: 'https',
+    iosScheme: 'https'
+  },
+  plugins: {
+    // ===== Capawesome Live Update =====
+    LiveUpdate: {
+      appId: "1182ca56-0577-43fc-8e84-c3e0841dce69",
+      autoDeleteBundles: true,      // 自動刪除舊版本節省空間
+      resetOnUpdate: false,          // 更新後不重置 App 狀態
+      defaultChannel: "production",  // 預設頻道 (production/beta/internal)
+      enabled: false,                 // 啟用 Live Update
+      readyTimeout: 10000,           // 等待 bundle 載入的超時時間 (ms)
+    },
+    // ===== 原有配置 =====
+    StatusBar: {
+      style: 'light',  // light = 黑色圖示（適合淺色背景），dark = 白色圖示
+      overlaysWebView: true,  // true = WebView 延伸到 status bar 下方
+      // iOS 不支援 backgroundColor,會自動使用透明背景顯示底層 WebView 顏色
+    },
+    FirebaseAuthentication: {
+      skipNativeAuth: false,
+      providers: ['google.com', 'apple.com'],
+      // 重要：使用原生 Firebase Auth 而非 WebView
+      forceRefresh: false
+    },
+    SplashScreen: {
+      launchShowDuration: 2000,
+      backgroundColor: '#ffffff',
+      showSpinner: false
+    }
+  },
+  ios: {
+    contentInset: 'never',  // 不自動加入 padding,我們用 CSS safe-area 手動處理
+    limitsNavigationsToAppBoundDomains: true,
+    webContentsDebuggingEnabled: true  // 啟用 Safari 開發者工具 (iOS 16.4+ 必須)
+  }
+};
+
+export default config;