# visionA-local — PM 第一輪需求分析

> 階段：第一階段（三方聯合討論）— 需求探索
> 作者：PM Agent
> 日期：2026-04-10
> 狀態：第一輪分析草稿，**非 PRD**，待 Design / Architect 回饋與使用者確認

---

## 1. 產品定位：與原 edge-ai-platform 的差異

| 面向 | edge-ai-platform（原專案） | visionA-local（本專案） |
|------|---------------------------|------------------------|
| 部署形態 | 伺服器/容器，EC2 + Docker + 反向代理 | 單機桌面 App（Mac / Win / Ubuntu） |
| 網路模型 | 多人可遠端連線（有 relay / tunnel / cluster） | 只跑 localhost，一人一機 |
| 安裝體驗 | Ops 手動部署、curl install script、需先裝 ffmpeg/python | 一鍵 GUI 安裝檔，內嵌所有依賴 |
| 多裝置策略 | 支援 cluster（多 Kneron 叢集） | 單機最多接多顆 USB，但**不做 cluster** |
| 使用場景 | 共享平台、遠端存取、多人協作 | 個人開發、現場 POC、離線 demo |

**核心轉換：從「共享基礎設施」變成「個人工具」**。這個定位決定了所有後續取捨——任何為了「多人」「遠端」「規模化」而生的功能都該砍掉，任何為了「安裝便利」「離線可用」「單人順手」的體驗都要加強。

### 目標使用者（Persona 草案，待細化）

1. **Innovedus 內部應用工程師 / FAE（主要）** — 帶筆電去客戶現場做 Kneron KL720/KL730 demo，不能依賴網路或客戶 IT 環境。核心需求：**「接上去就能跑」**。
2. **外部開發者 / 評估客戶（次要）** — 剛拿到 Kneron 開發板想快速上手試玩，沒耐心搞 Python 環境與 SDK 安裝。核心需求：**「不踩坑」**。
3. **Solution Architect / 產品經理（第三）** — 非工程背景，想用 Mock 模式體驗產品能力，向客戶說故事。核心需求：**「不用寫 code」**。

此產品定位是**內部工具 + POC 工具**，不是 production 服務。這個前提會影響我們對可靠性、可觀測性、license、auto-update 等的取捨。

---

## 2. 核心 User Stories（6 個關鍵情境）

| # | 情境 | Persona | 成功體驗 |
|---|------|---------|----------|
| US-1 | **第一次安裝** | 全部 | 下載安裝檔 → 雙擊 → 照指示點幾下 → 桌面出現 app icon + tray 圖示，全程 < 3 分鐘、無需 terminal |
| US-2 | **Mock 模式試玩** | 產品經理 | 啟動 app 後預設就能進入 Mock 模式，看到 3 個假裝置、跑假推論流，不用接任何硬體 |
| US-3 | **連實體 Kneron 裝置** | FAE | 插上 USB → App 自動偵測 → 顯示裝置型號與韌體版本 → 點「connect」就能跑 |
| US-4 | **切換/上傳模型** | 開發者 | 從內建的預置 .nef 模型選一個，或拖拉自己的 .nef 進來，不用手動拷貝檔案到特定路徑 |
| US-5 | **跑即時攝影機推論** | FAE | 選一顆接上的 webcam → 點「Start」→ 看到 MJPEG 串流 + overlay 推論結果 |
| US-6 | **從 tray 快速控制** | 全部 | 關閉主視窗後 app 仍在 tray，點 tray 可看到裝置狀態 / 開啟 UI / 離開 |

**延伸情境（次要，可進 Phase 2）：**
- US-7：上傳影片 / 圖片做離線推論（原專案已有）
- US-8：匯出推論結果（JSON / CSV / 影片）
- US-9：查看系統依賴狀態與日誌

---

## 3. 功能範圍確認（對照原專案 API / 頁面）

### 3.1 後端 API 保留 / 刪除

| API 群組 | 決定 | 備註 |
|---------|------|------|
| `/api/system/*`（health / info / metrics / deps） | ✅ 保留 | local 也需要，但 metrics 可能簡化 |
| `/api/system/update-check` | ⚠️ 視情況 | 取決於使用者是否要 auto-update（**待確認**） |
| `/api/system/restart` | ✅ 保留 | Tray 需要 |
| `/api/models/*`（list / get / upload / delete） | ✅ 全保留 | 核心 |
| `/api/devices/*`（list / scan / connect / disconnect / flash / inference start/stop） | ✅ 全保留 | 核心 |
| `/api/camera/*`（list / start / stop / stream） | ✅ 全保留 | 核心 |
| `/api/media/upload/*`（image / video / batch） | ✅ 保留 | US-7 需要 |
| `/api/media/url` | ⚠️ 建議砍 | 需要 yt-dlp 依賴，local 版應儘量減少外部依賴；若砍掉 yt-dlp 可少一個依賴 |
| `/api/clusters/*`（全部） | ❌ 砍 | 決策已確認 |
| `/ws/clusters/*` | ❌ 砍 | 同上 |
| `/ws/devices/*`、`/ws/server-logs` | ✅ 保留 | 核心 |
| `/auth/token`（relay token） | ❌ 砍 | local 不需要 relay |
| relay / tunnel 相關中介層 | ❌ 砍 | 決策已確認 |

### 3.2 前端頁面保留 / 刪除

對照 `frontend/src/app/` 結構：

| 路由 | 決定 |
|------|------|
| `/`（首頁 / dashboard） | ✅ 保留，但**重新設計**——local 版首頁應該是「快速開始」而非「叢集總覽」 |
| `/devices` | ✅ 保留 |
| `/models` | ✅ 保留 |
| `/workspace`（推論工作區） | ✅ 保留 |
| `/settings` | ✅ 保留，但**清掉 relay 設定、cluster 設定** |
| `/clusters` | ❌ 整個砍掉 |

### 3.3 其他模組處理

| 模組 | 決定 |
|------|------|
| `server/internal/cluster/` | ❌ 刪除 |
| `server/internal/relay/` | ❌ 刪除 |
| `server/internal/tunnel/` | ❌ 刪除 |
| `server/internal/flash/`（韌體更新） | ⚠️ **需 Architect 確認**：local 版要不要保留韌體燒錄？可能在現場 demo 會用到 |
| `server/internal/update/`（自我更新） | ⚠️ 取決於 auto-update 決策 |
| `installer/`（Wails） | ✅ 作為 visionA-local 的 GUI shell 基礎 |

---

## 4. 驗收標準方向（待細化為量化指標）

local 版的「能用」應該用**使用者體驗時間**與**零依賴**兩個維度定義：

| 驗收面向 | 建議門檻 |
|---------|---------|
| **安裝時間** | 全新一台機器（無 Python、無 ffmpeg、無 SDK）從下載安裝檔到開啟 app 首屏 < 5 分鐘 |
| **首次推論時間** | 從 app 開啟到 Mock 模式跑出第一幀推論結果 < 30 秒（無需使用者任何設定） |
| **實機接入時間** | 插上 Kneron USB → app 偵測到裝置 → connect 成功 < 10 秒 |
| **零外部依賴** | 使用者機器**完全不需要**預先安裝 Python / ffmpeg / KneronPLUS / 任何 SDK |
| **離線可用** | 完全斷網下，除了 update-check 之外所有核心功能正常 |
| **跨平台** | macOS 12+ (arm64/amd64)、Windows 10+ (amd64)、Ubuntu 22.04+ (amd64) 三平台一致體驗 |
| **安裝檔大小** | 單平台安裝檔 < 500 MB（**需 Architect 評估是否可行**，預置模型數量會影響） |
| **資源佔用（idle）** | Mock 模式 idle 時 CPU < 5%、RAM < 500 MB |

---

## 5. 需要 Architect / Design 回答的問題

### 給 Architect 的問題

1. **KneronPLUS SDK 跨平台打包**：KneronPLUS 在 mac / win / linux 的安裝方式不一樣（mac 需 driver、win 需 .dll、linux 需 udev rules），Wails 能不能把這些差異都抽象掉？是否需要在 post-install 步驟處理？
2. **Python runtime 內嵌策略**：我們要嵌入整個 Python 3.12 + KneronPLUS site-packages，單平台大概會長多大？有沒有更輕的方案（例如只嵌入需要的子模組）？
3. **ffmpeg 內嵌**：直接打包 static binary 還是透過 brew/winget 裝？static binary 比較省事但會讓安裝檔變大 50-100MB。
4. **預置模型 .nef**：要嵌入幾顆？哪幾顆？影像分類 / 物件偵測 / 臉辨各一顆？每顆多大？
5. **韌體燒錄（flash）功能**：local 版要不要保留？這會牽涉到韌體檔案也要打包進去。
6. **單一執行檔 vs 分離 installer**：原專案 edge-ai-platform 是 single binary + Wails installer，visionA-local 是否直接用 Wails 做 shell，把 server binary 包在 Wails 裡？
7. **update 機制**：Wails 有沒有現成的 auto-update 框架？或者每次都讓使用者重下？
8. **程式碼簽章**：Mac notarization 與 Windows Authenticode 要不要做？這影響發行流程與金錢成本。
9. **Tray 的跨平台一致性**：Wails tray 在三平台體驗一致嗎？Linux tray 尤其有坑。
10. **日誌與崩潰回報**：local 版該怎麼收集錯誤？要不要做 opt-in 的遠端 crash report？

### 給 Design 的問題

1. **Onboarding 流程**：第一次開啟 app 要不要有歡迎頁 / 快速教學？還是直接進 Mock 模式讓使用者自己摸索？
2. **首頁重新設計**：原版首頁是「叢集總覽」，local 版首頁應該呈現什麼？Dashboard？設備列表？還是 workspace 直接當首頁？
3. **Tray 的使用者流程**：點 tray icon 是打開主視窗、還是彈出 menu、還是開 mini dashboard？Mac / Win / Linux 各自慣例不同。
4. **Mock 模式的視覺提示**：使用者要能很明顯知道「我現在在跑假資料」，避免誤以為是真推論。是否要加 watermark / badge？
5. **安裝器的外觀**：Wails installer 的首屏長什麼樣？只有一顆「安裝」按鈕？還是要有品牌頁 / EULA / 路徑選擇？
6. **錯誤狀態**：裝置拔掉、模型載入失敗、ffmpeg 壞了——這些狀態的視覺與文案怎麼處理？
7. **暗色模式**：原專案有沒有暗色？local 版要不要跟隨系統？
8. **裁切 UI 範圍**：清掉 relay / cluster 後，`settings` 頁會剩什麼？需要重新規劃資訊架構嗎？

---

## 6. 需要使用者確認的問題

1. **Auto-update**：要不要做自動更新？如果要，是「背景下載 + 提示重啟」還是「只提示有新版，讓使用者自己下載」？
2. **程式碼簽章 / 公證**：要不要投資做 Apple Developer ID notarization 與 Windows code signing？這需要購買憑證（Apple $99/年、Windows EV cert $300-600/年），不做的話 Mac 會跳「unidentified developer」警告、Windows 會被 SmartScreen 攔截。
3. **發佈通路**：只放 Gitea Releases 讓內部下載？還是要上 Mac App Store / Microsoft Store / Snap Store？
4. **License / 啟用機制**：要不要做 license key 控制（防止外流）？還是完全開放？
5. **遙測**：要不要收集匿名使用數據（開啟次數、功能使用頻率、崩潰報告）？以便改進產品？
6. **目標使用者優先級**：內部 FAE、外部客戶、產品經理三種 persona，哪一種是 MVP 要優先服務的？這會影響 onboarding 設計。
7. **預置模型範圍**：同意內嵌「影像分類 + 物件偵測 + 臉辨」各一顆嗎？或者要更多 / 更少？
8. **韌體燒錄功能**：local 版保留嗎？是 FAE 現場 demo 的實用功能，但會增加打包複雜度。
9. **`media/url`（YouTube URL 匯入）功能**：要不要砍？砍了可以少一個 yt-dlp 依賴。
10. **Linux 支援優先級**：決策上寫了支援 Ubuntu，但實際開發優先級：Mac > Win > Linux 還是三平台齊進？Linux tray / USB 權限問題最多。

---

## 下一步

這份第一輪分析**不是 PRD**，目的是讓 Architect 與 Design 看過後給出技術與體驗面的反饋，以及讓使用者確認第 6 節的 10 個問題。待以下輸入收到後，PM 會進入第二輪——撰寫正式的 PRD（含 RICE、完整 User Stories、功能規格、成功指標、風險評估）。

需要的輸入：
- [ ] 使用者回答第 6 節的 10 個問題
- [ ] Architect 的技術可行性回饋（第 5 節問題 1-10）
- [ ] Design 的體驗面回饋（第 5 節問題 1-8）