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

9.3 KiB
Raw Blame History

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] 以便追溯