botrun-horse 2.29.2 → 2.30.0

package/botrun-c/design/google-drive/02-api-design.md

@@ -0,0 +1,314 @@
+# API 端點設計
+
+## 端點總覽
+
+| Method | Endpoint | 說明 |
+|--------|----------|------|
+| GET | `/api/gdrive/folders` | 列出已加入的資料夾 |
+| POST | `/api/gdrive/folders` | 新增資料夾 |
+| PUT | `/api/gdrive/folders/:id` | 更新資料夾設定 |
+| DELETE | `/api/gdrive/folders/:id` | 移除資料夾 |
+| POST | `/api/gdrive/sync` | 同步選定資料夾 |
+| GET | `/api/gdrive/history` | 最近 10 個網址 |
+
+---
+
+## GET /api/gdrive/folders
+
+列出使用者已加入的所有 Google Drive 資料夾。
+
+### Request
+
+```http
+GET /api/gdrive/folders
+Authorization: Bearer {token}
+```
+
+### Response (200 OK)
+
+```json
+{
+  "success": true,
+  "folders": [
+    {
+      "id": "1abc123def456",
+      "url": "https://drive.google.com/drive/folders/1abc123def456",
+      "alias": "專案文件",
+      "type": "service-account",
+      "lastSync": "2025-12-21T10:00:00Z",
+      "fileCount": 42,
+      "totalSize": "128MB",
+      "selected": true,
+      "syncStatus": "synced"
+    }
+  ],
+  "history": [
+    "https://drive.google.com/drive/folders/xxx",
+    "https://drive.google.com/drive/folders/yyy"
+  ]
+}
+```
+
+### 欄位說明
+
+| 欄位 | 類型 | 說明 |
+|------|------|------|
+| `id` | string | Google Drive folder ID |
+| `url` | string | 完整 URL |
+| `alias` | string | 使用者自訂別名 |
+| `type` | enum | `public` / `service-account` |
+| `lastSync` | ISO8601 | 最後同步時間 |
+| `fileCount` | number | 檔案數量 |
+| `totalSize` | string | 總大小 (human-readable) |
+| `selected` | boolean | 是否選中（用於問答） |
+| `syncStatus` | enum | `synced` / `syncing` / `error` / `pending` |
+
+---
+
+## POST /api/gdrive/folders
+
+新增 Google Drive 資料夾。
+
+### Request
+
+```http
+POST /api/gdrive/folders
+Authorization: Bearer {token}
+Content-Type: application/json
+
+{
+  "url": "https://drive.google.com/drive/folders/1abc123def456",
+  "type": "public",
+  "alias": "專案文件"
+}
+```
+
+### Request Body
+
+| 欄位 | 類型 | 必填 | 說明 |
+|------|------|------|------|
+| `url` | string | ✅ | Google Drive 資料夾 URL |
+| `type` | enum | ❌ | `public` (預設) / `service-account` |
+| `alias` | string | ❌ | 自訂別名 |
+
+### Response (201 Created)
+
+```json
+{
+  "success": true,
+  "folder": {
+    "id": "1abc123def456",
+    "url": "https://drive.google.com/drive/folders/1abc123def456",
+    "alias": "專案文件",
+    "type": "public",
+    "fileCount": 0,
+    "syncStatus": "pending"
+  },
+  "message": "資料夾已新增，請點擊同步開始下載"
+}
+```
+
+### Error Responses
+
+| Code | 說明 |
+|------|------|
+| 400 | 無效的 URL 格式 |
+| 403 | 無權限存取此資料夾 |
+| 409 | 資料夾已存在 |
+
+---
+
+## PUT /api/gdrive/folders/:id
+
+更新資料夾設定（別名、選中狀態）。
+
+### Request
+
+```http
+PUT /api/gdrive/folders/1abc123def456
+Authorization: Bearer {token}
+Content-Type: application/json
+
+{
+  "alias": "新的別名",
+  "selected": true
+}
+```
+
+### Response (200 OK)
+
+```json
+{
+  "success": true,
+  "folder": {
+    "id": "1abc123def456",
+    "alias": "新的別名",
+    "selected": true
+  }
+}
+```
+
+---
+
+## DELETE /api/gdrive/folders/:id
+
+移除資料夾（同時刪除本地快取）。
+
+### Request
+
+```http
+DELETE /api/gdrive/folders/1abc123def456
+Authorization: Bearer {token}
+```
+
+### Query Parameters
+
+| 參數 | 類型 | 說明 |
+|------|------|------|
+| `keepCache` | boolean | 是否保留本地快取（預設 false） |
+
+### Response (200 OK)
+
+```json
+{
+  "success": true,
+  "message": "資料夾已移除",
+  "deletedCache": true
+}
+```
+
+---
+
+## POST /api/gdrive/sync
+
+同步選定的資料夾。
+
+### Request
+
+```http
+POST /api/gdrive/sync
+Authorization: Bearer {token}
+Content-Type: application/json
+
+{
+  "folderIds": ["1abc123def456", "2xyz789ghi012"],
+  "force": false
+}
+```
+
+### Request Body
+
+| 欄位 | 類型 | 必填 | 說明 |
+|------|------|------|------|
+| `folderIds` | string[] | ❌ | 要同步的資料夾（空 = 全部） |
+| `force` | boolean | ❌ | 強制重新同步（忽略 modifiedTime） |
+
+### Response (200 OK) - 同步完成
+
+```json
+{
+  "success": true,
+  "results": [
+    {
+      "folderId": "1abc123def456",
+      "status": "synced",
+      "filesUpdated": 5,
+      "filesSkipped": 37,
+      "filesDeleted": 2,
+      "duration": 3500
+    }
+  ],
+  "summary": {
+    "totalFolders": 1,
+    "totalFiles": 42,
+    "totalSize": "128MB"
+  }
+}
+```
+
+### Response (202 Accepted) - 背景同步
+
+大型資料夾會在背景同步，回傳進度 ID：
+
+```json
+{
+  "success": true,
+  "status": "syncing",
+  "progressId": "sync-123456",
+  "message": "同步已開始，預計需要 2 分鐘"
+}
+```
+
+---
+
+## GET /api/gdrive/history
+
+取得最近使用的 10 個 URL。
+
+### Request
+
+```http
+GET /api/gdrive/history
+Authorization: Bearer {token}
+```
+
+### Response (200 OK)
+
+```json
+{
+  "success": true,
+  "history": [
+    {
+      "url": "https://drive.google.com/drive/folders/xxx",
+      "alias": "專案文件",
+      "lastUsed": "2025-12-21T10:00:00Z"
+    }
+  ]
+}
+```
+
+---
+
+## 支援的 URL 格式
+
+API 自動解析以下 URL 格式：
+
+```
+# 標準資料夾 URL
+https://drive.google.com/drive/folders/{folderId}
+
+# 分享連結
+https://drive.google.com/drive/folders/{folderId}?usp=sharing
+
+# 短連結（需解析重定向）
+https://drive.google.com/open?id={folderId}
+
+# ZIP 檔案
+https://drive.google.com/file/d/{fileId}/view
+```
+
+---
+
+## 錯誤回應格式
+
+所有錯誤回應遵循統一格式：
+
+```json
+{
+  "success": false,
+  "error": "錯誤訊息",
+  "code": "ERROR_CODE",
+  "details": {}
+}
+```
+
+### 錯誤碼
+
+| Code | HTTP Status | 說明 |
+|------|-------------|------|
+| `INVALID_URL` | 400 | 無效的 Google Drive URL |
+| `FOLDER_NOT_FOUND` | 404 | 找不到資料夾 |
+| `ACCESS_DENIED` | 403 | 無權限存取 |
+| `FOLDER_EXISTS` | 409 | 資料夾已存在 |
+| `SYNC_FAILED` | 500 | 同步失敗 |
+| `QUOTA_EXCEEDED` | 429 | 超過 API 配額 |

package/botrun-c/design/google-drive/03-frontend-design.md

@@ -0,0 +1,278 @@
+# 前端 UI 設計
+
+## 元件架構
+
+```
+web/
+├── components/
+│   ├── gdrive/
+│   │   ├── gdrive-selector.tsx       # 右上角選單（桌面）
+│   │   ├── gdrive-drawer.tsx         # 底部抽屜（手機）
+│   │   ├── gdrive-folder-list.tsx    # 資料夾列表
+│   │   ├── gdrive-folder-item.tsx    # 單一資料夾項目
+│   │   ├── gdrive-add-dialog.tsx     # 新增對話框
+│   │   └── gdrive-sync-status.tsx    # 同步狀態指示器
+│   └── ...
+├── hooks/
+│   ├── useGdriveFolders.ts           # 資料夾 CRUD
+│   ├── useGdriveSync.ts              # 同步狀態
+│   └── useGdriveHistory.ts           # 歷史記錄
+└── lib/
+    └── gdrive-storage.ts             # localStorage 工具
+```
+
+## 元件設計
+
+### 1. GdriveSelector（桌面版）
+
+位於右上角的下拉選單，顯示已加入的資料夾列表。
+
+```tsx
+interface GdriveSelectorProps {
+  className?: string;
+}
+
+// 功能：
+// - 顯示已選中的資料夾名稱
+// - 下拉顯示所有資料夾
+// - 快速切換選中狀態
+// - 新增資料夾入口
+// - 同步按鈕
+```
+
+**UI 草圖**：
+```
+┌─────────────────────────────────┐
+│ [📁 專案文件 ▼]  [🔄]           │
+├─────────────────────────────────┤
+│ ☑️ 專案文件     42 檔案  128MB  │
+│ ☐ 參考資料     15 檔案   25MB  │
+│ ☐ 會議記錄      8 檔案   12MB  │
+│─────────────────────────────────│
+│ [+ 新增資料夾]                  │
+└─────────────────────────────────┘
+```
+
+### 2. GdriveDrawer（手機版）
+
+底部抽屜式選單，適合手機觸控操作。
+
+```tsx
+interface GdriveDrawerProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+}
+
+// 功能：
+// - 底部滑出的抽屜
+// - 大按鈕易於觸控
+// - 支援拖拉關閉
+```
+
+**UI 草圖**：
+```
+┌─────────────────────────────────┐
+│ ─────  (拖拉條)                 │
+├─────────────────────────────────┤
+│ Google Drive 資料夾             │
+│                                 │
+│ ┌─────────────────────────────┐ │
+│ │ 📁 專案文件                 │ │
+│ │ 42 檔案 · 128MB · ✅ 已同步  │ │
+│ └─────────────────────────────┘ │
+│                                 │
+│ ┌─────────────────────────────┐ │
+│ │ 📁 參考資料                 │ │
+│ │ 15 檔案 · 25MB · ⏳ 待同步   │ │
+│ └─────────────────────────────┘ │
+│                                 │
+│ ┌─────────────────────────────┐ │
+│ │ [+ 新增資料夾]              │ │
+│ └─────────────────────────────┘ │
+│                                 │
+│ [🔄 同步全部]                   │
+└─────────────────────────────────┘
+```
+
+### 3. GdriveFolderList
+
+資料夾列表元件，支援多選和排序。
+
+```tsx
+interface GdriveFolderListProps {
+  folders: GdriveFolder[];
+  selectedIds: string[];
+  onSelect: (id: string, selected: boolean) => void;
+  onDelete: (id: string) => void;
+  onEdit: (id: string) => void;
+}
+```
+
+### 4. GdriveAddDialog
+
+新增資料夾的對話框。
+
+```tsx
+interface GdriveAddDialogProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  onAdd: (url: string, alias?: string) => Promise<void>;
+  history: string[];  // 最近 10 個網址
+}
+```
+
+**UI 草圖**：
+```
+┌───────────────────────────────────────┐
+│ 新增 Google Drive 資料夾              │
+├───────────────────────────────────────┤
+│                                       │
+│ 資料夾網址 *                          │
+│ ┌───────────────────────────────────┐ │
+│ │ https://drive.google.com/...      │ │
+│ └───────────────────────────────────┘ │
+│                                       │
+│ 最近使用：                            │
+│ • 專案文件 (3 天前)                   │
+│ • 參考資料 (1 週前)                   │
+│                                       │
+│ 別名（選填）                          │
+│ ┌───────────────────────────────────┐ │
+│ │ 例如：專案文件                     │ │
+│ └───────────────────────────────────┘ │
+│                                       │
+│ ☐ 這是公開資料夾（無需權限）          │
+│                                       │
+│         [取消]  [新增並同步]          │
+└───────────────────────────────────────┘
+```
+
+## Hooks 設計
+
+### useGdriveFolders
+
+管理資料夾列表的 CRUD 操作。
+
+```tsx
+interface UseGdriveFoldersReturn {
+  // 狀態
+  folders: GdriveFolder[];
+  isLoading: boolean;
+  error: Error | null;
+
+  // 操作
+  addFolder: (url: string, alias?: string, type?: 'public' | 'service-account') => Promise<void>;
+  removeFolder: (id: string) => Promise<void>;
+  updateFolder: (id: string, updates: Partial<GdriveFolder>) => Promise<void>;
+  toggleSelect: (id: string) => Promise<void>;
+
+  // 重新載入
+  refetch: () => Promise<void>;
+}
+
+function useGdriveFolders(): UseGdriveFoldersReturn {
+  // 實作...
+}
+```
+
+### useGdriveSync
+
+管理同步狀態。
+
+```tsx
+interface UseGdriveSyncReturn {
+  // 狀態
+  isSyncing: boolean;
+  syncProgress: SyncProgress | null;
+  lastSyncTime: Date | null;
+
+  // 操作
+  syncAll: () => Promise<void>;
+  syncFolder: (folderId: string) => Promise<void>;
+  cancelSync: () => void;
+}
+
+interface SyncProgress {
+  folderId: string;
+  folderName: string;
+  current: number;
+  total: number;
+  status: 'downloading' | 'converting' | 'indexing';
+}
+```
+
+### useGdriveHistory
+
+管理最近使用的 URL 歷史。
+
+```tsx
+interface UseGdriveHistoryReturn {
+  history: HistoryItem[];
+  addToHistory: (url: string, alias?: string) => void;
+  clearHistory: () => void;
+}
+
+interface HistoryItem {
+  url: string;
+  alias?: string;
+  lastUsed: Date;
+}
+```
+
+## 狀態管理
+
+使用 React Context + localStorage 持久化：
+
+```tsx
+// contexts/GdriveContext.tsx
+interface GdriveContextValue {
+  folders: GdriveFolder[];
+  selectedIds: string[];
+  history: HistoryItem[];
+  // ...
+}
+
+// localStorage keys
+const STORAGE_KEYS = {
+  HISTORY: 'gdrive-history',      // 最近 10 個網址
+  SELECTED: 'gdrive-selected',    // 選中的資料夾 IDs
+};
+```
+
+## 響應式設計
+
+```tsx
+// 根據螢幕寬度自動切換
+function GdriveManager() {
+  const { isMobile } = useCapacitorPlatform();
+
+  if (isMobile) {
+    return <GdriveDrawer />;
+  }
+
+  return <GdriveSelector />;
+}
+```
+
+## 整合位置
+
+在 `ChatPage.tsx` 的右上角新增入口：
+
+```tsx
+// ChatPage.tsx 修改
+<div className="flex items-center gap-2">
+  <GdriveSelector />  {/* 新增 */}
+  <DropdownMenu>
+    {/* 現有的選單 */}
+  </DropdownMenu>
+</div>
+```
+
+## 樣式指南
+
+遵循現有 shadcn/ui 設計系統：
+
+- 使用 `Button`, `Dialog`, `DropdownMenu` 等現有元件
+- 配色跟隨主題（dark/light mode）
+- 間距使用 Tailwind 標準（4px 倍數）
+- 動畫使用 `transition-all duration-200`