visionA/local-tool/.autoflow/03-design/spec/04-first-run.md

04 — First-Run Experience 詳細流程

4.1 觸發條件

• 資料目錄下 config.json 的 firstRunCompleted != true
  • macOS：~/Library/Application Support/visiona-local/config.json
  • Windows：%APPDATA%\visiona-local\config.json
  • Linux：~/.local/share/visiona-local/config.json

（資料目錄名稱於第四輪 R4-5 統一為全小寫 visiona-local，對齊 Bundle ID 與 Linux 慣例。）

• 或使用者從 Settings > 進階 手動觸發「重新顯示歡迎流程」

完成條件：三步流程跑到最後一步 或 使用者點任一步驟的「略過」。

4.2 流程概覽

[啟動 App]
    ↓
[Step 1] 歡迎畫面 ────→ [略過] ──┐
    ↓ 繼續                        │
[Step 2] 模式選擇 ────→ [略過] ──┤
    ↓ 繼續                        │
[Step 3] 硬體偵測 ────→ [略過] ──┤
    ↓ 完成                        │
                                  ↓
                            [Dashboard]

重點：每一步右上角都有「略過」，點了直接跳到 Dashboard，不強制走完。

4.3 Step 1 — 歡迎畫面

佈局

┌─────────────────────────────────────────────────────┐
│                                           [略過 →]  │
│                                                     │
│              [visionA logo 128px]                   │
│                                                     │
│            歡迎使用 visionA-local                   │
│       在你的電腦上跑 Kneron AI 推論                 │
│                                                     │
│      ✓ 完全離線 — 不需網路                          │
│      ✓ 一鍵安裝 — 所有依賴已內建                    │
│      ✓ 支援 Kneron KL520 / KL720 / KL730            │
│                                                     │
│                                                     │
│  ⓘ 剛才你可能看到系統的安全警告——那是因為我們是    │
│    內部工具、未購買程式碼簽章憑證。是安全的。        │
│                                                     │
│              [讓我開始使用 →]                        │
│                                                     │
│                     1 / 3                           │
└─────────────────────────────────────────────────────┘

元件與規格

• 視窗尺寸：1024×720（固定，居中）
• Logo：沿用 edge-ai-platform（原檔案 frontend/public/logo.svg 或類似）
• 標題：h1 32px / font-semibold
• Value prop 清單：3 行，icon + 文字
• 簽章警示說明區塊：淺色背景卡片，info icon，自動顯示（不需偵測）
• CTA：button.primary size=lg，footer 顯示「1 / 3」進度
• 右上略過：ghost button size=sm

互動

• 「讓我開始使用」→ Step 2
• 「略過」→ 跳到 Dashboard，並寫 firstRunCompleted = true
• ⌘Q 可立即結束 App

---

4.4 Step 2 — 模式選擇

佈局

┌─────────────────────────────────────────────────────┐
│                                           [略過 →]  │
│                                                     │
│              選擇執行模式                            │
│         你隨時可以在 Settings 切換                  │
│                                                     │
│   ┌──────────────────┐  ┌──────────────────┐       │
│   │      🔌          │  │      🧪          │       │
│   │                  │  │                  │       │
│   │   真實硬體模式    │  │    Mock 模式     │       │
│   │   (推薦)         │  │                  │       │
│   │                  │  │                  │       │
│   │ 連接實體 Kneron  │  │ 用預設假資料體驗 │       │
│   │ USB 裝置，跑真實 │  │ 產品功能，不需要 │       │
│   │ AI 推論          │  │ 硬體             │       │
│   │                  │  │                  │       │
│   │ [●] 選取          │  │ [○] 選取          │       │
│   └──────────────────┘  └──────────────────┘       │
│                                                     │
│                                                     │
│              [← 返回]    [繼續 →]                    │
│                                                     │
│                     2 / 3                           │
└─────────────────────────────────────────────────────┘

規格

• 兩張 card.selectable，240×320，圓角 12px
• 預設選取：真實硬體模式（依決策 Q8）
• 選中狀態：border 2px color.primary，背景 color.primary.subtle
• 「推薦」badge 顯示在真實硬體卡片右上角
• 點整張卡片 = 選取（不需要精準點 radio button）

互動

• 「繼續」→ 如選真實模式進 Step 3；如選 Mock 則跳過 Step 3 直接進 Dashboard 並顯示 Mock badge
• 「返回」→ Step 1
• 鍵盤：← → 切換選取；Enter 繼續

---

4.5 Step 3 — 硬體偵測（僅真實模式）

Phase 1：掃描中

┌─────────────────────────────────────────────────────┐
│                                           [略過 →]  │
│                                                     │
│              偵測 Kneron 裝置                        │
│                                                     │
│                    ⟳                                │
│             正在掃描 USB 裝置...                     │
│                                                     │
│            [■■■■■■□□□□] 60%                         │
│                                                     │
│                                                     │
│                                                     │
│                     3 / 3                           │
└─────────────────────────────────────────────────────┘

Phase 2A：偵測成功

┌─────────────────────────────────────────────────────┐
│                                                     │
│         ✓ 偵測到 2 顆 Kneron 裝置                   │
│                                                     │
│   ┌──────────────┐  ┌──────────────┐               │
│   │ 🟢 KL720-A   │  │ 🟢 KL520-B   │               │
│   │ FW 2.1.0     │  │ FW 1.8.3     │               │
│   └──────────────┘  └──────────────┘               │
│                                                     │
│                                                     │
│        [前往 Dashboard]  [前往 Workspace →]         │
│                                                     │
└─────────────────────────────────────────────────────┘

Phase 2B：偵測失敗（無裝置）

┌─────────────────────────────────────────────────────┐
│                                                     │
│         ⚠ 沒有偵測到 Kneron 裝置                    │
│                                                     │
│   可能的原因：                                       │
│   • 裝置還沒接上 USB                                │
│   • USB 線只能供電不能傳輸 (試換一條)                │
│   • macOS: 第一次連接需要允許權限                    │
│   • Windows: 需要安裝 WinUSB driver                 │
│   • Linux: 需要 libusb + udev rules                 │
│                                                     │
│         [🔄 重新掃描]  [使用 Mock 模式]              │
│                         [繼續到 Dashboard]           │
│                                                     │
└─────────────────────────────────────────────────────┘

規格

• Phase 1 進度條：基於後端 /api/devices/scan 的回報進度；超過 10 秒超時切到 Phase 2B
• Phase 2A：最多顯示 4 顆裝置卡；超過則顯示「+N」
• Phase 2B：每個排錯項目可點擊展開詳細說明（平台自動偵測顯示對應項）

互動

• Phase 1「略過」→ 直接 Dashboard（不寫 Mock flag）
• Phase 2A「前往 Workspace」→ 自動選中第一顆裝置進入 workspace
• Phase 2B「使用 Mock 模式」→ 寫 Mock flag + 進 Dashboard
• Phase 2B「繼續到 Dashboard」→ 維持真實模式（使用者待會再接裝置）

---

4.6 完成後的狀態

• 寫入資料目錄下的 config.json（macOS 為 ~/Library/Application Support/visiona-local/config.json，其他平台見 4.1）：

  {
    "firstRunCompleted": true,
    "mode": "real" | "mock",
    "completedAt": "2026-04-11T10:00:00Z"
  }
  

• 跳轉 Dashboard
• 如果是 Mock 模式，Header 立即顯示黃色 Mock badge

4.7 i18n 重點文案（需翻譯）

Key	繁中	English
firstRun.welcome.title	歡迎使用 visionA-local	Welcome to visionA-local
firstRun.welcome.subtitle	在你的電腦上跑 Kneron AI 推論	Run Kneron AI inference on your computer
firstRun.welcome.signatureNotice	剛才你可能看到系統的安全警告——那是因為我們是內部工具、未購買程式碼簽章憑證。是安全的。	You may have seen a system security warning — that's because we're an internal tool without a code-signing certificate. It's safe.
firstRun.mode.title	選擇執行模式	Choose your mode
firstRun.mode.real.title	真實硬體模式	Real Hardware
firstRun.mode.mock.title	Mock 模式	Mock Mode
firstRun.hardware.scanning	正在掃描 USB 裝置...	Scanning USB devices...
firstRun.hardware.notFound	沒有偵測到 Kneron 裝置	No Kneron devices found
common.skip	略過	Skip
common.continue	繼續	Continue
common.back	返回	Back

4.8 無障礙

• 每一步 focus 預設落在主 CTA
• Tab 順序：[略過] → [主 CTA] → [次要 CTA] → [返回]
• 進度指示用 aria-label="第 X 步，共 3 步" 而非只靠視覺
• 每一步提供 role="region" + aria-labelledby
• 鍵盤：← → 在 Step 2 切卡、Enter 繼續、Esc 略過