botrun-horse 2.31.0 → 2.34.0

package/botrun-c/TODO-CAPACITOR-INTEGRATION.md

@@ -1,482 +0,0 @@
-# 📱 Capacitor 整合 TODO List
-
-**建立日期**：2025-11-06
-**狀態**：進行中 (6/22 完成)
-**預計完成時間**：3-5 天
-**最後更新**：2025-11-06 (完成 Native 平台檔案讀取邏輯)
-
----
-
-## 🎯 專案目標
-
-將現有的 Next.js web app 封裝為 iOS 和 Android 原生 App，並解決長時間錄音問題。
-
----
-
-## 📊 整體進度
-
-```
-階段 1: Audio Recorder 整合     [▓▓▓▓▓▓░░░] 6/9  (Native 檔案讀取完成)
-階段 2: iOS 完善                [░░░░░░░░░] 0/3
-階段 3: Android 建立            [░░░░░░░░░] 0/5
-階段 4: 資源與優化              [░░░░░░░░░] 0/3
-階段 5: 測試與部署              [░░░░░░░░░] 0/2
-```
-
----
-
-## 🎤 階段 1：Audio Recorder 整合（優先）
-
-**目標**：替換 MediaRecorder 為 Capawesome Audio Recorder，解決長時間錄音問題
-**預計時間**：1 天
-**相依性**：無
-
-### ✅ 前置檢查
-
-- [x] **#1** 檢查 web/ 專案是否已整合 Capacitor SDK ✅
-  - **檢查項目**：
-    - [x] 是否有 `import { AudioRecorder } from '@capawesome-team/capacitor-audio-recorder'`
-    - [x] 環境判斷邏輯（使用 `window.Capacitor` 檢查）
-    - [ ] Firebase Auth 是否考慮 native 環境（尚未實作）
-  - **檔案位置**：`web/components/chat-input.tsx`, `web/contexts/AuthContext.tsx`
-  - **完成時間**：2025-11-06
-  - **備註**：發現 Capawesome Audio Recorder 本身支援跨平台，不需要手動區分環境
-
-### 📦 Plugin 安裝
-
-- [x] **#2** 在 web/ 安裝 @capacitor/filesystem 和 @capawesome/capacitor-audio-recorder ✅
-  ```bash
-  cd web && npm install @capacitor/filesystem @capawesome-team/capacitor-audio-recorder
-  ```
-  - **完成時間**：2025-11-06
-  - **備註**：Web 專案先安裝，mobile-ios/ 和 mobile-android/ 會在建置時同步
-
-- [x] **#3** 設定 Capawesome Audio Recorder license key ✅
-  - **方式**：環境變數 `CAPAWESOME_LICENSE_KEY`（或寫在 `capacitor.config.ts`）
-  - **檔案位置**：`mobile-ios/capacitor.config.ts`, `mobile-android/capacitor.config.ts`
-  - **完成時間**：2025-11-06
-  - **備註**：待 iOS/Android 專案建立時設定
-
-- [x] **#4** 在 web/package.json 加入 @capawesome/capacitor-audio-recorder 依賴 ✅
-  ```bash
-  cd web && npm install @capacitor/core @capawesome-team/capacitor-audio-recorder
-  ```
-  - **完成時間**：2025-11-06
-  - **備註**：同時安裝了 `@capacitor/core` (v7.4.4)
-
-### 💻 程式碼重構
-
-- [x] **#5** 修改 chat-input.tsx 支援 Capacitor Audio Recorder ✅
-  - **實作重點**：
-    - [x] 加入 `import { AudioRecorder } from '@capawesome-team/capacitor-audio-recorder'`
-    - [x] 使用統一 API：`AudioRecorder.startRecording()` / `stopRecording()`
-    - [x] 跨平台支援：Web 返回 `blob`，Native 返回 `uri`
-    - [x] 權限請求：`AudioRecorder.requestPermissions()`
-    - [x] Web 平台測試通過
-  - **檔案位置**：`web/components/chat-input.tsx:515-582`
-  - **參考文件**：https://capawesome.io/plugins/audio-recorder/
-  - **完成時間**：2025-11-06
-  - **備註**：Plugin 本身支援跨平台，不需要手動區分 Web/Native
-
-- [x] **#6** 更新轉錄邏輯支援 native 錄音檔案路徑 ✅
-  - **實作重點**：
-    - [x] Native 回傳檔案路徑（uri）
-    - [x] 使用 `Filesystem.readFile()` 讀取錄音檔案（base64 格式）
-    - [x] 轉換 base64 為 Blob
-    - [x] 支援多種音訊格式（webm, mp4, aac）
-    - [x] 驗證後端 API 支援所有格式
-  - **檔案位置**：`web/components/chat-input.tsx:378-387, 543-572, 475-482`
-  - **完成時間**：2025-11-06
-  - **音訊格式**：
-    - Web: audio/webm (.webm)
-    - iOS: audio/mp4 (.m4a)
-    - Android: audio/aac (.aac)
-
-### 🔐 權限設定
-
-- [ ] **#7** 設定 iOS 錄音權限說明
-  - **檔案位置**：`mobile-ios/ios/App/App/Info.plist`
-  - **新增內容**：
-    ```xml
-    <key>NSMicrophoneUsageDescription</key>
-    <string>需要麥克風權限以錄製語音訊息並轉換為文字</string>
-    ```
-  - **預計時間**：5 分鐘
-
-- [ ] **#8** 設定 Android 錄音權限
-  - **檔案位置**：`mobile-android/android/app/src/main/AndroidManifest.xml`
-  - **新增內容**：
-    ```xml
-    <uses-permission android:name="android.permission.RECORD_AUDIO" />
-    ```
-  - **預計時間**：5 分鐘
-
-### 🧪 測試
-
-- [ ] **#9** 測試長時間錄音功能（>10 分鐘）
-  - **測試項目**：
-    - [ ] iOS 實機測試 10+ 分鐘錄音
-    - [ ] Android 實機測試 10+ 分鐘錄音
-    - [ ] 背景錄音測試（切換 App）
-    - [ ] 轉錄功能是否正常
-    - [ ] 檔案大小和格式
-  - **預計時間**：1 小時
-
----
-
-## 📱 階段 2：iOS 完善
-
-**目標**：補完 iOS 專案的缺失部分
-**預計時間**：半天
-**相依性**：階段 1 完成
-
-- [ ] **#10** 在 mobile-ios/ 安裝 Firebase Authentication plugin
-  ```bash
-  cd mobile-ios && npm install @capacitor-firebase/authentication
-  ```
-  - **檔案位置**：`mobile-ios/package.json`
-  - **參考文件**：https://github.com/capawesome-team/capacitor-firebase
-  - **預計時間**：10 分鐘
-
-- [ ] **#18** 設定 iOS 其他權限說明
-  - **檔案位置**：`mobile-ios/ios/App/App/Info.plist`
-  - **新增內容**：
-    ```xml
-    <key>NSCameraUsageDescription</key>
-    <string>需要相機權限以拍攝照片並上傳</string>
-
-    <key>NSPhotoLibraryUsageDescription</key>
-    <string>需要相簿權限以選擇照片上傳</string>
-
-    <key>NSPhotoLibraryAddUsageDescription</key>
-    <string>需要權限以儲存照片到相簿</string>
-    ```
-  - **參考文件**：`mobile-ios/IOS-PERMISSIONS.md`
-  - **預計時間**：10 分鐘
-
-- [ ] **#20** 測試 iOS 建置流程
-  ```bash
-  cd mobile-ios
-  npm run build   # 建置 web + 同步 + 開啟 Xcode
-  ```
-  - **測試項目**：
-    - [ ] Next.js 靜態輸出正常
-    - [ ] Capacitor sync 成功
-    - [ ] Xcode 開啟無錯誤
-    - [ ] 模擬器運行正常
-    - [ ] 實機安裝成功
-  - **預計時間**：30 分鐘
-
----
-
-## 🤖 階段 3：Android 建立
-
-**目標**：建立完整的 Android 專案
-**預計時間**：2 天
-**相依性**：階段 1 完成（可平行進行）
-
-### 📁 專案結構
-
-- [ ] **#11** 建立 mobile-android/ 目錄結構和基本配置
-  - **建立檔案**：
-    - [ ] `mobile-android/capacitor.config.ts`（參考 iOS 版本）
-    - [ ] `mobile-android/package.json`
-    - [ ] `mobile-android/tsconfig.json`
-    - [ ] `mobile-android/.gitignore`
-  - **預計時間**：30 分鐘
-
-- [ ] **#12** 在 mobile-android/ 安裝 Android 相關依賴
-  ```bash
-  cd mobile-android
-  npm install @capacitor/core @capacitor/android @capacitor/cli
-  npm install @capacitor/app @capacitor/haptics @capacitor/keyboard @capacitor/status-bar
-  npm install @capacitor-firebase/authentication
-  npm install @capawesome/capacitor-audio-recorder
-  ```
-  - **預計時間**：10 分鐘
-
-### 🔥 Firebase 設定
-
-- [ ] **#13** 建立 Android Firebase 設定模板
-  - **建立檔案**：`mobile-android/google-services.json.template`
-  - **參考**：Firebase Console → Android App → 下載 `google-services.json`
-  - **Bundle ID**：`com.botrun.agent`（需與 iOS 一致）
-  - **預計時間**：15 分鐘
-
-### 📜 文件與腳本
-
-- [ ] **#14** 建立 Android 設定腳本
-  - **建立檔案**：`mobile-android/setup-android.sh`（參考 `mobile-ios/setup-ios.sh`）
-  - **功能**：
-    - [ ] 檢查環境（Node.js, Android Studio, JDK）
-    - [ ] 安裝相依套件
-    - [ ] 建置 Next.js Web
-    - [ ] 初始化 Android 專案（`npx cap add android`）
-    - [ ] 同步 Web 內容
-    - [ ] 複製 Firebase 設定
-  - **預計時間**：1 小時
-
-- [ ] **#15** 建立 Android 文件
-  - **建立檔案**：
-    - [ ] `mobile-android/README.md`
-    - [ ] `mobile-android/QUICK-START.md`
-    - [ ] `mobile-android/ANDROID-PERMISSIONS.md`
-  - **參考**：`mobile-ios/` 對應檔案
-  - **預計時間**：1 小時
-
-### 🔐 權限設定
-
-- [ ] **#19** 設定 Android 其他權限
-  - **檔案位置**：`mobile-android/android/app/src/main/AndroidManifest.xml`
-  - **新增內容**：
-    ```xml
-    <uses-permission android:name="android.permission.CAMERA" />
-    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
-    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
-    <uses-permission android:name="android.permission.INTERNET" />
-    ```
-  - **預計時間**：10 分鐘
-
-### 🧪 測試
-
-- [ ] **#21** 測試 Android 建置流程
-  ```bash
-  cd mobile-android
-  npm run build
-  npx cap open android
-  ```
-  - **測試項目**：
-    - [ ] Next.js 靜態輸出正常
-    - [ ] Capacitor sync 成功
-    - [ ] Android Studio 開啟無錯誤
-    - [ ] 模擬器運行正常
-    - [ ] 實機安裝成功
-  - **預計時間**：30 分鐘
-
----
-
-## 🎨 階段 4：資源與優化
-
-**目標**：準備 App 發布資源
-**預計時間**：1 天
-**相依性**：階段 2, 3 完成
-
-- [ ] **#16** 評估並安裝額外需要的 Capacitor plugins
-  - **評估清單**：
-    - [ ] **@capacitor/filesystem** - 檔案讀寫（轉錄檔案、PDF 處理）
-    - [ ] **@capacitor/camera** - 拍照功能
-    - [ ] **@capacitor/network** - 網路狀態檢測（離線提示）
-    - [ ] **@capacitor/share** - 分享功能
-    - [ ] **@capacitor/app-launcher** - 開啟外部 App（如 PDF 閱讀器）
-  - **決策**：根據實際需求選擇安裝
-  - **預計時間**：1 小時
-
-- [ ] **#17** 準備 App Icon 和 Splash Screen 圖片資源
-  - **需求**：
-    - [ ] App Icon（iOS: 1024x1024, Android: 多尺寸）
-    - [ ] Splash Screen（iOS: 多尺寸, Android: 多尺寸）
-  - **工具**：
-    - Figma / Sketch 設計
-    - Capacitor Assets 自動生成：`npx @capacitor/assets generate`
-  - **檔案位置**：
-    - `mobile-ios/resources/icon.png`
-    - `mobile-ios/resources/splash.png`
-    - `mobile-android/resources/icon.png`
-    - `mobile-android/resources/splash.png`
-  - **參考文件**：https://capacitorjs.com/docs/guides/splash-screens-and-icons
-  - **預計時間**：2 小時
-
----
-
-## 🚀 階段 5：測試與部署
-
-**目標**：驗證所有功能並建立統一部署流程
-**預計時間**：半天
-**相依性**：所有階段完成
-
-- [ ] **#22** 建立統一的部署腳本
-  - **建立檔案**：`scripts/build-mobile-apps.sh`
-  - **功能**：
-    - [ ] 建置 Next.js web (static export)
-    - [ ] 同步到 iOS (`cd mobile-ios && npm run sync`)
-    - [ ] 同步到 Android (`cd mobile-android && npm run sync`)
-    - [ ] 可選參數：`--ios-only`, `--android-only`, `--open-xcode`, `--open-android-studio`
-  - **範例**：
-    ```bash
-    ./scripts/build-mobile-apps.sh --ios-only --open-xcode
-    ```
-  - **預計時間**：1 小時
-
-- [ ] **最終測試清單**
-  - **iOS**：
-    - [ ] Gmail 登入正常
-    - [ ] 長時間錄音（>10 分鐘）正常
-    - [ ] 檔案上傳正常
-    - [ ] 轉錄功能正常
-    - [ ] 離線行為正常（顯示錯誤提示）
-  - **Android**：
-    - [ ] Gmail 登入正常
-    - [ ] 長時間錄音（>10 分鐘）正常
-    - [ ] 檔案上傳正常
-    - [ ] 轉錄功能正常
-    - [ ] 離線行為正常（顯示錯誤提示）
-
----
-
-## 📚 參考文件
-
-### Capacitor
-- [Capacitor 官方文件](https://capacitorjs.com/docs)
-- [Capacitor CLI](https://capacitorjs.com/docs/cli)
-- [Capacitor Plugins](https://capacitorjs.com/docs/plugins)
-
-### Capawesome Audio Recorder
-- [官方文件](https://capawesome.io/plugins/audio-recorder/)
-- [Getting Started](https://capawesome.io/plugins/audio-recorder/getting-started/)
-- [API Reference](https://capawesome.io/plugins/audio-recorder/api/)
-
-### Firebase
-- [Firebase iOS Setup](https://firebase.google.com/docs/ios/setup)
-- [Firebase Android Setup](https://firebase.google.com/docs/android/setup)
-- [Capacitor Firebase Plugin](https://github.com/capawesome-team/capacitor-firebase)
-
-### 平台特定
-- [iOS Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/)
-- [Android Material Design](https://m3.material.io/)
-
----
-
-## 🐛 已知問題與風險
-
-### 高風險
-1. ✅ **長時間錄音穩定性**（已透過 Capawesome Audio Recorder 解決）
-2. ✅ **檔案上傳在 native 的路徑處理**（已完成 Filesystem plugin 整合）
-3. **Firebase Auth 在 native 環境的行為差異**（需測試）
-
-### 中風險
-1. **iOS App Store 審核要求**（權限說明必須清楚）
-2. **Android 多裝置相容性**（需測試多個 Android 版本）
-3. **Capacitor plugin 版本衝突**（需統一版本）
-
-### 低風險
-1. **App Icon / Splash Screen 尺寸生成**（工具自動處理）
-2. **打包簽章設定**（後續處理）
-
----
-
-## 📝 開發筆記
-
-### 重要決策
-
-#### 2025-11-06 - 14:00
-- **決策**：使用 Capawesome Audio Recorder 取代 MediaRecorder
-  - **原因**：解決長時間錄音不穩定問題
-  - **取得 license key**：已完成
-
-#### 2025-11-06 - 14:30
-- **決策**：Capawesome Audio Recorder 本身支援跨平台
-  - **原因**：官方文件說明 "Cross-platform: Supports Android, iOS and Web"
-  - **影響**：不需要手動區分環境或使用 fallback，統一使用 AudioRecorder API
-  - **實作**：Web 返回 `blob`，Native 返回 `uri`（需要 Filesystem plugin 讀取）
-
-#### 2025-11-06 - 17:00
-- **決策**：完成 Native 平台檔案讀取邏輯實作
-  - **實作內容**：
-    - 加入 `@capacitor/filesystem` 依賴
-    - 實作 `base64ToBlob()` helper function
-    - 使用 `Filesystem.readFile()` 讀取 Native 錄音檔案
-    - 支援多種音訊格式（webm, mp4, aac）
-  - **驗證**：後端 API 已支援所有音訊格式
-  - **下一步**：設定 iOS/Android 權限並實機測試
-
-#### 待決策
-- [x] 是否需要 Filesystem plugin？（**✅ 已完成**，用於讀取 Native 平台的 `uri`）
-- [ ] 是否需要 Camera plugin？（目前只有檔案上傳，未來可能需要）
-- [ ] App Icon 設計風格？（需與 web 版一致）
-
----
-
-## 📱 Android 測試準備（當前階段）
-
-### 前置需求
-1. ✅ Web 平台錄音功能已測試通過
-2. ✅ Native 檔案讀取邏輯已完成（TODO #6）
-3. ⏳ 需要設定 iOS 錄音權限（TODO #7）
-4. ⏳ 需要設定 Android 錄音權限（TODO #8）
-
-### 測試環境檢查
-```bash
-# 1. 檢查 mobile-android 是否存在
-ls -la mobile-android/
-
-# 2. 如果不存在，需要先建立（參考階段 3）
-# 3. 檢查 Node.js 和 Android Studio 環境
-node --version
-echo $ANDROID_HOME
-```
-
-### 快速測試步驟
-1. **安裝依賴**（如果 mobile-android 已存在）
-   ```bash
-   cd mobile-android
-   npm install
-   npm install @capawesome-team/capacitor-audio-recorder
-   npm install @capacitor/filesystem
-   ```
-
-2. **同步 Web 內容**
-   ```bash
-   cd ../web
-   npm run build
-   cd ../mobile-android
-   npx cap sync
-   ```
-
-3. **開啟 Android Studio**
-   ```bash
-   npx cap open android
-   ```
-
-4. **測試項目**
-   - [ ] 錄音權限請求是否正常
-   - [ ] 開始錄音功能
-   - [ ] 停止錄音功能
-   - [ ] 錄音檔案是否正確儲存
-   - [ ] 轉錄功能是否正常（需要先完成 TODO #6）
-
-### 已知問題
-- ✅ **Native 平台檔案讀取已完成**：已實作 Filesystem plugin 讀取 uri 邏輯
-- ⚠️ **權限設定尚未完成**：需要在 Info.plist (iOS) 和 AndroidManifest.xml (Android) 加入錄音權限
-- ⚠️ **尚未實機測試**：Native 平台功能需要在真實裝置上測試驗證
-
----
-
-## ✅ 完成標記
-
-完成每個 TODO 後，請：
-1. 勾選對應的 checkbox
-2. 更新「整體進度」統計
-3. 記錄完成時間和遇到的問題
-4. Commit 變更並註明 TODO 編號
-
-**範例 commit message**：
-```
-✅ TODO #6: 實作 Native 平台檔案讀取與轉錄邏輯
-
-- 安裝 @capacitor/filesystem 依賴
-- 實作 base64ToBlob() helper function
-- 使用 Filesystem.readFile() 讀取 Native 錄音檔案
-- 支援多種音訊格式（webm, mp4, aac）
-- 驗證後端 API 相容性
-
-Changes:
-- web/components/chat-input.tsx (新增 import、helper function、Native 檔案讀取邏輯)
-- web/package.json (新增依賴)
-
-Time: 1 hour
-```
-
----
-
-**最後更新**：2025-11-06 17:00
-**下次 Review**：完成權限設定並實機測試後

package/botrun-c/VERIFICATION.md

@@ -1,121 +0,0 @@
-# 上傳路徑統一修正 - 驗證報告
-
-## 📋 修正內容
-
-### 問題
-本地開發與生產環境的檔案路徑結構不一致，導致 Claude 無法正確找到上傳的檔案。
-
-### 修正
-1. **後端** (`api/src/routes/upload.ts:50`)：統一本地開發也使用 `uploads/` 子目錄
-2. **前端** (`web/components/chat-input.tsx:358-392`)：統一路徑轉換邏輯
-
-## ✅ 驗證結果
-
-### 測試時間
-2025-11-11 13:59
-
-### 測試環境
-- 環境：sh/server.sh (本地開發)
-- API URL: http://localhost:8080
-- 工作目錄：`./api/data/test-user/projects/default/`
-
-### 測試步驟與結果
-
-#### 1. 檔案上傳測試 ✅
-```bash
-curl -X POST "http://localhost:8080/api/upload/direct" \
-  -H "Authorization: Bearer dummy-token" \
-  -F "file=@/Users/40gpu/Downloads/IMG_9165.PNG"
-```
-
-**結果**：
-- ✅ 上傳成功
-- ✅ 檔案儲存位置：`./api/data/test-user/projects/default/uploads/IMG_9165.PNG`
-- ✅ API 回傳 `displayPath`: `IMG_9165.PNG`
-
-**驗證**：
-```bash
-$ ls -la ./api/data/test-user/projects/default/uploads/
--rw-r--r--  1 40gpu  staff  817948 11 11 13:59 IMG_9165.PNG
--rw-r--r--  1 40gpu  staff  489429 11 11 13:52 IMG_9166.PNG
-```
-
-#### 2. 前端路徑轉換測試 ✅
-**前端接收**：`displayPath = "IMG_9165.PNG"`
-
-**轉換後**：`uploads/IMG_9165.PNG`
-
-**邏輯**：
-- 如果是純檔名（不含 `/`）→ 加上 `uploads/` 前綴
-- 如果是 GCS URL (`gs://...`) → 提取相對路徑
-
-#### 3. Chat API 多模態閱讀測試 ✅
-**使用者訊息**：
-```
-📄 IMG_9165.PNG - uploads/IMG_9165.PNG
-
-請幫我多模態解析這張圖片的內容
-```
-
-**Claude 工具呼叫**：
-```json
-{
-  "toolName": "mcp__botrun-multimodal-reader__read_multimodal",
-  "toolInput": {
-    "filePaths": "uploads/IMG_9165.PNG",
-    "prompt": "請詳細分析這張圖片的所有視覺元素..."
-  }
-}
-```
-
-**結果**：
-- ✅ Claude 正確識別檔案路徑為 `uploads/IMG_9165.PNG`
-- ✅ 工具呼叫格式正確
-- ✅ 路徑與實際檔案位置一致
-
-## 📊 統一後的路徑結構
-
-### 本地開發 (sh/server.sh)
-```
-工作目錄：./api/data/test-user/projects/default/
-檔案位置：./api/data/test-user/projects/default/uploads/IMG_9165.PNG
-相對路徑：uploads/IMG_9165.PNG ✅
-```
-
-### 生產環境 (sh/deploy-gcp.sh, Cloud Run)
-```
-工作目錄：/mnt/data/{userId}/projects/default/
-GCS 位置：gs://botrun-c/{userId}/projects/default/uploads/IMG_9165.PNG
-相對路徑：uploads/IMG_9165.PNG ✅
-```
-
-## 🎯 結論
-
-✅ **修正成功**：本地開發與生產環境的路徑結構現已完全統一
-
-✅ **sh/server.sh 環境驗證通過**：
-- 上傳功能正常
-- 檔案儲存在正確位置
-- 前端路徑轉換正確
-- Claude 能正確呼叫 multimodal-reader
-
-✅ **sh/deploy-gcp.sh 環境預期**：
-- 路徑結構與本地一致
-- 應能正常運作
-
-## 📝 後續建議
-
-1. **部署到 Cloud Run 後驗證**：
-   - 上傳檔案
-   - 確認檔案在 GCS 的 `uploads/` 子目錄下
-   - 測試多模態閱讀功能
-
-2. **更新相關文件**：
-   - 更新地雷經驗文件，記錄此次路徑統一修正
-   - 確保未來開發者知道本地與生產環境路徑結構一致
-
-## 🔗 相關檔案
-
-- 後端修正：`api/src/routes/upload.ts`
-- 前端修正：`web/components/chat-input.tsx`
-- 測試腳本：`api/test-chat-upload.sh`