# 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`](./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 秒內。）