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>
164 lines
9.5 KiB
Markdown
164 lines
9.5 KiB
Markdown
# 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 秒內。）
|