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>
12 KiB
12 KiB
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
- macOS：
（資料目錄名稱於第四輪 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或類似） - 標題：
h132px / font-semibold - Value prop 清單：3 行，icon + 文字
- 簽章警示說明區塊：淺色背景卡片，
infoicon，自動顯示（不需偵測） - 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 立即顯示黃色
Mockbadge
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 略過