visionA/local-tool/.autoflow/02-prd/PRD-v2.md

# visionA-local — 產品需求文件（PRD v2）

> 版本：**v2.1（2026-04-14）**
> 作者：PM Agent
> 任務等級：L 級（重構方向變更）
> 狀態：**v2.1 補丁：吸收 R5-D1/D2/D3 + R5-E + Design 交叉審閱 4 Major / 4 Minor**
> 前版：`PRD-v2.md` v2.0（2026-04-14）/ [`PRD.md`](./PRD.md) v1.2（2026-04-11）

---

## 0. v2 變更摘要（和 v1.2 的差異）

本版本因應 2026-04-14 使用者提出的三項重大方向變更（介面架構、影片來源、模型管理），基於 R5 第五輪決策重新定位產品。本文件採「只更新受影響章節」策略，未影響的章節以「同 v1.2」標註並指向原子檔。

**最關鍵 5 點差異：**

1. **產品定位轉向**：從「Wails 桌面 app 內嵌 Next.js UI」改為「本機服務（Wails 控制台）+ 網頁控制台（瀏覽器 Web UI）」，競品類比從 Photo Booth 換成 **Ollama / LM Studio / Docker Desktop / Stable Diffusion WebUI**（R5-1）。
2. **砍 Mock 模式**：完全刪除，沒插硬體就讓 UI 空白（R5-5a）。Persona P3 Solution Architect 的使用情境被迫降級，US-2 整條砍掉。
3. **砍 yt-dlp 全套 + URL 影片推論**：媒體上傳只剩 camera / image / upload 影片（`.mp4 / .avi / .mov / .mpeg / .mpg`）。砍 35MB vendor binary。
4. **ffmpeg 授權從 GPL blocker 升級為 LGPL 方案 B 混合**：Windows/Linux 用 BtbN LGPL binary，macOS 自 build decoder-only（~20MB）commit 到 repo（R5-6 / R5-6a / R5-6b / R5-6c）。
5. **啟動時自動開瀏覽器（每次啟動）**：Wails 控制台 server 就緒後**每次啟動**都自動開系統預設瀏覽器，Settings 可關（R5-4 / R5-D3）。平台預設：**macOS / Windows ON；Linux OFF**（`xdg-open` 在極簡 WM 行為不穩，R5-D2）。用於抵消「多一步摩擦」對北極星指標的傷害。

### v2.1 補丁摘要（相對 v2.0）

v2.1 為 Design 交叉審閱發回的小版本修正（Major 1–3 + 4 個 Minor）+ R5-D / R5-E 決策落地，**未改動產品定位與核心決策**，只補齊語意與驗收標準。

| 變更 | 內容 | 依據 |
|------|------|------|
| M1 | 「首次啟動自動開」→「每次啟動自動開」（全文 replace） | R5-D3 |
| M2 | auto-open 平台預設差異（macOS / Windows ON；Linux OFF） | R5-D2 |
| M3 | US-7 Server 崩潰時 **除控制台 banner 外仍發 OS 原生通知** | R5-D1 |
| M4 | auto-open toggle 住 Wails 控制台（Design 仲裁採 PRD 原案） | Design review §G Major 4 |
| **R5-E 大改** | **AC-1.3 從「10 秒硬指標」翻轉為「60 秒 + 階段化進度 + perceived performance」** | R5-E1～E6 |
| Minor 1 | US-2 明確：日常啟動（非首次）同樣 auto-open | Design review Minor 1 |
| Minor 2 | Offline Overlay 硬阻斷（`role="alertdialog"` + focus trap + 不可關閉 + 純色卡片） | Design Spec v2 `server-offline-overlay.md` |
| Minor 3 | Wails 控制台 Footer **持久警示**取代單次 confirm / Error state **三動作按鈕**（Restart / View log / Report） | Design Spec v2 `control-panel.md` |
| Minor 4 | First-Run wizard **從 3 步縮為 2 步**（砍模式選擇），無硬體可按「稍後再設定」 | Design Spec v2 `first-run-update.md` / R5-5a |

**行數目標**：v2.1 新增約 40 行、精簡約 20 行，總量仍 ≤ 500 行。

**保留 vs 重寫對照表：**

| 章節 | 子檔 | v2 處理 |
|------|------|---------|
| 1. 產品策略與定位 | `strategy.md` | 🔴 重寫（見本檔 §1） |
| 2. 目標使用者與情境 | `user-research.md` | 🔴 重寫 US（見本檔 §2 / §5） |
| 3. 產品願景與非目標 | `vision-and-non-goals.md` | 🟡 修訂（見本檔 §3） |
| 4. 功能清單與 API 對照 | `features/feature-inventory.md` | 🔴 大幅修訂（見本檔 §4） |
| 5. 使用者流程 | `features/user-flows.md` | 🔴 重寫（見本檔 §5） |
| 6. 非功能需求與驗收 | `nonfunctional.md` | 🟡 修訂（見本檔 §6） |
| 7. 發佈與交付策略 | `release-strategy.md` | 🟢 同 v1.2（安裝檔數字需更新見 §6） |
| 8. 風險與相依性 | `risks.md` | 🔴 大幅修訂（見本檔 §8） |
| 4.8 第三方授權 | `feature-inventory.md §4.8` | 🔴 改寫（見本檔 §7） |

---

## 1. 產品策略與定位（重寫）

### 1.1 新定位

visionA-local 是一個**本機服務 + 網頁控制台**架構的 Kneron AI 邊緣推論工具：

- **Wails 桌面 app = 本機 server 控制台**（類比：Docker Desktop 的 Dashboard、Ollama 的 tray app），只負責 server 生命週期、log、版本資訊。
- **瀏覽器 Web UI = 真正的工作區**（類比：Stable Diffusion WebUI、LM Studio 的 web mode），所有「選裝置、選模型、推論」在瀏覽器完成。
- 兩者只在本機、只綁 `127.0.0.1`、不做 LAN、不做背景 daemon（R5-1 / R5-2）。

### 1.2 一句話價值主張

> **「雙擊 app → 自動開瀏覽器 → 插 USB → 5 分鐘內跑第一次推論。熟悉的瀏覽器操作、熟悉的 devtools，離線可用、零依賴。」**

### 1.3 競品類比更新

| v1.2 類比 | v2.0 類比 |
|-----------|-----------|
| Photo Booth、Kneron 官方 demo app | **Ollama**（server + web UI / CLI）、**Docker Desktop**（桌面 app 管 daemon、Dashboard 管操作）、**LM Studio**（桌面 app + server 模式）、**Stable Diffusion WebUI**（點 bat → 瀏覽器打開 127.0.0.1） |

### 1.4 北極星指標（更新）

**v1.2 原指標**：內部 FAE 在客戶現場首次安裝後 **5 分鐘內**順利跑出第一次推論的比例 ≥ 95%。

**v2.0 新指標**（處理「多一步開瀏覽器」紅線）：

> **內部 FAE 在客戶現場首次安裝後 5 分鐘內，瀏覽器 Web UI 跑出第一次推論的比例 ≥ 95%。**
> 起點雙擊安裝檔，終點瀏覽器顯示第一幀推論結果。自動開瀏覽器（R5-4 / R5-D3）是必要條件 — 使用者不需手動點「Open in Browser」，除非關過 Settings。比 v1.2 更嚴格（把瀏覽器冷啟動也納入 5 分鐘）。

### 1.5 策略取捨紀錄

- **砍 Mock 模式的代價**（R5-5a）：P3 Persona Sam 的「零摩擦 demo」情境無法再被支援，使用者明確接受此取捨，P3 實質降級為非目標（§2）。
- **雙視窗的代價**：Wails 控制台 + 瀏覽器比 v1.2 單視窗多一層「誰是主角」的心智負擔。緩解：控制台 UI 極簡（4 按鈕 + 1 log panel），所有業務操作（裝置、模型、Settings > 語言）強制住瀏覽器。

---

## 2. 目標使用者（修訂）

### 2.1 Persona 變動

- **P1 — Arthur（內部 FAE）**：同 v1.2。核心使用情境「帶筆電到客戶現場跑 demo」在 v2.0 下**多一步自動開瀏覽器**，但 R5-4 / R5-D3 決定每次啟動都自動開，對 Arthur 幾乎無感。
- **P2 — Dora（外部開發者）**：同 v1.2。她會欣賞「瀏覽器 devtools」（R5-1 動機 B），這是 v2.0 相對於 v1.2 的潛在加分項。
- **P3 — Sam（Solution Architect / PM）**：**實質降級為非目標使用者**。R5-5a 砍 Mock 模式後，Sam「沒硬體也能 demo」的訴求無法被滿足。保留 Persona 定義只是為了文件完整性，不再為他優化任何 MVP 功能。若未來要重新支援 Sam，應提 L 級功能重新討論。

### 2.2 Persona 對新架構的反應（PM 預測）

| Persona | 對「Wails 控制台 + 瀏覽器」的反應 | 對「砍 Mock」的反應 |
|---------|---------------------------------|--------------------|
| P1 Arthur | 🟡 中性偏好（第一次會愣一下，但每次啟動自動開瀏覽器大幅緩解） | ✅ 無感（他本來就帶硬體） |
| P2 Dora | ✅ 正面（瀏覽器 devtools 正中下懷） | ✅ 無感（她本來就在評估自家硬體） |
| P3 Sam | 🟡 中性（多一步開瀏覽器） | 🔴 **負面**（他本來就沒硬體） |

---

## 3. 非目標補充（修訂）

相對於 v1.2 `vision-and-non-goals.md`，v2.0 明確**新增以下非目標**：

- ❌ **Mock 模式 / 假資料 / 假裝置**（R5-5a）。沒插硬體就讓 UI 空白。
- ❌ **影片 URL 推論 / yt-dlp / YouTube / Vimeo / Dailymotion 整合**（R5 共識 2）。
- ❌ **Model Zoo / 遠端模型下載**（R5 共識 9，同 v1.2 但再次確認）。
- ❌ **LAN / 區網分享 localhost**（R5-1，使用者明確放棄動機 C/F）。
- ❌ **背景 daemon / tray 常駐**（R5-3 維持砍 tray，R5-2 維持視窗關閉=結束 server）。
- ❌ **雙 Next.js build**（共識 5，Wails 控制台用 vanilla HTML/JS/CSS，不搞兩份前端）。

**保留的非目標**（同 v1.2）：cluster、relay、tunnel、auto-update、程式碼簽章、telemetry、韌體燒錄、多架構、商店上架、license 啟用機制、WCAG 2.2 AA 正式合規。

---

## 4. 功能清單與 API 對照（大幅修訂）

本節列出**相對於 v1.2 的變動**。v2.0 完整的功能清單後續由 PM Agent 同步更新到 `features/feature-inventory.md` 子檔。

### 4.1 保留（沿用 v1.2）

- Device scan / connect（`GET /api/devices`、`POST /api/devices/scan`、`POST /api/devices/:id/connect|disconnect`、`POST /api/devices/:id/inference/start|stop`）
- 模型管理：8 個預設 .nef + 使用者上傳（`GET /api/models`、`POST /api/models/upload`、`DELETE /api/models/:id`、`GET /api/models/:id/download`）
- 批次影像上傳（`POST /api/media/upload/batch`，R5 共識 10）
- 推論引擎：camera / image / 上傳影片
- MJPEG 串流（`GET /api/camera/:id/stream`）
- WebSocket 推論結果 stream（`/ws/devices/*`、`/ws/server-logs`）
- 系統 API：`GET /api/system/health|info|deps|metrics`、`POST /api/system/restart`
- i18n 中英雙語（住瀏覽器 Web UI）
- Dark Mode 跟隨系統（住瀏覽器 Web UI，靠 `prefers-color-scheme`）
- Log 檔案持久化（macOS：`~/Library/Application Support/visiona-local/logs/`）

### 4.2 砍除（v2.0 明確刪除）

| # | 項目 | 理由 | R5 依據 |
|---|------|------|---------|
| 1 | `POST /api/media/url` endpoint | 砍 URL 推論 | R5 共識 2 |
| 2 | `server/internal/media/url_handler.go`（或類似檔案） | 同上 | R5 共識 2 |
| 3 | yt-dlp 內嵌（35MB binary + `vendor/ytdlp/` + `installer/payload-*` 相關 stage） | 砍 URL 推論 | R5 共識 2 |
| 4 | 前端「URL 貼上」tab、source-selector 中的 URL 選項 | 砍 URL 推論 | R5 共識 2 / R5 共識 4 |
| 5 | **Mock 模式全部**：Mock 裝置資料、Mock 推論結果 mock、Mock mode 切換按鈕、Mock 視覺標記、`server/internal/mock/`（若存在）、前端 Mock 入口 | 使用者明確砍 | **R5-5a** |
| 6 | Wails webview 載入 Next.js 前端的路由（原 `server/web/out` 不再被 Wails 直接 serve 作為主要 UI） | 轉為 server 控制台 | R5-1 |
| 7 | Wails tray 相關（維持 v1.2 Q-A 決策） | 沒意義 | R5-3 |
| 8 | First-Run 流程中的「模式選擇（真實 / Mock）」畫面 | Mock 砍了 | R5-5a |
| 9 | v1.2 US-2（Mock 模式試玩）整條 user story | Mock 砍了 | R5-5a |

### 4.3 新增（v2.0 明確增加）

| # | 項目 | 描述 | R5 依據 |
|---|------|------|---------|
| N1 | **Wails 控制台 UI** | vanilla HTML/JS/CSS 的獨立桌面視窗。包含：Start / Stop / Restart Server 按鈕、Open in Browser 按鈕、Server 狀態指示（running / stopped / error）、Server port 號、資料目錄路徑、版本號、Clear log 按鈕、Log panel（自動捲動 + 手動捲動解鎖）、Settings menu（含 auto-open toggle，見 N2）。**Footer 持久警示**：右下角固定顯示 `⚠ 關閉此視窗會停止 Local Server`（12 px muted，隨時可見，取代單次 confirm dialog 作為主要提醒）。**Error state 面板**（對應 N6）：log panel 上方浮動 banner 含三個動作按鈕 `Restart Server` / `View log` / `Report issue`（見 Design Spec v2 `v2/control-panel.md §5`）。**不含**裝置管理、推論、模型、Settings > 語言等任何業務操作。 | R5-1 / R5-5 / Design review Minor 3 |
| N2 | **啟動時自動開瀏覽器（每次啟動）** | Wails 控制台啟動、server 就緒後，**每次啟動**都自動開系統預設瀏覽器到 `http://127.0.0.1:{port}`（不是只在首次，R5-D3）。**auto-open toggle 住 Wails 控制台** 的 Settings menu（讀取時機在 Wails `main.go` 啟動階段，Web UI 尚未 load；已與 Design 取得共識採此位置）。**平台預設**：macOS / Windows `autoOpenBrowser = true`；**Linux `autoOpenBrowser = false`**（因 `xdg-open` 在極簡 WM 行為不穩定，R5-D2）。使用者可隨時切換。 | R5-4 / R5-D2 / R5-D3 |
| N3 | **Web UI Server Offline Overlay** | 瀏覽器 Web UI 偵測 server 斷線（heartbeat / WebSocket 斷）時，顯示**全螢幕半透明 backdrop（`rgba(0,0,0,0.4-0.5)`）+ 置中純色卡片**（卡片本體**不是**半透明，以確保 WCAG 4.5:1 對比）。卡片內訊息：「Local Server 已離線」+「請回到 visionA-local 桌面視窗重新啟動 Server」+「重試連線」Primary 按鈕 +「了解更多 ↓」Ghost 按鈕。**A11y 硬阻斷特性**：`role="alertdialog"` + `aria-modal="true"` + focus trap + **不可由使用者手動關閉**（無 ✕ 按鈕，只能 retry 成功或使用者自行 ⌘W / Ctrl+W 關 tab / 重開 app 後自動恢復）。覆蓋層下方 UI 凍結不可操作。 | R5-2 / Design review Minor 2 |
| N4 | **server boot-id 機制** | Go server 啟動時產生 UUID boot-id，放進 `/api/system/info` 回應。瀏覽器 Web UI 連上後記下第一個 boot-id；後續 poll 發現 boot-id 變了就代表 server 重啟，前端自動 reload state。**Restart Server 按鈕**（住 Wails 控制台）依賴此機制讓瀏覽器 tab 不用手動重載。 | R5 共識 14 |
| N5 | **CORS 中介層** | Go server 加 CORS middleware，`Access-Control-Allow-Origin` 只允許 `http://127.0.0.1:*` / `http://localhost:*`，其他 origin 一律拒絕。 | R5 共識 6 |
| N6 | **watchServer() 改為 Error state** | v1.2 watchServer 連續 3 次健檢失敗會 `os.Exit(1)`，v2.0 改為把 Wails 控制台的 Server 狀態切為「Error」並在 log panel 顯示錯誤，不強制退出 app。Error state 面板同時顯示三個動作按鈕（見 N1）。 | R5 共識 8 |
| N7 | **Server 崩潰 OS 原生通知** | 當 `watchServer()` 偵測連續 3 次健檢失敗進入 Error state 時，**除了**控制台 Error banner 外，**同步發一次 OS 原生通知**（macOS Notification Center / Windows Toast / Linux `libnotify`）。使用者可能正在使用瀏覽器 tab，靠 OS 通知把他拉回控制台。去重策略（避免 Error 狀態期間重複發通知）由 Architect 在 TDD v2 決定。 | R5-D1 |
| N8 | **啟動階段化進度顯示（6 階段）** | Wails 控制台在啟動過程全程顯示階段化進度：`1. 初始化控制台 → 2. 檢查 Python → 3. 啟動 server → 4. 偵測裝置 → 5. 開瀏覽器 → 6. 瀏覽器就緒`。每階段有編號 + 使用者可理解的動作描述 + 視覺回饋（spinner / 進度條）+ 中英雙語文案。第 6 階段「ready」的偵測訊號 = Web UI 透過 WebSocket hub 建立第一個 client 連線（不做新 endpoint，R5-E6）。階段文案由 Design Agent 最終決定（R5-E5）。啟動總預算見 §6.1 AC-1.3 系列。 | R5-E1～E6 |

### 4.4 功能對 Persona 對照表（更新）

| 功能 | 對應 Persona | 住哪裡 |
|------|-------------|--------|
| Wails 控制台（Start/Stop/Restart/Log）| P1, P2 | Wails 桌面視窗 |
| Device scan / connect | P1, P2 | 瀏覽器 Web UI |
| 模型管理 | P1, P2 | 瀏覽器 Web UI |
| Workspace（推論）| P1, P2 | 瀏覽器 Web UI |
| Settings > 語言 / 深色模式 | P1, P2 | 瀏覽器 Web UI |
| Settings > 自動開瀏覽器 | P1, P2 | **Wails 控制台**（因為它控制的是 Wails 啟動行為）|
| Server Offline Overlay | 全體 | 瀏覽器 Web UI |
| ~~Mock 模式~~ | ~~P3~~ | ~~砍~~ |

---

## 5. User Stories（重寫受影響的）

### US-1：第一次安裝 → 首次看到推論 UI（**重寫**，取代 v1.2 US-1 + 部分 US-5）

**身份**：任意目標 Persona（主力 P1 Arthur）
**情境**：剛拿到 `.dmg` / `.exe` / `.AppImage`，全新機器、客戶現場
**敘述**：
> 身為 FAE，我希望雙擊安裝檔、按幾下「下一步」、等進度條跑完，**視窗自動打開**（Wails 控制台）、**瀏覽器自動打開**（Web UI），插上 Kneron USB 後瀏覽器立刻顯示裝置，我按一下「Start」就看到第一幀推論結果。整個流程不超過 5 分鐘。

**驗收標準**：
- AC-1.1：下載安裝檔，無 terminal 操作可完成安裝（同 v1.2）
- AC-1.2：整個安裝過程 ≤ 3 分鐘（目標）/ ≤ 5 分鐘（上限）（同 v1.2，R4-4）
- **AC-1.3（R5-E 改寫）**：安裝完成後首次啟動，從 Wails 控制台視窗出現到瀏覽器 Web UI 顯示第一幀，**全程 ≤ 60 秒**（R5-E1，原 10 秒硬指標取消）。啟動過程全程可見、不可出現白畫面或無回饋狀態 — 採 Nielsen Norman perceived performance 原則，使用者感覺進度在推進比硬時間指標重要
- **AC-1.3a（新）**：啟動全程顯示階段化進度（6 階段，見 §4 N8），每階段有編號 + 使用者可理解的動作描述 + 視覺回饋（spinner 或進度條）+ 中英雙語文案。階段文案由 Design Agent 決定（R5-E2 / R5-E5）
- **AC-1.3b（新）**：任一啟動階段卡超過 **20 秒**，UI 必須顯示「正在重試」或「這步比預期久」類提示，**不可停留在白畫面或無變化狀態**（R5-E3）
- **AC-1.3c（新）**：總啟動時間超過 **60 秒仍未進入「就緒」狀態**，Wails 控制台進入 Error state，顯示「Restart Server」「View log」「Report issue」三個動作按鈕（對應 §4 N1 / N6，與 watchServer 3 次失敗後行為一致，R5-E4）
- **AC-1.3d（新）**：「瀏覽器就緒」的定義 = **Web UI 建立 WebSocket 連線到 server**（hub 收到第一個 client），不是瀏覽器視窗出現時。不做新 endpoint、不做固定延遲（R5-E6）
- AC-1.4：瀏覽器 Web UI 首次顯示時，若**沒插硬體**，Dashboard 顯示空白狀態 + 「請插入 Kneron 裝置」提示文字（R5-5a，不是 Mock 資料）。**First-Run wizard 從 v1.2 的 3 步縮為 2 步**（砍模式選擇，R5-5a）：Step 1 歡迎 → Step 2 硬體偵測。Step 2 在無硬體情況下可按 `稍後再設定` 略過，直接進 Dashboard 空白狀態（Design review Minor 4）
- AC-1.5：Mac 第一次開啟若出現 Gatekeeper 警告，Wails 控制台和安裝說明頁提供「右鍵 → 開啟」引導（同 v1.2）
- AC-1.6：auto-open 可在 **Wails 控制台的 Settings menu** 切換（不在 Web UI Settings，見 §4 N2）。**平台預設**：macOS / Windows ON；**Linux OFF**（R5-D2）。關閉後下次啟動只開 Wails 控制台、不開瀏覽器，使用者可手動按「Open in Browser」

### US-2：日常啟動（**新增**，取代 v1.2 US-2 Mock）

**身份**：P1, P2
**情境**：第二次以後的日常啟動（非首次安裝，但「啟動時自動開」對首次 / 日常**同樣生效**，R5-D3）
**敘述**：
> 身為日常使用者，我希望雙擊 app icon 後，Wails 控制台和瀏覽器都自動開啟（除非我關過 auto-open），server 狀態顯示 running，瀏覽器顯示上次的 Dashboard 狀態。

**驗收標準**：
- AC-2.1：日常啟動時，若 Wails 控制台 Settings `autoOpenBrowser === true`，**仍會自動開瀏覽器**（和首次啟動行為一致，R5-D3 / Design review Minor 1）。AC-1.3 系列的 60 秒預算與階段化進度在日常啟動同樣生效（通常遠低於 60 秒）
- AC-2.2：瀏覽器 Web UI 保留上次的 i18n 語言偏好、深色模式偏好
- AC-2.3：若使用者關過 auto-open（或 Linux 平台預設 OFF 且使用者未手動開），啟動時只開 Wails 控制台，使用者可點「Open in Browser」手動開

### US-3：連實體 Kneron 裝置（**微調**）

**身份**：P1, P2
**敘述**：同 v1.2，但 UI 住瀏覽器
**驗收標準**：
- AC-3.1 ~ AC-3.6：同 v1.2（插 USB → 3 秒內瀏覽器 Devices 頁顯示裝置）
- AC-3.7（**新**）：若使用者關閉瀏覽器但 Wails 控制台還在（server 仍跑），插入 USB 的事件不會通知使用者（不做 toast），下次使用者打開瀏覽器會看到裝置。不發原生 OS 通知（維持 v1.2 R4-8 OS 通知策略）。

### US-4：切換 / 上傳模型（**微調**）

**身份**：P1, P2
**敘述**：同 v1.2，但 UI 住瀏覽器
**驗收標準**：
- AC-4.1 ~ AC-4.4：同 v1.2
- AC-4.5（**新**）：拖放 .nef **只在瀏覽器視窗內有效**，拖到 Wails 控制台視窗無反應（不處理跨視窗拖放，避免混淆）
- AC-4.6（**新**）：預設模型清單**維持 8 個 .nef**，使用者可上傳自己的 .nef，但**沒有**任何 Model Zoo / URL download 入口（R5 共識 9）

### US-5：跑即時攝影機推論（**重寫，瀏覽器情境**）

**身份**：P1
**敘述**：
> 身為 FAE，我希望在瀏覽器 Workspace 頁選一顆 webcam、選一個模型、按 Start，看到 MJPEG 即時串流和推論 overlay。

**驗收標準**：
- AC-5.1：Workspace 頁能列出所有可用 webcam（透過後端 `/api/camera`，而非瀏覽器 `navigator.mediaDevices`；這點對 Chrome / Edge / Safari 行為一致）
- AC-5.2：選 webcam + 模型後按 Start，≤ 3 秒看到第一幀
- AC-5.3：推論 overlay（方框 / 標籤 / 信心度）正確顯示
- AC-5.4：即時 FPS / 延遲 / CPU / RAM 顯示
- AC-5.5：按 Stop 即時停止
- AC-5.6（**新**）：**不使用**瀏覽器 `getUserMedia()` API（避開 Chrome/Edge/Safari 權限差異 + HTTPS 限制）。所有攝影機存取走後端 AVFoundation / DirectShow / V4L2 pipeline（和 v1.2 架構相同）

### US-6：上傳影片推論（**修訂**，取代 v1.2 US-7 / US-8）

**身份**：P1, P2
**敘述**：
> 身為使用者，我希望能把一段 .mp4 / .avi / .mov / .mpeg / .mpg 影片拖進瀏覽器 Workspace，跑離線推論、看到逐幀結果。

**驗收標準**：
- AC-6.1：瀏覽器 Workspace 頁支援拖放或 file picker 上傳影片
- AC-6.2：支援副檔名：`.mp4 / .avi / .mov / .mpeg / .mpg`（R5 共識 11）
- AC-6.3：上傳後後端走 ffmpeg decode → Kneron 推論 → 前端顯示結果
- AC-6.4：**不支援** URL 推論 / YouTube / Vimeo / Dailymotion（R5 共識 2）

### US-7：Server 崩潰 / 意外中斷（**新增**）

**身份**：P1, P2
**情境**：Go server 子程序因某種原因崩潰（OOM、panic、依賴錯誤），或使用者關閉 Wails 視窗
**敘述**：
> 身為使用者，我希望當 server 斷線時，我在瀏覽器看到清楚的「Local Server 已離線」訊息，而不是無聲的網頁卡住。我也希望 Wails 控制台能告訴我發生什麼、我能按 Restart 重啟。

**驗收標準**：
- AC-7.1：瀏覽器 Web UI 偵測 server 斷線（health check 失敗 or WebSocket 斷 + retry 失敗）→ 顯示全螢幕 Server Offline Overlay（R5-2 / N3）。**Overlay 無 ✕ 按鈕、不可手動關閉**（`role="alertdialog"` + focus trap，Design review Minor 2）
- AC-7.2：Overlay 卡片內訊息：「Local Server 已離線，請回到 visionA-local 桌面視窗重新啟動 Server」+「重試連線」Primary 按鈕 +「了解更多 ↓」Ghost 按鈕。卡片背景純色（非 backdrop 半透明），確保 WCAG 4.5:1 對比
- AC-7.3：Wails 控制台 Server 狀態顯示變為「Error」（紅色），log panel 上方浮現 Error banner 面板，含 **三個動作按鈕**：`Restart Server` / `View log` / `Report issue`（對應 §4 N1 / N6，Design Spec v2 `v2/control-panel.md §5`，Design review Minor 3）
- AC-7.4：使用者在 Wails 控制台按 Restart Server 後，server 重啟、取得新 boot-id，瀏覽器 Web UI 透過 Retry 重連、偵測到新 boot-id、自動 reload state（R5 共識 14 / N4）
- AC-7.5：使用者直接關閉 Wails 視窗 → **server 結束**（R5-2 維持 v1.2 Q7）→ 瀏覽器 Web UI 顯示相同的 Offline Overlay + 提示「請重新啟動 visionA-local」
- AC-7.6：為避免使用者誤解「關閉視窗 = 程式還在背景跑」，**雙保險警示**：(a) Wails 控制台 Footer 右下角**持久警示文字** `⚠ 關閉此視窗會停止 Local Server`（12 px muted，始終可見，§4 N1）；(b) 標題列 / menu bar 的「Close」按鈕 tooltip / confirm dialog 同樣寫明。(a) 是主要手段（避免使用者盲目點 confirm），(b) 為輔
- **AC-7.7（R5-D1 新）**：Server 崩潰事件（watchServer 連續 3 次失敗進入 Error state 的瞬間），**除控制台 Error banner 外，同步發一次 OS 原生通知**（macOS Notification Center / Windows Toast / Linux `libnotify`）。使用者可能正在使用瀏覽器 tab 而未看控制台，OS 通知負責把他拉回來。去重策略（Error 狀態期間避免重複發）由 Architect 在 TDD v2 決定

### 砍掉的 User Stories

| US | v1.2 標題 | v2.0 處理 |
|----|----------|-----------|
| v1.2 US-2 | Mock 模式試玩 | **砍**（R5-5a） |
| v1.2 US-6 | 從 Tray 快速控制 | 維持 v1.2 已砍（第三輪 Q-A） |
| v1.2 US-8 | YouTube / URL 推論 | **砍**（R5 共識 2） |
| v1.2 US-9 | 查看 server 日誌 | **升級**：住 Wails 控制台成為一級功能（N1） |

---

## 6. 非功能需求（更新）

### 6.1 效能指標

| 指標 | v1.2 | v2.0 | 變化說明 |
|------|------|------|---------|
| 安裝時間 | ≤ 3 分 / 上限 5 分 | **同 v1.2** | R4-4 沿用 |
| 首次推論時間（首次啟動）| ≤ 20s / 上限 30s（至 Mock 第一幀）| **≤ 20s / 上限 30s（至瀏覽器第一幀）** | 終點改為瀏覽器 Web UI 顯示第一幀真實推論結果（因 Mock 砍）。R5-4 的自動開瀏覽器是達成此指標的必要條件。Architect TDD v2 需驗證預算 |
| 首次推論時間（回訪）| ≤ 10s / 上限 15s | **同 v1.2**（但終點改為瀏覽器）| 同上 |
| 實機接入時間 | ≤ 5s / 上限 10s | 同 v1.2 | — |
| 攝影機串流延遲（首次）| ≤ 200ms / 上限 250ms | 同 v1.2（R4-2）| — |
| 攝影機串流延遲（穩定後）| ≤ 120ms / 上限 150ms | 同 v1.2（R4-2）| — |
| idle CPU（無硬體狀態）| ≤ 3% / 上限 5%（Mock 模式）| **≤ 3% / 上限 5%（無硬體狀態）** | Mock 改為「無硬體空白狀態」。CPU 估計值不變，因為 v1.2 Mock 本來就不 spawn Python |
| idle RAM（無硬體狀態）| ≤ 500 MB / 上限 600 MB | **≤ 450 MB / 上限 550 MB** | 因無 Mock state、無 Python sidecar、無 yt-dlp 子程序，可略降。**此指標不含瀏覽器 tab 記憶體**（由 OS 系統瀏覽器負責，不是 Wails app 的責任範圍）。Architect 實測：Wails + Go server + Python 樂觀估 275–405 MB，達標 |
| 真實推論 RAM | ≤ 1 GB / 上限 1.5 GB | 同 v1.2 | — |

### 6.2 安裝檔大小（更新）

| 平台 | v1.2 上限 | v2.0 目標 | 組成變化 |
|------|-----------|-----------|---------|
| macOS `.dmg` | ≤ 220 MB | **≤ 185 MB**（目標）/ 上限 ≤ 220 MB | -35MB yt-dlp、ffmpeg 從 77MB GPL build 換成 ~20MB LGPL decoder-only = 淨 -92MB |
| Windows `.exe` | ≤ 200 MB | **≤ 165 MB**（目標）/ 上限 ≤ 220 MB | -35MB yt-dlp、ffmpeg 換 BtbN LGPL ~40MB（差異較小，但仍略降） |
| Ubuntu `.AppImage` | ≤ 200 MB | **≤ 165 MB**（目標）/ 上限 ≤ 220 MB | 同 Windows |

> **根據**：R5-6 / R5-6a / R5-6b / R5-6c ffmpeg LGPL 混合方案，砍 yt-dlp 全套。實際數字需 Architect 在 TDD v2 實測確認。

### 6.3 瀏覽器相容性（新）

- **預設**：開啟使用者 OS 預設瀏覽器（macOS：Safari/Chrome/Edge 依 OS 設定；Windows：Edge；Linux：依 `xdg-settings`）
- **auto-open 平台預設**（見 §4 N2）：macOS / Windows `autoOpenBrowser = true`；**Linux `autoOpenBrowser = false`**（`xdg-open` 在極簡 WM 下行為不穩定，R5-D2）
- **推薦**：Chrome 或 Edge（MJPEG decode 穩定性最好、devtools 最完整、WebSocket 穩定）
- **可用但不保證**：Safari（MJPEG decode 可能較慢；因為 US-5 AC-5.6 決定不走 `getUserMedia`，Safari 的攝影機權限流程差異不構成問題）
- **不支援**：IE、舊版 Firefox ESR（< 115）、行動版瀏覽器（不是使用情境）
- **WebSocket 就緒偵測**（R5-E6 / AC-1.3d）：依賴瀏覽器支援 WebSocket — 所有現代瀏覽器原生支援，風險低

> **注意**：v1.2 靠 Wails webview（WebView2 / WKWebView）是 Chromium/Safari 核心的一個已知固定版本，v2.0 改用使用者系統瀏覽器後**多了一維瀏覽器版本差異**。這是 Architect TDD v2 和 Testing Agent 要接受的新測試矩陣。

### 6.4 安全性需求（修訂）

- ✅ Server 只監聽 `127.0.0.1`，**絕對不 bind 0.0.0.0**（同 v1.2，R5 共識 7 再次確認）
- ✅ **CORS 中介層**：`Access-Control-Allow-Origin` 只允許 `http://127.0.0.1:*` / `http://localhost:*`（**v2.0 新增**，R5 共識 6）
- ✅ 使用者資料存在 OS 慣例目錄（同 v1.2）
- ❌ 無 TLS（localhost 不需要）（同 v1.2）
- ❌ 無認證（單人工具）（同 v1.2）
- ⚠️ 瀏覽器 DevTools 暴露：v2.0 使用者可以用 F12 看到所有 API 呼叫、WebSocket 流量。這不是安全問題（因為是單人本機），但要在 FAE 訓練文件提醒「不要把瀏覽器分頁截圖給外部，可能含硬體序號」

### 6.5 其他非功能需求

其餘章節（相容性、可維護性、可打包、可用性、日誌）**同 v1.2**，詳見 [`nonfunctional.md`](./nonfunctional.md)。

---

## 7. 第三方授權宣告（大改，取代 v1.2 §4.8）

### 7.1 依賴對照表（v2.0）

| 依賴 | 用途 | 授權 | 宣告要求 | v1.2 → v2.0 變動 |
|------|------|------|---------|-----------------|
| **ffmpeg LGPL build（BtbN）** | Windows / Linux 的攝影機 / 影片 decode | **LGPL v2.1+** | 必須宣告（LGPL 條文、動態連結、About 對話框列 `Powered by FFmpeg (LGPL)` + 連結） | v1.2 是 GPL build 標 `under legal review` 🔴，v2.0 改 LGPL 方案 B 解除 blocker（R5-6） |
| **ffmpeg LGPL build（macOS 自 build）** | macOS 的攝影機 / 影片 decode | **LGPL v2.1+** | 同上；額外說明「本 binary 由 Innovedus 在 macOS 上自 ffmpeg 官方 source 以 `./configure --enable-shared --disable-gpl` 等 flag build 出，源碼可取得」 | **v2.0 新增**。Decoder-only ~20MB，只含 mp4/avi/mov/mpeg/mpg 五種 decoder（R5-6a），commit 到 `vendor/ffmpeg/macos/`（R5-6b）。ffprobe 一起包（R5-6c）|
| **KneronPLUS SDK**（wheel）| 裝置 / 推論 | Kneron 專有 | 同 v1.2（發佈前 gate，R5 風險維持）| 同 v1.2 |
| **Python runtime**（python-build-standalone）| 執行 KneronPLUS | PSF 2.0 | 同 v1.2 | 同 v1.2 |
| **Python wheels**（numpy / opencv / pyusb 等）| 推論依賴 | BSD / MIT / Apache 2.0 為主 | 同 v1.2 | 同 v1.2 |
| **Wails v2** | Wails 控制台殼 | MIT | 同 v1.2 | 角色改變（v1.2 是前端 shell，v2.0 是控制台 shell）|
| **Next.js / React / shadcn / Radix / Tailwind / Zustand** | 瀏覽器 Web UI | MIT 為主 | 同 v1.2 | 同 v1.2 |
| ~~**yt-dlp**~~ | ~~URL 影片下載~~ | ~~Unlicense~~ | **v2.0 刪除** | 整個 vendor 拔掉 |

### 7.2 macOS ffmpeg 自 build 的長期責任

Architect TDD v2 必須產出 `scripts/build-ffmpeg-macos.sh`（記錄 configure flags / source tarball URL / checksum 驗證）。LGPL ffmpeg 幾乎不需更新（R5-6b）；~20MB binary commit 到 repo 可接受；2-3 年後 build 系統變化時需 ~0.5 人天重 build。

### 7.3 授權檔案落點

同 v1.2 `<APPDATA>/licenses/`，但：❌ 刪 `LICENSE-yt-dlp.txt`；✅ `LICENSE-ffmpeg.txt` 從 GPL 換成 LGPL v2.1 + v3；✅ 新增 `ffmpeg-macos-build-notes.md` 說明 macOS binary 來源。

---

## 8. 風險與相依性（大幅修訂）

### 8.1 技術風險變動

| 風險 ID | v1.2 狀態 | v2.0 處理 |
|---------|-----------|-----------|
| R1（KneronPLUS Linux wheel glibc）| 高可能 / 高影響 | 同 v1.2（不變）|
| R2（Windows WinUSB UAC）| 中 / 高 | 同 v1.2 |
| R3（KneronPLUS macOS x86_64）| 中 / 高，已被 Q4 降級 | 同 v1.2 |
| R4（Linux venv）| 中 / 中 | 同 v1.2 |
| R5（Kneron .nef re-distribution）| 發佈前 gate | 同 v1.2 |
| **R6（ffmpeg GPL blocker）** | 🔴 release blocker | **✅ 解除**（R5-6 走 LGPL 方案 B）|
| R11（發佈通路）| P2 追蹤 | 同 v1.2 |
| R12（CI runner）| P2 追蹤 | 同 v1.2 |

### 8.2 新增風險（v2.0）

#### N-R1 — 瀏覽器相容性差異（新）

| 項目 | 內容 |
|------|------|
| 描述 | v2.0 改用使用者系統瀏覽器後，MJPEG decode 效能、WebSocket 穩定性、深色模式判斷都會因瀏覽器而異。Safari 的 MJPEG 延遲可能超過 150ms 上限 |
| 可能性 | 中 |
| 影響 | 中（Safari 使用者體驗可能變差，但 P1 FAE 多用 Chrome）|
| 等級 | **P2 追蹤項** |
| 緩解 | 1) 預設推薦 Chrome / Edge；2) Safari 列為「可用但不保證」；3) Testing Agent 測試矩陣加 Safari；4) 發佈說明寫「若遇延遲過高，請改用 Chrome / Edge」 |
| PM 行動 | Testing 階段實測 Safari，若嚴重超標則在 Wails 控制台自動開瀏覽器時優先選 Chrome / Edge |

#### N-R2 — macOS 自 build ffmpeg 的長期維護成本（新）

| 項目 | 內容 |
|------|------|
| 描述 | macOS 上沒有現成的 LGPL decoder-only ffmpeg binary，需要 Innovedus 自 build（R5-6a / R5-6b）。2-3 年後若 ffmpeg build 系統變化 / configure flag 調整 / source tarball 結構變化，可能需要重新 build |
| 可能性 | 中（長期）|
| 影響 | 低—中 |
| 等級 | **P3 追蹤項**（不緊急）|
| 緩解 | 1) TDD v2 產出 `scripts/build-ffmpeg-macos.sh`，記錄完整 build 步驟；2) commit 時把 source tarball checksum、configure flags、build 環境一起寫進 commit message；3) 每 2 年做一次 build 演練確保 script 還能跑 |
| PM 行動 | 交付時在 delivery docs 加「ffmpeg rebuild SOP」 |

#### N-R3 — 使用者誤解「關閉視窗 ≠ 結束 server」（新）

| 項目 | 內容 |
|------|------|
| 描述 | R5-2 決定維持「關閉 Wails 視窗 = 結束 server」，但因為 v2.0 多了瀏覽器視窗這個「真正的操作介面」，使用者可能誤以為「我關掉 Wails 視窗沒關係、瀏覽器 tab 還在、應該還能用」。這種誤解會導致他在瀏覽器看到 Offline Overlay 時很困惑 |
| 可能性 | 高 |
| 影響 | 中（體驗面混亂，不危險）|
| 等級 | **P2 追蹤項** |
| 緩解 | 1) Wails 控制台 Close 按鈕的 tooltip / confirm dialog 明確寫「關閉此視窗會結束 Local Server」（AC-7.6）；2) Web UI 的 Offline Overlay 文案引導「請回到 visionA-local 桌面視窗重新啟動」；3) First-Run 歡迎頁加一句說明 |
| PM 行動 | Design Agent 在 Design Spec v2 確認這三處文案都到位 |

#### N-R4 — 砍 Mock 後 CI / E2E 測試困難（新）

| 項目 | 內容 |
|------|------|
| 描述 | v1.2 有 Mock 模式，CI runner 沒插硬體也能跑 E2E 測試（跑 Mock pipeline）。v2.0 砍 Mock 後，CI runner 要跑裝置管理 / 模型切換 / 推論 E2E 時，若沒硬體就測不了 |
| 可能性 | 高 |
| 影響 | 中（測試覆蓋率下降）|
| 等級 | **P2 追蹤項** |
| 緩解 | 1) E2E 測試分層：「不需硬體的 UI 測試」（載入、i18n、Settings、Offline Overlay、Wails 控制台 start/stop button）可在無硬體 CI 跑；「需要硬體的測試」（裝置偵測、推論）只能在有硬體的 runner 跑；2) 用 HTTP fixture mock 後端 API（前端 unit 測試層級），但不碰 Go server 的推論 pipeline；3) Testing Agent 在測試計畫明確區分兩層 |
| PM 行動 | 與 Testing Agent / DevOps 討論是否要建「有硬體 CI runner」（M5+ 規劃）|

### 8.3 PM 需要進一步確認的事項（寫入 progress.md 未解決問題）

沿用 v1.2 三項（R5 授權 / R11 發佈通路 / R12 CI runner）；新增 **N-R1 瀏覽器相容性**（Testing 驗證 Safari/Chrome/Edge/Firefox MJPEG + WebSocket）、**N-R4 CI/E2E 測試分層**（Testing + DevOps 於 TDD v2 提出分層方案）。

---

## 9. 策略性路線圖（更新）

- **Now（本 sprint，重構實作）**：PRD v2.1 / Design Spec v2 / TDD v2 三方互審 → Architect 產 ffmpeg LGPL vendor script + Wails 控制台實作 + CORS middleware + 刪檔清單 → Design 產控制台 wireframe + Offline Overlay + source-selector 拔 URL → 拆 milestone 進開發
- **Next（重構完成後）**：M7 Windows build 重驗（R5-7）；v1.0.0 release gate：Kneron re-distribution 授權（R5 發佈前 gate）；三平台 smoke test
- **Later（v1.0.0 發佈後）**：視回饋決定是否放回 v1.2 功能（Mock / URL 推論 / tray）；視需求升級 LAN 模式（重走 R5-1 動機 C）

---

## 10. 變更追蹤（和 v1.2 的完整差異清單）

| 區域 | v1.2 | v2.0 | R5 依據 |
|------|------|------|---------|
| 產品定位 | Wails 桌面 app 內嵌 Next.js UI | 本機服務 + 網頁控制台 | R5-1 |
| 競品類比 | Photo Booth | Ollama / Docker Desktop / LM Studio / SD WebUI | R5-1 |
| 一句話價值主張 | 「裝起來就能跑、離線可用、零依賴」 | 「雙擊 → 自動開瀏覽器 → 插 USB → 5 分鐘跑第一次推論」 | R5-1 / R5-4 |
| 北極星指標終點 | Mock 第一幀 | 瀏覽器第一幀（真實硬體）| R5-5a |
| Mock 模式 | MVP 必達 | **砍** | R5-5a |
| URL 影片推論 | US-8 / `/api/media/url` / yt-dlp 內嵌 | **砍** | R5 共識 2 |
| yt-dlp vendor（35MB）| 打包 | **砍** | R5 共識 2 |
| ffmpeg | GPL build（blocker 🔴）| **LGPL 方案 B 混合**（Win/Linux BtbN、macOS 自 build decoder-only ~20MB commit）| R5-6 / R5-6a / R5-6b / R5-6c |
| 安裝檔大小（macOS 目標）| ≤ 220 MB | **≤ 185 MB** | R5-6 |
| idle RAM（無硬體）| ≤ 500 MB / 上限 600 MB | ≤ 450 MB / 上限 550 MB | 砍 Mock / yt-dlp |
| Wails 視窗關閉 | 結束程式 | **同 v1.2**（R5-2 復議後維持）| R5-2 |
| Tray | 砍（v1.2 Q-A）| **同 v1.2**（R5-3 復議後維持）| R5-3 |
| 啟動時自動開瀏覽器 | 無 | **新增，每次啟動都開**（R5-D3），macOS/Win 預設 ON、**Linux 預設 OFF**（R5-D2），toggle 住 Wails 控制台 Settings（已與 Design 取得共識） | R5-4 / R5-D2 / R5-D3 |
| AC-1.3 啟動預算 | — | **≤ 60 秒**（原 v2.0 草案 10 秒硬指標被 R5-E1 取代）+ 階段化進度（6 階段，R5-E2）+ 20 秒卡住提示（R5-E3）+ 60 秒超時進 Error state（R5-E4）+ WebSocket 就緒偵測（R5-E6） | **R5-E1～E6** |
| Server 崩潰 OS 通知 | 無 | **新增**（控制台 Error banner 並存，R5-D1）| R5-D1 |
| First-Run wizard 步數 | 3 步（歡迎 / 模式選擇 / 硬體偵測） | **2 步**（歡迎 / 硬體偵測，砍模式選擇；無硬體可按「稍後再設定」略過） | R5-5a / Design review Minor 4 |
| Offline Overlay 硬阻斷 | — | **新增驗收特性**（`role="alertdialog"` + focus trap + 無 ✕ 按鈕 + 純色卡片） | Design review Minor 2 |
| Wails 控制台 Footer 持久警示 | 無 | **新增**「⚠ 關閉此視窗會停止 Local Server」取代單次 confirm 作為主要提醒 | Design review Minor 3 |
| Error state 三動作按鈕 | 無 | **新增** `Restart Server` / `View log` / `Report issue`（Wails 控制台 Error banner 內） | Design review Minor 3 |
| Wails 控制台 | 無（webview 載 Next.js）| **新增 vanilla HTML/JS/CSS**：Start/Stop/Restart/Open Browser/log panel/status/port/dir/version | R5-5 / R5 共識 5 |
| Server Offline Overlay | 無 | **新增**（Web UI 全螢幕覆蓋層）| R5-2 |
| CORS middleware | 無 | **新增**（127.0.0.1 / localhost only）| R5 共識 6 |
| watchServer 連 3 次失敗 | `os.Exit(1)` | **改為 Error state，不退出** | R5 共識 8 |
| Server boot-id | 無 | **新增**（支援 Restart Server 按鈕的 tab 自動重連）| R5 共識 14 |
| US-1 | 3 分鐘看到 Dashboard | 5 分鐘瀏覽器跑第一次推論 | R5-1 / R5-4 |
| US-2 | Mock 試玩 | 日常啟動（取代）| R5-5a |
| US-5 | Wails webview 攝影機 | 瀏覽器 Workspace + 後端攝影機 pipeline（不走 `getUserMedia`）| R5-1 |
| US-7 / US-8 | 影片 / URL 上傳 | 合併為 US-6，砍 URL | R5 共識 2 |
| US-9 | Settings 進階分頁次要功能 | **升級為 Wails 控制台一級功能** | R5-1 / R5-5 |
| 新 US-7（server 崩潰 / 離線）| 無 | **新增** | R5-2 |
| 上傳影片副檔名 | mp4 / avi / mov / webm（瀏覽器能吃）| **mp4 / avi / mov / mpeg / mpg** | R5 共識 11 |
| Persona P3 Sam | 三順位目標 | **實質降級為非目標** | R5-5a |
| 新風險 | — | N-R1 瀏覽器相容 / N-R2 macOS ffmpeg 維護 / N-R3 關窗誤解 / N-R4 CI 測試分層 | — |
| 解除風險 | R6 ffmpeg GPL blocker | **解除** | R5-6 |

---

## 11. 給 Orchestrator / 下輪審閱的問題

| # | 問題 | v2.1 狀態 |
|---|------|---------|
| 11-1 | auto-open Settings 資料落在哪？Web UI 和 Wails 控制台共用同一個 config 嗎？ | ✅ **已解決**（Architect 答：`preferences.json @ <dataDir>/`，write-rename 原子寫，fallback DefaultPreferences；auto-open toggle 由 Wails 進程讀取，Web UI 不碰此欄位） |
| 11-2 | US-1 AC-1.3 10 秒預算是否可達？ | ✅ **已解決（由 R5-E 取代）** — 整個問題被重新定義為「60 秒總預算 + 階段化進度 + perceived performance」，不再是硬時間指標 |
| 11-3 | idle RAM ≤ 450 MB 是否可達？ | ✅ **已解決**（Architect 實測：Wails + Go server + Python 275–405 MB 達標；悲觀估含瀏覽器 tab ~500 MB 超 50 MB，但瀏覽器 tab 不在本指標範圍內，已於 §6.1 clarify） |
| 11-4 | N-R4 砍 Mock 後 CI / E2E 測試分層 | ⏳ **懸置**，交 Testing Agent 在測試計畫提出「不需硬體的 UI 測試」vs「需硬體測試」分層方案 |
| 11-5 | Web UI 要不要加常駐「本機服務」徽章？ | ✅ **已解決：不加**（Design Agent 決定，改由 First-Run Step 1 歡迎頁一次性告知；見 Design review §D） |
| 11-6 | Settings auto-open toggle 住哪裡？ | ✅ **已解決**（Design 仲裁採 PRD 原案：住 Wails 控制台 Settings menu；Design Spec v2 `v2/settings-update.md` 將同步修正） |
| 11-7 | R5-E 階段化進度 6 階段文案（中英雙語）定稿 | ⏳ **懸置**（R5-E5 使用者授權 Design Agent 決定；最終在 Design Spec v2 wireframe 定版時由使用者審閱 override） |

---

## 變更紀錄

| 版本 | 日期 | 作者 | 變更 |
|------|------|------|------|
| v2.0 | 2026-04-14 | PM Agent | 依 R5 五輪決策重寫：砍 Mock / URL 推論 / yt-dlp；新增 Wails 控制台 + Server Offline Overlay + 首次自動開瀏覽器 + CORS；ffmpeg 從 GPL blocker 解除為 LGPL 方案 B 混合；Persona P3 降級；US-1/US-2/US-5/US-6/US-7 重寫；解除 R6，新增 N-R1 ~ N-R4 風險。完整差異見 §10 |
| v2.1 | 2026-04-14 | PM Agent | 吸收 Design 交叉審閱（4 Major + 4 Minor）+ R5-D1/D2/D3 + R5-E1～E6：(1) 「首次啟動自動開」→「每次啟動自動開」全文修正（R5-D3）；(2) auto-open 平台預設 Linux OFF（R5-D2）；(3) US-7 新增 AC-7.7 Server 崩潰時發 OS 原生通知（R5-D1）；(4) §4 新增 N7 OS 通知、N8 啟動階段化進度（6 階段）；(5) **AC-1.3 從 10 秒硬指標改寫為 60 秒 + perceived performance + AC-1.3a/b/c/d 四條新驗收**（R5-E1～E6）；(6) US-2 明確日常啟動同樣 auto-open（Minor 1）；(7) Offline Overlay 補齊 `role="alertdialog"` + focus trap + 不可關閉 + 純色卡片（Minor 2）；(8) US-7 AC-7.3 / AC-7.6 補 Wails 控制台 Footer 持久警示 + Error state 三動作按鈕（Minor 3）；(9) US-1 AC-1.4 補 First-Run 從 3 步縮為 2 步 + 「稍後再設定」略過（Minor 4）；(10) §6.1 idle RAM 加不含瀏覽器 tab 註記 + Architect 實測佐證；(11) §11 懸念 5 題結案 + 新增 11-6 / 11-7，保留 11-4 CI 測試分層懸置 |