# 元件庫清單與規格 — visionA Cloud

> **本元件庫 100% 沿用 `local-tool/frontend/src/components/`**，Frontend Agent 實作時直接搬（或整併到 monorepo shared package）。本文件整理既有元件清單與用途，並定義雲端版**新增的 4 個元件**。

---

## 1. 元件分類總覽

| 類別 | 數量 | 來源 | 狀態 |
|------|------|------|------|
| 基礎 UI（Shadcn 風）| 22 | `src/components/ui/` | 沿用 |
| Layout | 4 | `src/components/layout/` | 沿用（Sidebar 需擴充） |
| Dashboard | 3 | `src/components/dashboard/` | 沿用 |
| Devices | 8 | `src/components/devices/` | 沿用（需擴充遠端狀態） |
| Models | 6 | `src/components/models/` | 沿用 |
| Inference | 5 | `src/components/inference/` | 沿用 |
| Camera | 多個 | `src/components/camera/` | 沿用 |
| 特殊 | 7 | 根目錄 | 沿用（部分可能棄用） |
| **雲端版新增** | 4 | `src/components/cloud/`（建議）| 本次新增 |

---

## 2. 基礎 UI 元件（沿用 Shadcn 風）

來源：`local-tool/frontend/src/components/ui/`

| 元件 | 檔案 | 用途 |
|------|------|------|
| `Button` | `button.tsx` | 6 variants（default / destructive / outline / secondary / ghost / link），8 sizes（xs / sm / default / lg / icon*3）|
| `Card` | `card.tsx` | 資訊容器（含 Header / Title / Description / Content / Footer / Action 子元件）|
| `Dialog` | `dialog.tsx` | Modal 對話框（Radix Dialog 封裝）|
| `AlertDialog` | `alert-dialog.tsx` | 確認危險操作的專用 Dialog（無法 ESC 關閉）|
| `Tabs` | `tabs.tsx` | 分頁切換（Radix Tabs 封裝）|
| `Input` | `input.tsx` | 單行文字輸入框，h-9 |
| `Select` | `select.tsx` | 下拉選單（Radix Select 封裝）|
| `Badge` | `badge.tsx` | 標籤徽章，6 variants |
| `Slider` | `slider.tsx` | 滑桿（Radix Slider 封裝，用於 confidence threshold）|
| `Progress` | `progress.tsx` | 進度條（Radix Progress） |
| `Checkbox` | `checkbox.tsx` | 多選框（Radix Checkbox） |
| `Label` | `label.tsx` | 表單標籤（Radix Label） |
| `Separator` | `separator.tsx` | 分隔線 |
| `ScrollArea` | `scroll-area.tsx` | 自訂滾動條（Radix ScrollArea） |
| `Sonner` | `sonner.tsx` | Toast 通知（Sonner 封裝） |
| `EmptyState` | `empty-state.tsx` | 空狀態頁面（Icon + Title + Description + Action） |

**狀態覆蓋（所有互動元件都需具備）：**

- Default / Hover / Active / Focus-visible / Disabled / Loading
- Focus-visible 使用 shadcn 預設 `ring-[3px]`（符合 WCAG AA）
- Disabled 統一 `disabled:pointer-events-none disabled:opacity-50`

---

## 3. Layout 元件（沿用 + 擴充）

來源：`local-tool/frontend/src/components/layout/`

| 元件 | 檔案 | 用途 | 雲端版變更 |
|------|------|------|-----------|
| `Header` | `header.tsx` | 頂部列：平台標題 + HelpButton + ConnectionStatus | 平台標題改「visionA Cloud」；ConnectionStatus 語義變更（見下） |
| `Sidebar` | `sidebar.tsx` | 左側導航：Dashboard / Models / Devices / Workspace / Settings | **新增**：底部 UserMenu；**新增**：`/clusters` 導航項 |
| `ConnectionStatus` | `connection-status.tsx` | 伺服器連線狀態徽章（綠 / 紅點）| 語義變更：local-tool 指「本機 server」，Cloud 指「雲端 API Server」|
| `HelpButton` | `help-button.tsx` | 開啟引導（driver.js tour）| Phase 0 保留，Phase 1 重寫內容為雲端版 |

### 3.1 Sidebar 變更規格（雲端版）

```
┌────────────────────────┐
│ [Logo] visionA Cloud   │  ← h-14，border-b
├────────────────────────┤
│ ▸ Dashboard            │
│ ▸ Models               │
│ ▸ Devices              │
│ ▸ Clusters      (new)  │  ← 新增
│ ▸ Workspace            │
│ ▸ Settings             │
│                        │
│  (flex-1)              │
│                        │
├────────────────────────┤
│ [avatar] username ▾    │  ← 新增 UserMenu（點開展示 Account / Sign out）
├────────────────────────┤
│ v0.1.0                 │
└────────────────────────┘
```

**導航項目（繁中 / English）：**

| i18n key | 繁中 | English | icon |
|---------|------|---------|------|
| `nav.dashboard` | 儀表板 | Dashboard | `LayoutDashboard` |
| `nav.modelLibrary` | 模型庫 | Models | `Boxes` |
| `nav.devices` | 裝置 | Devices | `Cable` |
| `nav.clusters` | 叢集 | Clusters | `Network` |
| `nav.workspace` | 工作區 | Workspace | `Play` |
| `nav.settings` | 設定 | Settings | `Settings` |

> **改動說明**：local-tool 目前用 `{ icon: 'H' }` 這種單字母佔位（見 `sidebar.tsx:13-18`），設計上不理想。Design Review 列為 **Minor**。**雲端版建議改用 Lucide Icon**，與產品視覺語言一致。

### 3.2 ConnectionStatus 語義變更

原 local-tool 的 `ConnectionStatus` 檢查 `fetch('/system/health')`，顯示「伺服器已連線」。

**雲端版需要區分兩層連線：**

| 層級 | 顯示位置 | 含義 | 綠 / 紅 / 黃 |
|------|---------|------|-------------|
| 雲端 API | Header 右側（現有位置）| 前端能不能打雲端 API Server | 綠：OK / 紅：API 不可達 |
| 遠端 Agent | 個別裝置卡片 / 詳情頁 | 該使用者的 local agent 有沒有連上雲端 | 綠：在線 / 灰：離線 / 黃：連線中 |

**Cloud 版 `ConnectionStatus` 行為：**

- 綠點 + 「已連線」→ 可以正常使用
- 紅點 + 「連線失敗，重試中」→ 整個服務不可用，顯示全域 `NetworkErrorBanner`
- 不再顯示 local-tool 的「伺服器未連線」— 雲端 API 應該永遠可達，失敗應觸發明顯警告

---

## 4. Dashboard 元件（沿用）

來源：`local-tool/frontend/src/components/dashboard/`

| 元件 | 用途 | 雲端版變更 |
|------|------|-----------|
| `StatCard` | 統計卡片（標題 + 數字 + icon） | 無 |
| `ActivityTimeline` | 近期活動時間軸 | 無（但資料來源從 local store 改為雲端事件）|
| `ConnectedDevicesList` | 已連線裝置列表（Dashboard 上的）| **小改動**：裝置項目要顯示「最後心跳 X 秒前」|

---

## 5. Devices 元件（沿用 + 擴充）

來源：`local-tool/frontend/src/components/devices/`

| 元件 | 用途 | 雲端版變更 |
|------|------|-----------|
| `DeviceList` | 裝置卡片網格 | 無 |
| `DeviceCard` | 單一裝置卡片（名稱、狀態、類型、韌體、已燒錄模型、操作按鈕）| **擴充**：右上角新增 `RemoteDeviceBadge`（見第 10 節）|
| `DeviceStatus` / `DeviceStatusBadge` | 狀態點 + 文字徽章 | **新增狀態**：`offline`（遠端掉線）、`reconnecting`（重連中） |
| `DeviceHealthCard` | 健康狀態（運行時間、韌體版本、最後活動）| **擴充**：新增「Pairing Token」、「最後心跳」欄位 |
| `DeviceConnectionLog` | 連線歷史紀錄 | 無（但雲端版 log 應包含 tunnel 事件） |
| `DeviceSettingsCard` | 裝置別名、備註 | 無 |
| `FlashDialog` | 燒錄模型對話框 | 無（行為透過 tunnel 傳到 local agent） |
| `FlashProgress` | 燒錄進度 | 無（WebSocket 透過雲端中繼） |

### 5.1 DeviceStatusBadge 擴充

**新增狀態（雲端版）：**

| 狀態 | 顏色 | i18n key | 文字（繁中）|
|------|------|---------|-----------|
| `offline` | `bg-gray-400` | `devices.status.offline` | 離線 |
| `reconnecting` | `bg-yellow-400 animate-pulse` | `devices.status.reconnecting` | 重新連線中 |

> 既有的 `detected` / `disconnected` 狀態在雲端版可能用不到（使用者不會直接「scan」遠端裝置）。雛形不刪除，但 UI 上會以 Pairing 流程取代 scan。

---

## 6. Models 元件（沿用，無變更）

來源：`local-tool/frontend/src/components/models/`

- `ModelCard` / `ModelGrid` / `ModelFilters` / `ModelDetail` / `ModelUploadDialog` / `ModelComparisonDialog`

雲端版行為差異：上傳 `.nef` 檔案走雲端儲存（S3-compat），但 UI 不變。

---

## 7. Inference 元件（沿用，無變更）

來源：`local-tool/frontend/src/components/inference/`

- `InferencePanel` / `PerformanceMetrics` / `ClassificationResult` / `VideoProgress` / `ConfidenceSlider`

雲端版行為差異：推論結果透過 WebSocket 從 local agent → 雲端 → 瀏覽器。UI 不變。

---

## 8. Camera 元件（沿用，無變更）

來源：`local-tool/frontend/src/components/camera/`

- `CameraInferenceView` / `CameraControls` / `SourceSelector` / `BatchImageThumbnails` 等

**雲端版注意：**
- Camera stream 仍然走 local agent（硬體存取）
- MJPEG stream 透過 tunnel 從 local agent → 雲端 → 瀏覽器顯示
- Image / Video 上傳：Phase 0 仍走 local agent 處理；Phase 1+ 考慮直上雲端

---

## 9. 特殊元件（部分調整）

來源：`local-tool/frontend/src/components/`

| 元件 | 用途 | 雲端版變更 |
|------|------|-----------|
| `OnboardingDialog` | 首次訪問引導 Dialog | **Phase 0 暫時保留**；Phase 1 重寫（現版本假設「插 USB Dongle」，雲端不適用）|
| `GuidedTour` | driver.js 步驟引導 | **Phase 0 暫時保留**；Phase 1 重寫為 Cloud Tour |
| `ServerStatusDashboard` | 後端 Go runtime 狀態 | **Phase 0 可移除 or 隱藏**（使用者看不到雲端 runtime）；留供 Phase 1 重新定位 |
| `ServerLogViewer` | 伺服器即時日誌 | 同上 |
| `LangSync` | 語言狀態同步 | 無變更 |
| `ThemeSync` | 主題跟隨系統 | 無變更 |
| `StoreHydration` | Zustand store hydration | 無變更 |

---

## 10. 雲端版新增元件

**建議路徑**：`visionA-frontend/src/components/cloud/`

### 10.1 `UserMenu`

**用途**：Sidebar 底部的使用者選單，雲端版必備。

**視覺**：
```
┌──────────────────────────┐
│  [avatar] jim@example.com  ▾  │  ← trigger
└──────────────────────────┘
          ↓ click
┌──────────────────────────┐
│  帳號設定 (Account)         │
│  語言切換 (Language)        │
│  ───────────────          │
│  登出 (Sign out)           │
└──────────────────────────┘
```

**規格：**
- 基底元件：Radix DropdownMenu（shadcn 封裝）
- Trigger：Button variant=ghost，size=default
- Avatar：40px 圓形（`rounded-full`），顯示使用者 Email 首字母 or GravatarURL
- 下拉位置：`side="top" align="start"`（展開往上）
- 項目圖示：Lucide `UserCog` / `Globe` / `LogOut`

**i18n key：**
- `account.menu.accountSettings`
- `account.menu.language`
- `account.menu.signOut`

**雛形簡化**：Phase 0 `signOut` 直接跳回 `/login`（不接 API）；`account.menu.accountSettings` 跳 `/account` stub 頁。

**無障礙：**
- Trigger 可 Tab 聚焦、Enter / Space 展開
- 下拉內容鍵盤可 Arrow 導航
- `aria-label` = 使用者 Email

---

### 10.2 `PairingTokenCard`

**用途**：`/devices/pair` 頁面的主要卡片，展示 Pairing Token 並提供複製功能。

**視覺**：
```
┌────────────────────────────────────────────────┐
│  🔗  Pairing Token                              │
│                                                 │
│  使用這組 token 讓你的 local agent 連上雲端      │
│  ───────────────────────────────────────        │
│                                                 │
│   ┌────────────────────────────────────────┐   │
│   │  vAc_a1b2c3d4e5f6a7b8                    │   │
│   │  c9d0e1f2a3b4c5d6e7f8                    │   │
│   │  (vAc_ + 32 hex，視覺切兩行；            │   │
│   │   複製為完整 36 字元無空格)              │   │
│   └────────────────────────────────────────┘   │
│                                                 │
│   [📋 複製]  [🔄 重新產生]                       │
│                                                 │
│   ⏱ 剩餘 14:52 ────────────────                  │
│     (進度條 bg-primary → amber(≤10:00)           │
│      → red(≤3:00)；過期轉灰 disabled)            │
│   📅 產生時間：14:30                             │
└────────────────────────────────────────────────┘
```

**規格：**
- 基底：`Card` + CardHeader + CardContent + CardFooter
- Token 格式：`vAc_` + 32 字元 hex（總長 36），TTL **15 分鐘**，一次性使用
- Token 顯示區：`bg-muted font-mono text-xl tracking-wider p-4 rounded-md select-all`
  - 視覺切兩行（第 1 行 `vAc_` + 16 hex，第 2 行 16 hex）；Mobile 降為 `text-lg`
  - 複製到剪貼簿永遠是**完整 36 字元無空格無換行**
  - 過期狀態：`text-muted-foreground line-through`
- 複製按鈕：`variant=default` + Lucide `Copy` icon；按下後暫態改為「已複製 ✓」2 秒，伴隨 toast；過期時 disabled
- 重新產生：`variant=outline` + Lucide `RefreshCw`；點擊後 AlertDialog 確認「重新產生會讓舊 token 失效，新 token 有效期 15 分鐘」
- 倒數計時器（15 分鐘 TTL 必備）：
  - 格式 `mm:ss`，1 秒更新一次
  - 進度條 `h-1.5 w-full`，初始 `bg-primary`，≤ 10:00 → `bg-amber-500`，≤ 3:00 → `bg-red-500` 且卡片加 `ring-1 ring-red-300`
  - ≤ 0:30 發一次 Toast「Token 即將過期」
  - 0:00 自動切過期狀態；主 CTA 變「重新產生 token」

**互動：**
- 按複製：`navigator.clipboard.writeText(token)` + `showSuccess(t('pairing.copied'))`
- 按重新產生：開 AlertDialog，確認後呼叫 API → 更新 token + 重置計時

**i18n key：**
- `pairing.tokenTitle`
- `pairing.tokenDescription`
- `pairing.copy` / `pairing.copied` / `pairing.regenerate`
- `pairing.expiresIn` / `pairing.generatedAt`
- `pairing.regenerateConfirm` / `pairing.regenerateWarning`

**無障礙：**
- Token 區塊：`aria-label="Pairing token"`，`role="text"`
- 複製按鈕：Enter / Space 可觸發
- 重新產生：AlertDialog 的焦點陷阱（shadcn 內建）

---

### 10.3 `RemoteDeviceBadge`

**用途**：在雲端場景下顯示單一遠端裝置的連線狀態，取代 / 擴充既有 `DeviceStatusBadge`。

**視覺變體：**

```
🟢 在線                    ← bg-green-500 + 文字
🟡 重新連線中 (pulse)       ← bg-yellow-400 animate-pulse
⚪ 離線・最後心跳 2 分鐘前   ← bg-gray-400 + 文字 + 次要文字（timestamp）
🔴 錯誤・無法建立 tunnel     ← bg-red-500 + 文字 + tooltip 顯示錯誤詳情
```

**規格：**
- 基底：`div.flex.items-center.gap-2`
- 狀態點：`h-2.5 w-2.5 rounded-full`（沿用 `DeviceStatusBadge` 樣式）
- 狀態文字：`text-sm`
- 次要資訊（最後心跳）：`text-xs text-muted-foreground`
- `pulse` 狀態：`animate-pulse` class

**Props：**

```tsx
interface RemoteDeviceBadgeProps {
  status: 'online' | 'offline' | 'reconnecting' | 'error';
  lastSeenAt?: string;      // ISO 8601 timestamp
  errorMessage?: string;    // tooltip 顯示
  size?: 'sm' | 'md';       // 預設 md
}
```

**使用情境：**
- `/devices` 裝置卡片右上角（取代 `DeviceStatusBadge`）
- `/devices/[id]` 裝置詳情頁的大型狀態顯示（size=md）
- Dashboard `ConnectedDevicesList` 的每個項目右側
- `/workspace/[deviceId]` 頂部（裝置掉線時要能即時看到）

**i18n key（新增）：**
- `remote.status.online` → 在線
- `remote.status.offline` → 離線
- `remote.status.reconnecting` → 重新連線中
- `remote.status.error` → 連線錯誤
- `remote.lastSeen` → 最後心跳 {time}
- `remote.lastSeenNever` → 從未連線

**無障礙：**
- 角色：`role="status"` + `aria-live="polite"`（狀態改變時通知 SR）
- 不只靠顏色：圓點 + 文字雙保險
- 錯誤狀態提供 `aria-describedby` 指向 tooltip 的完整訊息

**時間格式化（建議用 `date-fns` 或輕量 util）：**
- < 60 秒 → 「剛剛」
- < 60 分 → 「X 分鐘前」
- < 24 時 → 「X 小時前」
- ≥ 24 時 → 絕對時間「04/20 14:30」

---

### 10.4 `NetworkErrorBanner`

**用途**：全域警告橫幅，當雲端 API 不可達時顯示於 Header 下方。

**視覺**：
```
┌────────────────────────────────────────────────────────┐
│ ⚠  連線中斷 — 無法連上雲端服務。正在重試...  [立即重試]  │
└────────────────────────────────────────────────────────┘
```

**規格：**
- 背景：`bg-amber-50 dark:bg-amber-950/30`
- 邊框：`border-b border-amber-300 dark:border-amber-700`
- 文字：`text-amber-800 dark:text-amber-200 text-sm`
- 圖示：Lucide `AlertTriangle`，`text-amber-600`
- 位置：Header 下方 sticky（`sticky top-14 z-40`）
- 右側按鈕：`Button variant=outline size=sm`

**狀態變化：**
- API 正常 → 不顯示
- API 失敗 > 3 次連續 → 顯示 banner
- API 恢復 → banner 切換為「已恢復連線」短暫顯示 3 秒後消失

**i18n key：**
- `network.disconnected.title` → 連線中斷
- `network.disconnected.description` → 無法連上雲端服務。正在重試...
- `network.disconnected.retryButton` → 立即重試
- `network.restored` → 已恢復連線 ✓

**無障礙：**
- `role="alert"` + `aria-live="assertive"`（重要警告）
- 重試按鈕：`aria-label="重試連線"`

---

## 11. 元件狀態覆蓋檢查表（給 Frontend QA 與 Design QA）

每個互動元件都應有以下狀態：

| 狀態 | 所有按鈕 / Input | 卡片列表 | 頁面 | 資料載入 |
|------|-----------------|---------|------|---------|
| Default | ✅ | ✅ | ✅ | — |
| Hover | ✅ | ✅（整個卡片）| — | — |
| Active / Pressed | ✅ | — | — | — |
| Focus-visible | ✅ | ✅ | — | — |
| Disabled | ✅ | — | — | — |
| Loading | ✅（Loader2 icon）| ✅（skeleton）| ✅（skeleton）| ✅（skeleton）|
| Empty | — | ✅（EmptyState）| ✅（EmptyState）| — |
| Error | — | ✅（error banner）| ✅（error page）| ✅（retry）|
| Success | ✅（toast）| — | — | — |

---

## 12. UX Writing 規範（簡版，完整版見 Flow 子檔）

**產品語調：**
- 對象是開發者，可用技術術語（如「Pairing Token」、「tunnel」、「session」）但不濫用
- 錯誤訊息要**說清楚發生什麼事 + 使用者能做什麼**
- 避免過度客氣（不需要「請」「您」滿天飛）
- 繁中台灣用語（不用「鏈接」用「連結」；不用「您」頻繁出現）

**常用文案（整合到 i18n）：**

| 場景 | 繁中 | English |
|------|------|---------|
| 載入中 | 載入中... | Loading... |
| 儲存成功 | 已儲存 | Saved |
| 儲存失敗 | 儲存失敗，請重試 | Save failed, please retry |
| 刪除確認 | 確定要刪除「{name}」嗎？此操作無法復原。 | Delete "{name}"? This cannot be undone. |
| 空列表 | 還沒有任何紀錄 | Nothing here yet |
| API 錯誤 | 連線失敗，請檢查網路或稍後再試 | Connection failed, check network or try later |
| 權限不足 | 沒有權限進行此操作 | No permission for this action |
| Session 過期 | 登入已過期，請重新登入 | Session expired, please sign in |

---

## 13. 實作建議（給 Frontend Agent）

1. **Monorepo 結構**：若 `visionA-frontend` 與 `local-tool` 之後都在同 repo，可抽出 `packages/ui/`、`packages/i18n/` 共用，避免重複。Phase 0 不需要，直接複製即可。
2. **新元件檔案放 `src/components/cloud/`**，命名清晰，不要與既有元件混放。
3. **測試**：新增的元件（`UserMenu`、`PairingTokenCard`、`RemoteDeviceBadge`、`NetworkErrorBanner`）都要有對應 Vitest 測試。
4. **Storybook / Playground**：Phase 0 不要求；Phase 1 考慮引入 Storybook。