# visionA-local 設計分析（第一輪）

> Design Agent · 第一階段三方聯合討論 · 2026-04-10
> 本文件為「分析」而非「規格」，目的是盤點現況、指出差異、收斂疑問。

---

## 1. 原 frontend 的盤點（edge-ai-platform）

### 1.1 現有頁面（`src/app/`）

| 路由 | 用途 | 去留 |
|------|------|------|
| `/`（Dashboard） | 概覽：模型數、裝置數、連線數、活動時間軸 | ✅ 保留，但需拿掉 cluster 相關統計 |
| `/models` | 模型庫：上傳、切換、比對 `.nef` | ✅ 保留 |
| `/devices` | USB Kneron 裝置列表、連線狀態、Flash | ✅ 保留 |
| `/clusters` | 叢集列表 / 建立叢集 | ❌ 砍 |
| `/workspace/[deviceId]` | 單裝置工作區：攝影機 + 模型 + 推論 | ✅ 保留（核心頁面） |
| `/workspace/cluster` | 叢集工作區 | ❌ 砍 |
| `/settings` | 設定頁 | ✅ 保留，需重新設計（見下） |

### 1.2 現有元件分類

| 分類 | 元件 | 去留 |
|------|------|------|
| `camera/` | camera-feed, camera-controls, camera-overlay, source-selector, camera-inference-view, batch-image-thumbnails | ✅ 全保留 |
| `devices/` | device-card, device-list, device-health-card, flash-dialog, flash-progress, device-connection-log, device-status | ✅ 全保留 |
| `models/` | model-card, model-grid, model-filters, model-upload-dialog, model-detail, model-comparison-dialog | ✅ 全保留 |
| `inference/` | inference-panel, classification-result, confidence-slider, performance-metrics, video-progress | ✅ 全保留 |
| `cluster/` | cluster-card, cluster-list, cluster-create-dialog, cluster-performance | ❌ 全砍 |
| `dashboard/` | stat-card, activity-timeline, connected-devices-list | ✅ 保留（拿掉 cluster 欄位） |
| `layout/` | sidebar, header, connection-status, help-button | ✅ 保留但需改寫（見第 2 節） |
| `onboarding-dialog.tsx`, `guided-tour.tsx` | 新手引導 | ✅ 保留並強化（First-Run） |
| `relay-token-sync.tsx` | Relay token 同步 | ❌ 砍 |
| `server-log-viewer.tsx`, `server-status-dashboard.tsx` | 後端狀態 | ✅ 保留（桌面 app 尤其需要） |
| `theme-sync.tsx`, `lang-sync.tsx`, `store-hydration.tsx` | 基礎設施 | ✅ 保留 |

### 1.3 Sidebar 改動
原 5 項導航去掉 `/clusters`，變成 4 項：Dashboard / Models / Devices / Settings。Logo 字母 `E` 應換成 visionA-local 品牌識別。

---

## 2. 從「網頁工具」到「桌面 app」的 UX 差異

| 維度 | 原 Web 版行為 | 桌面 app 應做的調整 |
|------|-------------|-------------------|
| **視窗外觀** | 瀏覽器 tab，有 URL bar、書籤列 | 原生視窗、無 URL bar、使用系統 window chrome；mac 可考慮 frameless + traffic lights |
| **啟動方式** | 使用者打開瀏覽器輸入 localhost:3721 | 雙擊 app icon 即開；可選開機自啟動（預設關） |
| **路由表達** | URL 是使用者心智模型 | URL 隱藏在內部，導航完全靠 sidebar；移除 deep link 依賴 |
| **背景常駐** | 關掉分頁 = 關掉工具 | 關閉視窗 ≠ 結束程式：收進 tray，server 持續運作 |
| **檔案互動** | 上傳透過 `<input type=file>` | 支援拖放到視窗任一處、支援「以 visionA-local 開啟」系統關聯 `.nef` / 圖片 |
| **選單列** | 瀏覽器選單 | 原生 menubar：File / Edit / View / Devices / Help，含快捷鍵 |
| **快捷鍵** | 瀏覽器佔用大量快捷鍵 | 釋放 ⌘N/⌘W/⌘, 等，對應到桌面 app 常見動作 |
| **主題** | 跟隨 Tailwind theme，手動切換 | 預設跟隨系統（light/dark/auto），記住偏好 |
| **通知** | 瀏覽器 Notification API（需授權） | 原生 OS 通知（mac Notification Center / Win toast / Linux libnotify） |
| **更新** | F5 就是最新 | 需要 in-app update 提醒（沿用 Wails updater 或自建） |
| **字級與密度** | 預設 web 字級 | 桌面 app 可略緊湊，但仍要遵守 44px 觸控目標（平板模式） |

---

## 3. 首次啟動體驗（First-Run）流程草案

使用者下載 `.dmg` / `.exe` / `.AppImage` → 安裝 → 第一次打開。建議流程（最多 3 步，可跳過）：

```
Step 1 — 歡迎畫面
  • visionA-local logo + 一句話 value prop
  • "開始使用" / "稍後再說"

Step 2 — 執行模式選擇
  • 🟢 真實硬體模式：插上 Kneron USB 裝置即可開始
  • 🟡 Mock 模式：沒有硬體也能探索功能（預設選項，降低門檻）
  • 可隨時在 Settings 切換

Step 3 — 硬體偵測（僅真實模式）
  • 自動掃描 USB 裝置
  • 成功 → 顯示偵測到的裝置卡片，CTA「前往 Workspace」
  • 失敗 → 顯示排錯清單（驅動、權限、USB3、重插）+「切換 Mock 模式」備案

完成後 → 進入 Dashboard，guided-tour 可選擇啟動
```

**設計重點：**
- 不強迫註冊、不要 email、不要網路。這是離線工具。
- Mock 模式作為「我先看看」的無摩擦入口，降低首次挫敗。
- 硬體偵測失敗要**主動給解法**，不要只顯示紅字。

---

## 4. Tray 互動設計建議

### 狀態圖示（menubar / systray）
| 狀態 | 圖示 | 說明 |
|------|------|------|
| Server 運行中，有裝置連線 | 🟢 實心 logo | 正常 |
| Server 運行中，無裝置 | ⚪ 淺色 logo | Idle |
| Server 啟動中 | 🔵 動態 pulse | Loading |
| Server 錯誤 | 🔴 logo + 驚嘆號 | 需使用者處理 |
| Mock 模式 | logo + 小 "M" badge | 與真實模式視覺區隔 |

### 點擊行為（平台差異）

| 平台 | 左鍵 | 右鍵 |
|------|------|------|
| macOS | 直接展開選單（mac 慣例，無左右之分） | — |
| Windows | 叫出主視窗（Win 慣例） | 展開選單 |
| Linux/GNOME | 展開選單（行為差異大，以選單為主） | 展開選單 |

### 選單項目（統一內容）
```
▸ 顯示 visionA-local      ⌘0
▸ Server 狀態：Running (localhost:3721)   [唯讀]
  ─────────
▸ 快速動作
  ├ 新增裝置…
  ├ 上傳模型…
  └ 開啟工作區
  ─────────
▸ 模式：● 真實  ○ Mock    [可切換]
▸ 開機自動啟動            [checkbox]
  ─────────
▸ 關於 visionA-local
▸ 檢查更新…
▸ 結束                    ⌘Q
```

---

## 5. 跨平台一致性的取捨

**原則：視覺統一 × 互動遵循平台慣例。**

| 項目 | 策略 |
|------|------|
| 色彩 / 字型 / 間距 / 元件樣式 | 跨平台完全一致（Design Tokens 統一） |
| 主視窗標題列 | mac frameless + traffic lights；win/linux 用標準 title bar（避免自畫 close button 的坑） |
| 快捷鍵修飾鍵 | mac 用 ⌘、win/linux 用 Ctrl；由 menu 定義，不手動寫字串 |
| 右鍵選單 | 原生 context menu（Wails runtime 提供） |
| 檔案對話框 | 原生 file picker，不自畫 |
| 通知 | 原生 OS 通知，訊息格式統一 |
| Tray 圖示尺寸 | mac 16pt template、win 16×16/32×32、linux 22×22，各自獨立資產 |
| 字型 | 跟隨系統字型（mac SF Pro、win Segoe UI、linux Inter/Ubuntu） |

**刻意不一致的地方：** 不要做自定義 title bar、不要覆寫原生選單，越原生越好。

---

## 6. 需要 PM / Architect 回答的問題

### 給 PM
1. **目標使用者**：主要是 Kneron 工程師內部使用？還是要給客戶 demo？這影響 First-Run 的技術門檻設定。
2. **Mock 模式的完整度**：Mock 是否要提供預錄的推論結果影片？還是可以完全用假資料？
3. **多語系**：原專案有 i18n（`useTranslation`），local 版要支援哪些語言？繁中 only 還是 en+zh？
4. **使用者資料**：模型、裝置設定存哪？`~/Library/Application Support/visionA-local/` 這類 OS 慣例目錄？
5. **錯誤回報**：是否要內建 feedback / 錯誤回報機制（匿名 telemetry）？

### 給 Architect
1. **單例鎖**：同一台機器同時開多個 visionA-local 視窗時，是否共用同一個後端 server？需要 single-instance lock。
2. **Port 衝突處理**：3721 被佔用時的 fallback 策略？UI 怎麼呈現？
3. **Tray 實作**：Wails v2 的 tray API 在 linux 上支援度如何？有無需要 systray fallback？
4. **檔案關聯**：要不要註冊 `.nef` 為 visionA-local 可開啟？這要寫進 installer。
5. **深色模式偵測**：Wails 能否偵測系統主題變更並即時 push 給前端？
6. **原生選單**：Wails 的 menu API 跨平台一致性如何？還是要各平台寫一份？

---

## 7. 需要使用者本人決定的設計向問題

| # | 問題 | 選項 |
|---|------|------|
| 1 | **品牌識別** | A. 直接沿用 edge-ai-platform 既有視覺（字母 E），只換名字 / B. 做一個新的 visionA-local logo 與色系 / C. 先用臨時 wordmark，上線前再處理 |
| 2 | **深色模式策略** | A. 預設跟隨系統 + 可手動覆寫（推薦） / B. 只提供 dark（技術工具常見） / C. 只提供 light |
| 3 | **首次啟動引導** | A. 強制走完 3 步歡迎流程 / B. 只顯示歡迎畫面，可一鍵跳過 / C. 完全跳過，直接進 Dashboard，用 tooltip 引導 |
| 4 | **Mock 模式預設** | A. 第一次啟動預設 Mock（零門檻）/ B. 第一次啟動預設真實硬體 / C. 強制使用者選擇 |
| 5 | **視窗關閉行為** | A. 關閉 = 收進 tray，server 繼續（像 Docker Desktop）/ B. 關閉 = 結束程式 / C. 讓使用者在 Settings 選擇 |
| 6 | **開機自啟動** | A. 預設關，使用者可開 / B. 首次啟動時詢問 / C. 預設開 |
| 7 | **多語系範圍** | 繁中 only / 繁中 + 英文 / 全部沿用原專案語言 |
| 8 | **Dashboard 去 cluster 後的排版** | A. 維持 4 個 stat card，把 cluster 換成別的指標（例：累計推論次數）/ B. 減為 3 個 stat card，讓版面更寬鬆 |
| 9 | **Tray 是否可選關閉** | A. Tray 是核心體驗，強制常駐 / B. Settings 可關閉 tray，改為傳統 app 模式 |
| 10 | **Settings 頁面改造程度** | A. 僅移除 relay/cluster 相關設定 / B. 重新設計為桌面 app 風格（分頁式：一般/硬體/模型/外觀/進階） |

---

## 下一步建議

1. 使用者先回答第 7 節的 10 個問題（尤其 1, 2, 3, 4, 5）
2. 並行進行：Architect 回答第 6 節的技術問題
3. 第二輪我會產出 IA（資訊架構圖）、First-Run 流程 wireframe、Tray 互動規格、Settings 分頁結構草案
4. 第三輪再進入完整 Design Tokens + 元件規格 + HTML Prototype