jim800121chen
c54f16fca0
local-tool/: visionA-local desktop app
- M1: Wails shell + Go server + Next.js UI + Mock mode (macOS dmg ready)
- M2: i18n (zh-TW/en) + Settings 4-tab refactor
- M3: Embedded Python 3.12 runtime (python-build-standalone) + KneronPLUS wheels
- M4: Windows Inno Setup script (build on Windows runner)
- M5: Linux AppImage script + udev rule (build on Linux runner)
- M6: ffmpeg (GPL, pending legal review) + yt-dlp bundled
- Lifecycle: watchServer health check, fatal native dialog,
Wails IPC raise endpoint, stale process cleanup
.autoflow/: full PRD / Design Spec / Architecture / Testing docs
(4 rounds tri-party discussion + cross review)
.github/workflows/: macOS / Windows / Linux build CI
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
234 lines
12 KiB
Markdown
234 lines
12 KiB
Markdown
# 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 略過
|