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>
137 lines
8.1 KiB
Markdown
137 lines
8.1 KiB
Markdown
# 2. 目標使用者與使用情境
|
||
|
||
## 2.1 Persona
|
||
|
||
### P1 — Innovedus 內部 FAE（主要 Persona，MVP 優先服務）
|
||
|
||
| 項目 | 內容 |
|
||
|------|------|
|
||
| 名字 | Arthur（化名） |
|
||
| 角色 | Innovedus 資深應用工程師 |
|
||
| 使用情境 | 帶筆電到客戶現場做 Kneron KL720 / KL730 推論 demo |
|
||
| 目標 | 不踩坑地開啟工具，接上 USB，立刻跑推論 |
|
||
| 痛點 | 客戶現場網路可能被擋、pip install 可能失敗、Python 環境可能衝突、ffmpeg 可能沒裝 |
|
||
| 技術素養 | 高（熟悉 CLI、Python、Docker） |
|
||
| 頻率 | 每週 1-3 次 |
|
||
| 一句話 | **「我希望打開筆電、雙擊 app、插 USB，就能 demo，不要再為了環境浪費客戶時間。」** |
|
||
|
||
### P2 — 外部開發者 / 評估客戶（次要 Persona）
|
||
|
||
| 項目 | 內容 |
|
||
|------|------|
|
||
| 名字 | Dora（化名） |
|
||
| 角色 | 剛拿到 Kneron 開發板的嵌入式 / AI 工程師 |
|
||
| 使用情境 | 評估 Kneron KL 系列是否適合自家專案 |
|
||
| 目標 | 不花一整天搞環境，快速看到「我的模型跑在 Kneron 上是什麼感覺」 |
|
||
| 痛點 | KneronPLUS SDK 安裝步驟繁瑣、文件分散、踩坑後找不到解答 |
|
||
| 技術素養 | 高，但對 Kneron 生態不熟 |
|
||
| 頻率 | 評估期 1-2 週內高頻，之後看決策 |
|
||
| 一句話 | **「我想用自己的 .nef 模型在 Kneron 上跑起來，不要先讀 200 頁文件。」** |
|
||
|
||
### P3 — Solution Architect / PM（第三順位 Persona）
|
||
|
||
| 項目 | 內容 |
|
||
|------|------|
|
||
| 名字 | Sam（化名） |
|
||
| 角色 | Innovedus / 合作夥伴的解決方案架構師或產品經理 |
|
||
| 使用情境 | 向客戶 / 內部高層介紹 Kneron 能做什麼，手邊沒有硬體 |
|
||
| 目標 | 用 Mock 模式看到「產品會長什麼樣」，不需要任何技術前置作業 |
|
||
| 痛點 | 不會寫 code、沒硬體、無法自己跑 demo |
|
||
| 技術素養 | 中（會用終端機但不寫程式） |
|
||
| 頻率 | 每月 1-2 次 |
|
||
| 一句話 | **「我要一個零摩擦的 demo 環境，能跑 Mock 就好，我只是要讓人看到願景。」** |
|
||
|
||
## 2.2 核心 User Stories（6 個關鍵情境）
|
||
|
||
### US-1：第一次安裝
|
||
|
||
**身份**：任意 Persona
|
||
**情境**：剛拿到 visionA-local 的下載連結，手邊是全新一台機器
|
||
**敘述**：
|
||
> 身為一名 Innovedus FAE，我希望下載安裝檔、雙擊、按幾下「下一步」，就能在不開啟 terminal、不輸入任何指令的情況下完成安裝，並在 3 分鐘內看到 app 首屏。
|
||
|
||
**驗收標準**：
|
||
- AC-1.1：下載 `.dmg` / `.exe` / `.AppImage`，無 terminal 操作可完成安裝
|
||
- AC-1.2：整個安裝過程（解壓 + 依賴設定）≤ 3 分鐘（一般硬體 + SSD）
|
||
- AC-1.3：安裝完成後，系統中出現 visionA-local app icon（Applications / 開始功能表 / 應用程式清單）
|
||
- AC-1.4：**即使使用者機器完全沒裝 Python / ffmpeg / KneronPLUS，仍能成功安裝並啟動**
|
||
- AC-1.5：首次啟動若需要管理員權限（Windows WinUSB driver、Linux udev rules），必須明確告知使用者原因
|
||
- AC-1.6：Mac 第一次開啟若出現 Gatekeeper 警告，app 內必須提供「右鍵 → 開啟」的引導說明（因為不做 notarization）
|
||
|
||
### US-2：Mock 模式試玩
|
||
|
||
**身份**：Solution Architect / PM（P3）
|
||
**情境**：想向高層 demo 產品能力，手邊沒有 Kneron 硬體
|
||
**敘述**：
|
||
> 身為一名 Solution Architect，我希望啟動 app 後能立刻進入 Mock 模式，看到 3 個假裝置、假的推論流在跑，不用接任何硬體，也不用研究怎麼切換模式。
|
||
|
||
**驗收標準**：
|
||
- AC-2.1：First-Run 流程中 Mock 模式是「一鍵進入」選項（非預設）
|
||
- AC-2.2：進入 Mock 模式後，≤ 30 秒內可看到假的裝置列表 + 假的推論結果
|
||
- AC-2.3：Mock 模式下，UI 必須有明確視覺區隔（主視窗標題列 / 首頁徽章 / sidebar 狀態列都要有 mock 標記）
|
||
- AC-2.4：Mock 與真實模式可隨時在 Settings 切換，切換不需重啟 app
|
||
|
||
### US-3：連實體 Kneron 裝置
|
||
|
||
**身份**：Innovedus FAE（P1）、外部開發者（P2）
|
||
**情境**：帶著 Kneron KL720 / KL730 USB dongle，想立刻 connect
|
||
**敘述**：
|
||
> 身為一名 FAE，我希望插上 Kneron USB 後，app 自動偵測到裝置、顯示型號與韌體版本，點一下「Connect」就能進入工作區開始推論。
|
||
|
||
**驗收標準**：
|
||
- AC-3.1：插入 USB 後，≤ 3 秒 app 偵測到裝置並顯示在 Devices 頁
|
||
- AC-3.2：偵測結果包含：裝置型號、韌體版本、序號、連線狀態
|
||
- AC-3.3：從「偵測到」到「connect 成功」的操作 ≤ 5 秒
|
||
- AC-3.4：connect 失敗時必須顯示具體原因（driver 問題 / 權限問題 / USB 3.0 問題），並提供排錯步驟
|
||
- AC-3.5：**Windows 第一次連接若需 UAC 安裝 WinUSB driver，必須顯示說明對話框**
|
||
- AC-3.6：**Linux 第一次連接若需寫入 udev rules，必須顯示說明對話框**
|
||
|
||
### US-4：切換 / 上傳模型
|
||
|
||
**身份**：外部開發者（P2）
|
||
**情境**：想把自己訓練的 .nef 模型換上去試跑
|
||
**敘述**：
|
||
> 身為一名開發者，我希望能從預置模型列表挑一個、或直接拖拉我的 .nef 檔進 app，不用手動複製檔案到特定資料夾、不用設環境變數。
|
||
|
||
**驗收標準**：
|
||
- AC-4.1：Models 頁列出所有預置模型（至少分類 / 偵測 / 臉辨各一顆）
|
||
- AC-4.2：支援拖放 .nef 檔到視窗任何地方觸發上傳
|
||
- AC-4.3：支援點「Upload」按鈕開啟原生 file picker
|
||
- AC-4.4：上傳成功後模型立刻出現在列表，可馬上切換
|
||
- AC-4.5：模型檔案預設存在 OS 慣例的應用資料目錄（macOS：`~/Library/Application Support/visiona-local/models/`；Windows / Linux 依 OS 慣例，由 Architect TDD 定義），使用者可查看但不需直接操作
|
||
|
||
### US-5：跑即時攝影機推論
|
||
|
||
**身份**：FAE（P1）
|
||
**情境**：要向客戶展示「接上 webcam + Kneron，就能即時做物件偵測」
|
||
**敘述**：
|
||
> 身為一名 FAE，我希望在 Workspace 頁選一顆 webcam、選一個推論模型、按下 Start，看到 MJPEG 即時串流搭配推論 overlay 顯示偵測結果。
|
||
|
||
**驗收標準**：
|
||
- AC-5.1：Workspace 頁能列出系統中所有可用的 webcam
|
||
- AC-5.2：選擇 webcam + 模型後，按 Start 在 ≤ 3 秒內看到第一幀
|
||
- AC-5.3：推論結果以 overlay（方框 / 標籤 / 信心度）形式顯示在串流上
|
||
- AC-5.4：能顯示即時 FPS、延遲、CPU / RAM 占用
|
||
- AC-5.5：按 Stop 能即時停止串流與推論，不留殘影
|
||
|
||
> **已移除：原 US-6「從 Tray 快速控制」**
|
||
>
|
||
> 第三輪 Q-A 決策砍掉系統列 tray。理由：Q7 已決定「關閉視窗 = 結束程式」，使 tray 失去背景常駐價值；加上跨平台圖資產與 Wails tray 踩坑成本高。所有快速控制改由主視窗原生 menu bar + sidebar 提供。
|
||
|
||
## 2.3 延伸情境（MVP 包含但非核心 Story）
|
||
|
||
- **US-7**：上傳影片 / 圖片做離線推論（對應 `/api/media/upload/*`）
|
||
- **US-8**：貼 YouTube / 網路影片 URL 做推論（對應 `/api/media/url`，Q10 決定保留，需打包 yt-dlp）
|
||
- **US-9**：查看系統依賴狀態與 server 日誌（對應原 `server-status-dashboard` / `server-log-viewer`）
|
||
|
||
## 2.4 使用者旅程地圖（First-Run 場景）
|
||
|
||
| 階段 | 行為 | 感受 | 潛在痛點 | visionA-local 的解法 |
|
||
|------|------|------|----------|---------------------|
|
||
| 認知 | 從同事 / 內部公告得知有這個工具 | 期待 | 怕環境難搞 | 發佈說明寫明「零預裝、三分鐘安裝」 |
|
||
| 下載 | 從內部 Gitea Releases 下載 | 中性 | Mac 不知道該下哪個 | 下載頁清楚列出三平台檔名 |
|
||
| 安裝 | 雙擊安裝檔，跟指示走 | 若順利：放心；若跳警告：焦慮 | Mac Gatekeeper 警告、Win SmartScreen 攔截 | 發佈說明頁 + First-Run 歡迎頁有「看到警告？點這裡」的引導 |
|
||
| First-Run | 選擇模式（真實 / Mock） | 好奇 | 不知道該選哪個 | Mock 作為「無硬體入口」強調「不用接設備也能玩」 |
|
||
| 第一次成功 | 看到第一幀推論結果 | 驚喜 | — | 「3 分鐘就看到結果」—— 這就是價值 |
|
||
| 日常使用 | 打開 → 接 USB → 推論 → 關閉 | 滿意 | 若每次都要重新設定則挫敗 | Settings 記住上次偏好 |
|