botrun-horse 2.30.0 → 2.34.0

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

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

@@ -1,278 +0,0 @@
-# 前端 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`