visionA/local-tool/.autoflow/03-design/design-analysis-round1.md

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