# 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）：
  ```json
  {
    "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 略過