jim800121/visionA
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
visionA/local-tool/.autoflow/03-design/design-spec-v2.md
jim800121chen 8cd5751ce3 feat(local-tool): M8 重構 — Wails 控制台 + 瀏覽器 Web UI（R5 決策） 
依 R5 五輪決策把 visionA-local 從「Wails 內嵌 Next.js」重構為「Wails
本機伺服器控制台 + 瀏覽器 Web UI」模式（類比 Docker Desktop / Ollama）。

程式碼變動
  - M8-1 砍 yt-dlp 全套（後端 resolver / URL handler / 前端 URL tab /
    Makefile vendor / installer / bootstrap / CI workflow，-555 行）
  - M8-2 砍 Mock 模式全套（driver/mock、mock_camera、Settings runtimeMode、
    VISIONA_MOCK 環境變數，-528 行）
  - M8-3 ffmpeg 從 GPL 切換到 LGPL 混合方案：Windows/Linux 用 BtbN 現成
    LGPL binary，macOS 自 build minimal decoder-only 進 git
    （vendor/ffmpeg/macos/ffmpeg 5.7MB + ffprobe 5.6MB，比 GPL 版省 85% 空間）
  - M8-4 Wails Server Controller：state machine、log ring buffer 2000 行、
    preferences.json atomic write、boot-id、Gin SkipPaths、shutdown 7+1 秒、
    notify_*.go 三平台 OS 通知、watchServer 改 Error state 不 os.Exit
  - M8-4b 啟動階段管線 R5-E：6 階段進度 event、20s soft / 60s hard timeout、
    stage 5/6 skip 規則、sentinel file、RestartStartupSequence 5 步驟
  - M8-5 Wails 控制台 vanilla HTML/JS/CSS（9 檔 ~2012 行）取代 M7-B splash：
    state 視覺、log panel、startup progress panel、Stage 6 manual CTA
    pulse、shutdown modal、Settings、Dark Mode、i18n 中英雙語
  - M8-6 上傳影片副檔名擴充（mp4/avi/mov/mpeg/mpg）
  - M8-7 Web UI Server Offline Overlay（role=alertdialog + focus trap +
    wsEverConnected 容錯 + Page Visibility）
  - M8-8 CORS middleware（127.0.0.1/localhost only + suffix attack 防護）+
    ws/origin.go 獨立 WebSocket CheckOrigin 避 package cycle
  - MAJ-4 server:shutdown-imminent WebSocket broadcast 機制
    （/ws/system endpoint + notifyShutdownImminent helper）
  - M8-9 Boot-ID + 瀏覽器 tab 自動重連（sessionStorage loop guard）

品質
  - ~105+ 新 unit test + race detector (-count=2) 全綠
  - 10 個 milestone 全部通過 Reviewer 審查
  - 三方 v2 + v2.1 文件（PRD / Design Spec / TDD）+ 交叉互審紀錄
    收錄在 .autoflow/

交付前待處理（M8-10）
  - 重跑 make payload-macos 把舊 GPL 77MB binary 換成新 LGPL
  - 三平台 end-to-end build 驗證

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-15 17:57:54 +08:00

128 lines
9.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

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 設計規格 v2（索引）
> Design Agent · 第五輪正式規格 · 初版 2026-04-14
> **目前版本：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 未動到的章節（仍以 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 → 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.1 最終收斂確認（Architect 回看 Design v2.1 是否全部修正到位）
- 使用者最終審 `v2/startup-progress.md` 的 6 階段 wireframe + 文案定版
- 確認後進入開發階段 M8-1 ~ M8-10
- 所有 v2 文件的決策引用格式：`[R5-X]` / `[R5-D-X]` / `[R5-E-X]` 以便追溯
Reference in New Issue View Git Blame Copy Permalink