jim800121/visionA
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
visionA/local-tool/.autoflow/02-prd/user-research.md
jim800121chen c54f16fca0 Initial commit: visionA monorepo with local-tool subproject 
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>
2026-04-11 22:10:38 +08:00

8.1 KiB
Raw Permalink Blame History

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 記住上次偏好