jim800121/visionA
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
visionA/local-tool/.autoflow/02-prd/PRD-v2.md
jim800121chen 46514d77d7 docs(local-tool): M9 — Kneron Dongle FW 偵測 + 升降版（A+B、翻案 R5-Q9） 
L 級新功能、PRD/Design/TDD/ADR 三方協作 + 互審 + M9-6 SDK 雙驗證、總計 ~9000 行文件。

範圍：
- A 階段（MVP、5 人天）：KL520 + KL720 自動升級 KDP1 → KDP2
- B 階段（10.5 人天）：手動降版面向一般使用者 + KL630 / KL730 擴展
- 合計 15.5 人天、安裝包 +7MB（保守 bundle 策略）

關鍵決策：
- 翻案 R5-Q9（progress.md 第二輪使用者決策「韌體燒錄 flash → B 砍掉」）
- 跨平台用 KneronPLUS Python C API、不用 DFUT.exe
- 多版本目錄結構選 C metadata（firmware/<chip>/{version}/ + CURRENT_VERSION）
- Kneron firmware redistribution 授權與 R5-B4 預置模型同性質、發佈前評估

文件產出：
- PRD v2.2（PRD-v2.md 495 行 + features/feature-firmware-management.md 599 行）
- Design v2.2（firmware-management.md 948 行 + control-panel.md §6a graceful shutdown）
- TDD v2.2（v2/firmware-management.md 823 行 + ADR-001 218 行）
- 8 份 research（含 M9-6 弱驗證 + 強驗證、~3200 行）
- 3 份三方互審報告（PM/Design/Architect cross-review）

M9-6 強驗證重大發現（影響 B 階段）：
- KL730 product_id 實際是 0x732（不是 0x0730）
- KL630/KL730 firmware 是 embedded Linux rootfs（不是 .bin、不同代設計）
- KneronPLUS Python 沒 update_kdp_firmware_from_files 公開 API、warrenchen 走 ctypes
- 不影響 A 階段、B 階段 M9-8 需 spike

下一步：派 backend M9-1 起跑（bridge.py handle_firmware_upgrade）

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-25 07:40:56 +08:00

495 lines
42 KiB
Markdown
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# visionA-local — 產品需求文件（PRD v2）
> 版本：**v2.2（2026-05-24）**
> 作者：PM Agent
> 任務等級：L 級（v2.2 = 新增 FW 管理 feature，翻案 R5-Q9）
> 狀態：**v2.2 補丁：新增 Kneron Dongle FW 偵測 + 升降版（A + B 一次做完，~15.5 人天，+7MB）。詳見 [`features/feature-firmware-management.md`](./features/feature-firmware-management.md)**
> 前版：v2.1（2026-04-14，R5-D + R5-E）/ v2.0（2026-04-14，R5 重構）/ [`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 行。
### v2.2 補丁摘要（相對 v2.1）
v2.2 為**新增 feature**（不是修訂）——加入「Kneron Dongle FW 偵測 + 升降版」（A + B 一次做完），翻案 R5-Q9（progress.md 第二輪使用者決策 Q9 條目「韌體燒錄 flash → B 砍掉」、2026-04-11 拍板）。完整 user stories / AC / 風險 / milestone 在 [`features/feature-firmware-management.md`](./features/feature-firmware-management.md)；本檔僅補：§4.4 對照表 + 新增 §4.5 索引 + §10 新增一列 + §11 新增 11-8 + 變更紀錄 v2.2。新風險 R-FW-1 ~ R-FW-14 在 feature 子檔 §8 詳述（v2.2.1 補強）。安裝包 +7MB（保守 bundle 策略，dmg 163MB → ~170MB，仍在 §6.2 上限內）。Kneron firmware redistribution 授權與 R5-B4 預置模型授權合併處理（同性質智財授權）。
**保留 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 |
| **FW badge + 升級 modal**（v2.2 新）| P1, P2 | 瀏覽器 Devices 頁 |
| **Settings → 韌體管理**（v2.2 新，B 階段）| P1, P2 | 瀏覽器 Settings |
| ~~Mock 模式~~ | ~~P3~~ | ~~砍~~ |
### 4.5 Kneron Dongle FW 偵測 + 升降版（v2.2 新增 feature）
**翻案 R5-Q9**（progress.md 表格條目「Q9 韌體燒錄 flash → B 砍掉」，2026-04-11 第二輪決策）。當時砍的是「使用者燒任意 model 到 device flash」這條使用者旅程；v2.2 範圍切割後只做「升降版到 Kneron 官方 bundle 版本」，避開原始 brick 擔憂。完整 user stories（US-FW-1 ~ US-FW-3）/ AC / 風險 / milestone 詳見 [`features/feature-firmware-management.md`](./features/feature-firmware-management.md)。
- **A 階段（MVP，5 人天）**：KL520 + KL720 自動升級 KDP1 → KDP2、+0KB 安裝包、Devices 頁 FW badge（綠/黃/紅/灰）+ 升級 modal（M9-1 ~ M9-5）。**KL630/KL730 A 階段只做 FW 偵測（無升降版按鈕）**（v2.2.1 吸收 M9-6 弱驗證）
- **B 階段（擴展，10.5 人天）**：手動「韌體版本切換」面向一般使用者（UI 文案中性「韌體管理」/「切換到此版本」、不用「降版」字眼；含多層 safety net、不藏 dev mode、二次確認字串「DOWNGRADE」防誤觸）+ KL630/KL730 升降版（M9-10、含 AC-FW-3.5 生效條件 a/b/c）、+7MB（M9-6 ~ M9-13；M9-6 SDK 弱驗證已完成、強驗證 M9-9/M9-10 啟動前實機）
- **stage 命名統一**（v2.2.1）：preparing / loading / flashing / verifying / done / error（採 Design 命名為 source of truth、WebSocket event stage + i18n key 一致）
- **新風險 R-FW-1 ~ R-FW-14**（v2.2.1 補 R-FW-13 wheel 三平台版本不一致 P1 / R-FW-14 大小寫繞過 P2），詳見 feature 子檔 §8
- **與 R5-B4 合併處理**：Kneron firmware redistribution 授權與既有預置模型 redistribution 同性質（智財授權），發佈前一起取得 Kneron 書面授權；使用者明示「先不管授權、發佈前再評估」（feature 子檔 §9 Q-FW-1）
---
## 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. 變更追蹤（高階差異，逐項見 git history）
v1.2 → v2.x 已折成下方 bullet（原 25 項大表移除以保 500 行上限）：
- **定位轉向**（R5-1）：Wails 內嵌 Next.js → 本機服務 + 網頁控制台（Ollama 式）
- **砍 Mock / URL 推論 / yt-dlp 35MB**（R5-5a / 共識 2）：US-1/2/5/6/9 全面重寫
- **ffmpeg GPL → LGPL 方案 B**（R5-6 系列）：Win/Linux BtbN + macOS 自 build ~20MB
- **每次啟動自動開瀏覽器**（R5-4/D2/D3）+ AC-1.3 ≤60s perceived performance（R5-E1~E6）
- **新基礎建設**（R5-5/共識 5/6/8/14）：Wails 控制台 + Offline Overlay 硬阻斷 + CORS + boot-id + watchServer Error state + Footer 警示 + Error 三按鈕 + 崩潰 OS 通知
- **First-Run 3 步→2 步**（R5-5a / Minor 4）；影片副檔名改 mp4/avi/mov/mpeg/mpg；macOS ≤ 185MB（v2.2 含 +7MB FW ~170MB）；idle RAM ≤ 450/550MB
**節錄表（僅 v2.2 新項與 v2.x 風險）**：
| 區域 | v1.2 | v2.x | R5 依據 |
|------|------|------|---------|
| 新風險（v2.x）| — | N-R1 瀏覽器相容 / N-R2 macOS ffmpeg 維護 / N-R3 關窗誤解 / N-R4 CI 測試分層 + **R-FW-1 ~ R-FW-14（v2.2.1 補強 R-FW-13 wheel 三平台版本不一致 P1 / R-FW-14 大小寫繞過 P2）** | — / v2.2.1 |
| 解除風險 | R6 ffmpeg GPL blocker | **解除** | R5-6 |
| **v2.2 新 feature** | — | **FW 偵測 + 升降版**（A+B、+7MB、~15.5 人天、翻案 R5-Q9；v2.2.1 吸收三方互審 + M9-6 弱驗證）| **§4.5 + feature 子檔** |
---
## 11. 給 Orchestrator / 下輪審閱的問題
| # | 問題 | 狀態 |
|---|------|---------|
| 11-1 ~ 11-3 / 11-5 / 11-6 | v2.1 五題已解決（auto-open 落點、AC-1.3 預算、idle RAM、Web UI 徽章、Settings toggle 位置）| ✅ **已解決**（詳細結論散見 §1.4 / §6.1 / §4.5 N1-N2 / Design Spec v2 `v2/settings-update.md`；如需追溯，見 git log v2.1 提交）|
| 11-4 | N-R4 砍 Mock 後 CI / E2E 測試分層 | ⏳ **懸置**，交 Testing Agent 在測試計畫提出「不需硬體的 UI 測試」vs「需硬體測試」分層方案 |
| 11-7 | R5-E 階段化進度 6 階段文案（中英雙語）定稿 | ⏳ **懸置**（R5-E5 使用者授權 Design Agent 決定；最終在 Design Spec v2 wireframe 定版時由使用者審閱 override） |
| 11-8 | FW 管理 feature 三方互審項 | ✅ **v2.2.1 已吸收**（D-FW-1~6 / A-FW-1~6 全部已處理、O-FW-1（與 R5-B4 release blocker 合併）+ O-FW-2（M9-10 AC-FW-3.5 條件評估）為 Orchestrator 追蹤項；詳見 [`features/feature-firmware-management.md`](./features/feature-firmware-management.md) §14）|
---
## 變更紀錄
| 版本 | 日期 | 作者 | 變更 |
|------|------|------|------|
| v2.0 / v2.1 | 2026-04-14 | PM Agent | R5 五輪決策重寫 + Design 互審吸收（詳見 §10 / git log） |
| v2.2 | 2026-05-24 | PM Agent | 翻案 R5-Q9、新增 FW 管理 feature（A+B、~15.5 人天、+7MB）。詳見 [`features/feature-firmware-management.md`](./features/feature-firmware-management.md) |
| v2.2.1 | 2026-05-25 | PM Agent | FW feature 吸收三方互審 + M9-6 弱驗證：①stage 命名採 Design（preparing/loading/flashing/verifying）②M9 工時表拆法採 PM（Architect 同意）③AC-FW-3.5（KL630/KL730 升降版）延後 B 階段 M9-10 + 生效條件 a/b/c、A 階段 KL630/KL730 只做 FW 偵測④ADR-009 → ADR-001 編號統一⑤R5-Q9 行號改描述式引用⑥US-FW-2 拆 2a / 2b + UI 文案中性化⑦補 §7.2.1 體驗指標 5 條⑧新增 R-FW-13/14⑨補 AC-FW-1.9 graceful shutdown⑩badge 4 色（補灰色）⑪11-8 解決。詳見 [`features/feature-firmware-management.md`](./features/feature-firmware-management.md) §14.4 |
Reference in New Issue View Git Blame Copy Permalink