# visionA-local 設計規格 v2（索引）

> Design Agent · 第五輪正式規格 · 初版 2026-04-14
> **目前版本：v2.2（2026-05-24 補丁）** — 吸收 R5-Q9 翻案、新增 Kneron Dongle FW 管理規格（升級 + 版本切換、面向一般使用者）
> 前一版本：v2.1（2026-04-14 補丁）— 吸收 Architect 交叉審閱 Major 1+2 / Minor 1-5 修正 + R5-D1/D2/D3 / R5-E 追加決策
> 本版依 **R5 決策**重構：visionA-local 從「Wails 跑 Next.js 的單一桌面 app」轉為「**Wails Server Control Panel + 瀏覽器 Web UI**」雙 UI 架構。
> 本文件為 v2 索引檔，各章節詳細內容見 `v2/` 子檔。v1（`design-spec.md` + `spec/`）仍保留作為基準參考，未來的實作以 v2 為準。

---

## v2 範圍

本次 v2 只重新設計**因 R5 決策而改變的部分**，其餘 v1 章節（IA、Settings 分頁結構、design tokens、i18n 策略、A11y 等）**仍然有效**。

### R5 決策總表（本 v2 的立論基礎）

| # | 題目 | 使用者決定 | 對設計的影響 |
|---|------|----------|------------|
| R5-1 | 重構動機 | A+B+G（多視窗便利 + devtools + 需求方要求） | 確立雙 UI 架構 |
| R5-2 | 關閉 Wails 視窗行為 | **關閉 = 結束 server**，瀏覽器顯示「Local Server 已離線」覆蓋層 | 新增 Server Offline Overlay 設計 |
| R5-3 | Tray 復議 | **維持砍 tray**（T1） | 控制台無 tray 退縮選項 |
| R5-4 | 首次啟動自動開瀏覽器 | **A：首次自動開，Settings 可關** | 新增 Settings toggle + First-Run 流程變動 |
| R5-5 | Wails 控制台 scope | PM 清單 **拿掉 Mock 模式切換** | 控制台不顯示 Mock UI |
| R5-5a | Mock 模式歸處 | **完全砍掉 Mock 模式** | Settings 刪除硬體分頁的 Mock 相關項 / First-Run 砍模式選擇步驟 |
| R5-6 | ffmpeg 授權 | LGPL 混合（Win/Linux BtbN、macOS 自 build） | 不影響 UI 設計本身 |
| R5-7 | M7 Windows | 先不管 | 不影響 v2 |

---

## 文件結構

| # | 章節 | 檔案 | 一句話摘要 |
|---|------|------|-----------|
| v2.1 | Wails Server Control Panel | `v2/control-panel.md` | 桌面控制台完整規格（wireframe、狀態機、元件、i18n、A11y） |
| v2.2 | Server Offline Overlay | `v2/server-offline-overlay.md` | 瀏覽器端偵測到 server 斷線時的全螢幕覆蓋層 |
| v2.3 | source-selector 修改 | `v2/source-selector-update.md` | 砍 URL mode、重寫 video tab、要刪的 i18n key 清單 |
| v2.4 | First-Run 流程重定義 | `v2/first-run-update.md` | 砍 Mock 模式選擇步驟、自動開瀏覽器的起手流程圖 |
| v2.5 | Settings 頁更新 | `v2/settings-update.md` | 新增「啟動時自動開啟瀏覽器」toggle、Linux 預設 OFF、落地 `preferences.json`、砍 Mock 相關設定 |
| **v2.6** | **啟動進度面板**（v2.1 新增） | **`v2/startup-progress.md`** | **R5-E 階段化啟動進度面板：6 階段 wireframe、中英雙語文案、20 秒卡頓提示、60 秒 timeout Error 流程** |
| **v2.7** | **韌體管理**（v2.2 新增） | **`v2/firmware-management.md`** | **Kneron dongle FW 升級 + 版本切換完整規格：Settings 新分頁、Devices 頁 FW badge（紅/黃/綠 + deep-link）、二次確認流程（輸入 DOWNGRADE）、52 個 i18n keys、6 個新 component token、R-FW-11 設計緩解** |

---

## v2 未動到的章節（仍以 v1 為準）

- `spec/01-information-architecture.md` — IA 不變（4 主區塊 + Settings）
- `spec/02-pages-diff.md` — 頁面清單變動極小（僅 workspace 推論源砍 URL）
- `spec/03-wireframes.md` — Dashboard / Devices / Models / Workspace 主體不變
- `spec/06-cross-platform.md` — 跨平台 UX 差異不變
- `spec/07-design-tokens.md` — tokens 完全沿用
- `spec/08-states.md` — 全域錯誤分級、空狀態文案不變
- `spec/09-accessibility.md` — 盡力而為原則不變
- `spec/10-i18n.md` — i18n 策略不變

---

## Design Token 一致性（總則）

**Wails Server Control Panel 與瀏覽器 Web UI 共用同一套 shadcn oklch design tokens**（見 `spec/07-design-tokens.md`）。
具體做法：控制台前端是 vanilla HTML/JS/CSS（R5 三方共識），但仍引入與 Next.js Web UI 一致的 CSS variable 定義檔（從 `frontend/src/app/globals.css` 擷取 `:root` 與 `[data-theme='dark']` 的 token block），達到：

- 控制台與 Web UI 在 Light / Dark 下視覺語言一致
- 錯誤訊息紅、警告琥珀、成功綠完全相同（不會出現控制台紅和 Web 紅不同的 UX 破綻）
- 未來若 tokens 更新，只要同步 CSS variable 檔即可

**不另外定義控制台專屬 tokens**，唯一例外是控制台的 log panel 使用等寬字體 token（`font.mono`，v1 已存在），以及標題列 `window-chrome.height`（v1 `spec/07-design-tokens.md §7.5` 已定義）。

---

## v1 → v2 差異總覽

| 面向 | v1（第四輪） | v2（第五輪） | 來源決策 |
|------|-------------|-------------|---------|
| 主視窗呈現 | Wails 單視窗 = Next.js 主 UI | Wails 單視窗 = Server Control Panel；Web UI 跑在瀏覽器 | R5-1 |
| 視窗關閉 | 結束程式（第四輪 Q7） | 結束程式 **+** 瀏覽器顯示離線 Overlay | R5-2 |
| Tray | 無 | 無（維持） | R5-3 |
| 首次啟動 | Wails 開 → First-Run wizard 三步（歡迎 / 模式選擇 / 偵測） | Wails 控制台開 → 自動 start server → 自動 open 瀏覽器 → First-Run wizard **兩步**（歡迎 / 偵測） | R5-4、R5-5a |
| 首次啟動 Settings | — | 新增「首次啟動時自動開啟瀏覽器」toggle（預設 ON） | R5-4 |
| Mock 模式 | 預設真實硬體，可於 Settings > 硬體切換為 Mock | **完全砍除**，沒插硬體就空白 | R5-5a |
| Settings 分頁 | 一般 / 硬體 / 模型 / 進階 | 一般 / 硬體 / 模型 / 進階（結構不變，內容刪減） | v1 保留 |
| Workspace 推論源 | camera / image / video（file + url） | camera / image / video（僅 file） | R5 三方共識 |
| 支援影片副檔名 | `.mp4, .avi, .mov` | **`.mp4, .avi, .mov, .mpeg, .mpg`** | R5 三方共識 |
| 影片載入文案 | 「正在解析影片連結，YouTube 影片可能需要 10-30 秒…」 | 純檔案上傳，無解析文案 | R5 三方共識 |
| Wails 控制台 scope | 不存在 | Header 狀態列 + Primary controls + Log panel + Log actions + Footer | R5-5 |
| Server 狀態機 | 黑盒 | **五態視覺化**：Running / Starting / Stopping / Stopped / Error | v2 新增 |
| Server 崩潰通知 | Wails shell out native notification | 控制台內的 Error state 面板 + 紅字 log + OS notification | v2 細化 |
| 瀏覽器端 server 斷線 | 未定義 | 全螢幕 Server Offline Overlay（不可關閉、提供重試） | R5-2 |

---

## v2.1 → v2.2 差異總覽（2026-05-24 補丁輪）

v2.2 是吸收 R5-Q9 翻案（FW 管理面向一般使用者）後的補丁，新增 Kneron dongle FW 升級 + 版本切換的完整設計規格。**不改變 R5 雙 UI 架構立論**、只新增功能模組。

| 面向 | v2.1 | v2.2（2026-05-24 補丁）| 來源 |
|------|------|---------------------|------|
| Settings 分頁數 | 4（一般 / 硬體 / 模型 / 進階） | **5**（一般 / 硬體 / **韌體** / 模型 / 進階） | R5-Q9 + architect 42 |
| Devices 頁 FW 顯示 | 純文字 `FW 2.1.0` | **pill badge**（紅 / 黃 / 綠三色）+ deep-link ⚙ icon | R5-Q9 第 5 點 |
| FW 升級 UX | 未設計 | **單步驟確認 + 進度 modal**（不可中斷） | architect 30 §M9-4 |
| FW 降版 UX | 未設計 | **二次確認**（輸入「DOWNGRADE」字串）+ 進度 modal + 全螢幕 hover 攔截 | architect 42 §5.3 |
| 失敗復原 UX | 未設計 | **8 種失敗類型對應 friendly message + 復原行動** | architect 42 §5.5 |
| 新增 i18n keys | — | **52 keys**（zh-TW + en） | 本檔 `v2/firmware-management.md §9` |
| 新增 component tokens | — | **6 個 fw-badge token**（current / older / legacy × bg/fg） | 本檔 `v2/firmware-management.md §11.2` |
| UI 用語策略 | — | UI 一律稱「韌體管理」/「版本切換」（中性詞）、code/log/技術文件仍稱 downgrade | architect 42 §1.1 |

---

## v2 → v2.1 差異總覽（2026-04-14 補丁輪）

v2.1 是 v2 三方互審後的修正補丁，不改變 R5 雙 UI 架構立論，只處理 Architect 互審發現 + R5-D / R5-E 追加決策。

| 面向 | v2（2026-04-14 初版） | v2.1（2026-04-14 補丁） | 來源 |
|------|--------------------|----------------------|------|
| Settings 落地檔 | `settings.json` + 「走 Wails settings store」 | **`preferences.json` @ `<dataDir>/`** + Go server write-rename atomic | Architect Review Major 1 |
| 「啟動時自動開瀏覽器」預設值 | 三平台一致 ON | **macOS/Windows = ON，Linux = OFF**（依 `runtime.GOOS`） | R5-D2 |
| Toggle label 字面 | 「首次啟動時自動開啟瀏覽器」（待確認） | **「啟動時自動開啟瀏覽器」**（R5-D3 定案：每次啟動都開） | R5-D3 |
| Log panel 上限 | 1000 行 + rotate 7 天 / 10 MB | **2000 行 + 無落地 rotate**（in-memory ring buffer，使用者透過 Export log 手動匯出） | Architect Review Minor m-1、m-12 |
| Error banner 「Report...」按鈕 | 正常按鈕 | **【hold】** 待 PM 提供 GitHub Issue repo URL | Architect Review Minor m-11 |
| Error state OS 通知 | v2 模糊（控制台可見，通知視為次要重複） | **R5-D1 保留**：Error state 發 non-blocking toast notification，與控制台 Error banner 並存 | R5-D1 |
| Starting state 視覺 | 只有 header spinner，5 秒 timeout | **階段化啟動進度面板**（`v2/startup-progress.md`），6 階段 + 20 秒卡頓提示 + **60 秒總上限** | R5-E |
| 首次啟動流程 | 「首次」自動開瀏覽器 | **「每次」** 啟動都自動開瀏覽器（Wails 每次新啟動） | R5-D3 |

---

## 給 Orchestrator 的問題（懸而未決）

**v2 懸而未決已解決**：
- ~~Q2 Server 崩潰 OS 通知~~ → **R5-D1 保留**（已吸收至 `control-panel.md §6.2` + `startup-progress.md §3.7`）
- ~~Q3 Linux 預設值~~ → **R5-D2 Linux 預設 OFF**（已吸收至 `settings-update.md §2.2`）
- ~~R5-4 label 字面歧義「首次 vs 每次」~~ → **R5-D3 每次**（已吸收至 `settings-update.md §2.3` + `control-panel.md §7.1`）

**仍懸而未決**：
1. **控制台 header「port 變更 fallback」視覺字樣**：v1 第四輪決策「port 佔用則 fallback 到 3722/3723」，建議格式 `Port: 3722 (default 3721 in use)`，待使用者最終確認字樣。
2. **v2 是否要回頭作廢 v1 的 `spec/04-first-run.md`**：目前 v2 另開 `v2/first-run-update.md`，但未修改 v1 原檔。建議 v2 穩定後作廢 v1 原檔並改為索引到 v2；在此之前保持雙軌。
3. **R5-E startup-progress.md 新增 3 個小懸念**（`v2/startup-progress.md §11`）：
   - (a) 20 秒卡頓 hint 文案「正在重試...」vs 中性「正在處理中，請稍候...」
   - (b) 階段 6 WebSocket 連線被安全軟體擋的 Error 說明是否要特別提示
   - (c) 使用者按 Retry 的語意：重置整個啟動流程 vs 重試當前階段（Design 建議前者）

**v2.2 新增懸而未決**（來自 `v2/firmware-management.md §14.4`）：
4. **降版 modal 字串「DOWNGRADE」未來 i18n 化處理**：當前 Design 規格要求所有語系使用者皆輸入字面字串 `DOWNGRADE`（en）。若未來改 i18n（如中文使用者輸入「降版」），需與 Architect / Frontend 確認後端 `confirmToken` 是否同步調整（architect 42 §2.3 後端固定接受 `confirmToken: "DOWNGRADE"`）。Design 建議**短期維持英文字串**（跨語言一致、避免後端多語對應）。
5. **bundled 版本「發布日期」資料源**：firmware-management.md §3.3 範例顯示「2024-08 發行」等文案，但 architect 42 §2.1 `FirmwareVersion.ReleaseDate` 為 optional。需 Backend 在 bundle firmware 時準備 metadata（每個 version 目錄附 `META.json` 含 releaseDate / notes）。metadata 缺則 UI fallback 為不顯示日期。
6. **降版進行中關閉 Wails 控制台視窗的攔截邏輯**：依 R5-2 控制台關閉 = 結束 server。降版進行中關控制台 = 中斷降版 = 可能 brick。Frontend / Backend 是否需要在控制台側偵測「降版進行中」並擋下關閉動作？建議 Architect 補充。

---

**下一步：**
- 三方對 v2.1 最終收斂確認（Architect 回看 Design v2.1 是否全部修正到位）
- 使用者最終審 `v2/startup-progress.md` 的 6 階段 wireframe + 文案定版
- 確認後進入開發階段 M8-1 ~ M8-10
- 所有 v2 文件的決策引用格式：`[R5-X]` / `[R5-D-X]` / `[R5-E-X]` 以便追溯