visionA/local-tool/.autoflow/02-prd/nonfunctional.md

6. 非功能需求與驗收標準

6.1 效能需求（量化）

指標	目標值	上限值	測量方法
安裝時間（下載完成 → app 首屏）	≤ 3 分鐘	≤ 5 分鐘（硬性上限）	全新機器 + SSD + 一般規格 CPU，計時從雙擊安裝檔到 Dashboard 顯示。第四輪 R4-4 決策：上限放寬至 5 分鐘（原 3 分鐘僅為目標值，考量到 Python runtime 解壓 + 5 個 wheel 離線 install 的實測預算）。
首次推論時間 — 首次安裝後第一次啟動（app 首次開啟 → Mock 第一幀）	≤ 20 秒	≤ 30 秒	首次啟動需觸發 Python sidecar 冷啟動、wheel 載入、模型 warmup。第四輪 R4-7 決策：首次推論拆為兩級目標。
首次推論時間 — 回訪（第 2 次以後）（app 啟動 → Mock 第一幀）	≤ 10 秒	≤ 15 秒	無需再解壓依賴，僅 Python sidecar + 模型載入。第四輪 R4-7 決策：回訪目標較首次嚴格。
實機接入時間（插 USB → connect 成功）	≤ 5 秒	≤ 10 秒	計時從 USB 插入到 Devices 頁顯示「Connected」
攝影機串流啟動時間（按 Start → 第一幀）	≤ 2 秒	≤ 3 秒	計時從 Start 按鈕點擊到第一幀畫面
Mock 模式 idle CPU 占用	≤ 3%	≤ 5%	Mock 模式下 60 秒平均值（Mock 模式不 spawn Python sidecar，僅前端 state + Go server）
Mock 模式 idle RAM 占用	≤ 500 MB	≤ 600 MB	Mock 模式下 60 秒平均值。第四輪 R4-4 決策：原 400/500MB 放寬至 500/600MB（Wails + WebView2/WKWebView + Go server 基底已約 350-450MB，扣掉 Python 後空間有限）。注意：Mock 模式不 spawn Python sidecar，因此不計入 Python runtime 的 ~150MB。
真實推論 RAM 占用	≤ 1 GB	≤ 1.5 GB	跑一個分類 + 一個偵測模型（含 Python sidecar）
攝影機串流延遲 — 首次啟動串流（capture → UI 顯示）	≤ 200 ms	≤ 250 ms	MJPEG 時間戳比對；首次啟動 MJPEG pipeline warmup 較慢。第四輪 R4-2 決策。
攝影機串流延遲 — 穩定後（capture → UI 顯示）	≤ 120 ms	≤ 150 ms	MJPEG 時間戳比對；啟動 5 秒後的穩定值。第四輪 R4-2 決策：MJPEG 瀏覽器端 decode 不可能做到 100ms 以下，務實值為 150ms。

6.2 安裝檔大小需求

平台	目標值	上限值	組成
macOS（x86_64 .dmg）	≤ 220 MB	≤ 300 MB	Wails shell + Go server + Next.js + Python wheels + ffmpeg + .nef + Python runtime
Windows（x86_64 .exe）	≤ 200 MB	≤ 300 MB	同上 + WinUSB driver
Ubuntu（x86_64 .AppImage）	≤ 200 MB	≤ 300 MB	同上

注意：Architect Round 1 估算約 195-215 MB，在目標內。主要體積來自 ffmpeg（~40MB）+ Python wheels（~40MB）+ 預置模型（~73MB）。

6.3 零依賴需求

核心需求：使用者機器完全不需要預先安裝以下任何項目：

• ❌ 不需要 Python（內嵌 Python runtime + fallback 至系統 Python）
• ❌ 不需要 ffmpeg（內嵌靜態 binary）
• ❌ 不需要 KneronPLUS SDK（內嵌 wheel）
• ❌ 不需要 Node.js（前端已 embed 進 Go binary）
• ❌ 不需要 Docker
• ❌ 不需要 git
• ❌ 不需要任何開發工具

唯一例外：

• macOS / Linux：基本系統函式庫（glibc / libc 等標準元件）
• Windows：首次啟動需允許 UAC 以安裝 WinUSB driver
• Linux：首次啟動需 sudo 寫入 /etc/udev/rules.d/99-kneron.rules

6.4 離線可用需求

核心需求：除 update-check（本 MVP 已砍）之外，所有核心功能在完全斷網情況下必須正常運作，包含：

• ✅ 安裝過程（使用內嵌 wheels，pip install --no-index）
• ✅ First-Run 歡迎流程
• ✅ 裝置偵測 / connect / 推論
• ✅ 模型上傳 / 切換
• ✅ 攝影機串流
• ✅ 媒體上傳（圖片 / 影片）
• ⚠️ /api/media/url（yt-dlp）例外：需連網才能下載 YouTube 影片

6.5 相容性需求

6.5.1 作業系統（Q3 決定：都最新兩版）

平台	支援版本	架構	備註
macOS	14 (Sonoma)、15 (Sequoia)	x86_64	Q4 只做 x86_64，Intel Mac
Windows	10、11	x86_64	Windows 10 需要 1809 以上（WinUSB）
Ubuntu	22.04 LTS、24.04 LTS	x86_64	其他發行版不保證（用 AppImage 可能可以）

明確不支援：macOS 13 以下、Windows 10 1809 以下、Ubuntu 20.04 以下、所有 ARM 架構、其他 Linux 發行版（Fedora、Arch 等）。

6.5.2 Kneron 硬體

• KL720（第一優先）
• KL730
• 未來其他 KL 系列視 KneronPLUS wheel 支援度

6.5.3 攝影機

• macOS：AVFoundation 能列到的 webcam 皆支援
• Windows：DirectShow / Media Foundation 能列到的 webcam 皆支援
• Linux：V4L2 能列到的 webcam 皆支援

6.6 安全性需求

內部工具，安全模型較寬鬆，但仍需滿足：

• ✅ Server 只監聽 127.0.0.1，絕對不 bind 0.0.0.0
• ✅ 無 CORS 允許任意 origin
• ✅ 使用者資料（模型、config）存在 OS 慣例目錄，非系統路徑（macOS：~/Library/Application Support/visiona-local/；Windows / Linux 依各自 OS 慣例，由 Architect TDD 定義）
• ❌ 無需 TLS（localhost 不需要）
• ❌ 無需認證（單人工具）
• ❌ 無需加密儲存（檔案系統權限足矣）
• ⚠️ Python sidecar 的 subprocess 呼叫必須做參數 escape，避免 injection

6.7 可維護性需求

• ✅ 日誌寫入 OS 慣例資料目錄下的 logs/ 子目錄（macOS：~/Library/Application Support/visiona-local/logs/），滾動保留最近 7 天
• ✅ Crash 發生時 Go server 留下 stack trace 到 log file（本地，不上傳）
• ✅ server 狀態面板（沿用原 server-status-dashboard）可顯示目前依賴狀態
• ❌ 無遠端遙測 / 崩潰回報（Q12）
• ❌ 無 auto-update（Q6）

6.8 可用性需求（UX 層級）

6.8.1 本地化（Q13 決定）

• 中英雙語：繁體中文（zh-TW）+ 英文（en）
• 首次啟動依系統語言判斷，可在 Settings 切換
• 所有 UI 字串、錯誤訊息、First-Run 文案都需雙語

6.8.2 主題（Q15 決定）

• 預設跟隨系統（macOS appearance、Windows theme、Linux GTK theme）
• 使用者無法手動覆寫（簡化 Settings）
• 第三輪 Q-E3 決策：因為沒有手動覆寫需求，Settings 不設「外觀」分頁；語言偏好併入「一般」分頁

6.8.3 無障礙（WCAG 2.2 AA 明確 scope 外）

第四輪 R4-3 決策：WCAG 2.2 AA 正式合規不是 MVP 目標。內部工具、使用者是內部 FAE，使用者群體明確，不需要通過政府採購或公共部門的無障礙稽核。

• ✅ 盡力而為：繼承 shadcn/Radix 元件提供的預設無障礙屬性（ARIA role、focus ring、keyboard nav）
• ✅ 盡力而為：鍵盤可操作的主要流程（Tab navigation 可達 First-Run、Dashboard、Devices、Workspace 的核心按鈕）
• ❌ 不做：WCAG 2.2 AA 正式稽核
• ❌ 不做：螢幕閱讀器（VoiceOver / Narrator / NVDA）完整測試
• ❌ 不做：色彩對比度驗證工具（axe / Lighthouse A11y）的正式通過
• ❌ 不做：自訂快捷鍵衝突檢查
• ❌ 不做：大字體 / 高對比 / 減少動態效果的偏好設定

未來升級路徑：若未來要發佈給外部客戶或政府單位，需補完整的 WCAG 2.2 AA 稽核與修正。本 MVP 不保證合規。

本條也列入非目標：見 vision-and-non-goals.md 3.2.2 生命週期 / 營運相關段落（已補）。

6.9 可打包 / 可發佈需求

• ✅ 可從 CI（GitHub Actions 或類似）一鍵產出三平台安裝檔
• ✅ 可從單一 commit tag 觸發 release build
• ✅ 產出的安裝檔檔名含版本號：visionA-local-1.0.0-macos.dmg 等
• ✅ 發佈目標：內部 Gitea Releases 或 GitHub Releases（由使用者選擇）
• ❌ 不發佈到任何商店

6.10 總體驗收標準對照表

類別	指標	目標 / 上限	來源
效能	安裝時間	目標 ≤ 3 分鐘 / 上限 ≤ 5 分鐘	6.1
效能	首次推論時間（首次啟動）	目標 ≤ 20 秒 / 上限 ≤ 30 秒	6.1
效能	首次推論時間（回訪）	目標 ≤ 10 秒 / 上限 ≤ 15 秒	6.1
效能	實機接入時間	目標 ≤ 5 秒 / 上限 ≤ 10 秒	6.1
效能	串流延遲（首次）	目標 ≤ 200 ms / 上限 ≤ 250 ms	6.1
效能	串流延遲（穩定後）	目標 ≤ 120 ms / 上限 ≤ 150 ms	6.1
體積	macOS 安裝檔	≤ 220 MB	6.2
體積	Windows 安裝檔	≤ 200 MB	6.2
體積	Ubuntu 安裝檔	≤ 200 MB	6.2
資源	Mock idle CPU	≤ 3%（上限 5%）	6.1
資源	Mock idle RAM	≤ 500 MB（上限 600 MB）	6.1
依賴	完全零預裝	必須	6.3
離線	核心功能離線可用	必須	6.4
相容	macOS 14/15 x86_64	必須	6.5
相容	Windows 10/11 x86_64	必須	6.5
相容	Ubuntu 22.04/24.04 x86_64	必須	6.5
語言	中英雙語	必須	6.8.1
主題	跟隨系統深色模式	必須	6.8.2
發佈	CI 一鍵三平台 build	必須	6.9

第一次成功率（北極星指標）：內部 FAE 在客戶現場首次安裝後 5 分鐘內順利跑出第一次推論的比例 ≥ 95%。（對應安裝時間上限 5 分鐘 + 首次推論上限 30 秒，合計仍在 5 分 30 秒內。）