jim800121/visionA
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
visionA/local-tool/.autoflow/03-design/design-spec.md
jim800121chen c54f16fca0 Initial commit: visionA monorepo with local-tool subproject 
local-tool/: visionA-local desktop app
- M1: Wails shell + Go server + Next.js UI + Mock mode (macOS dmg ready)
- M2: i18n (zh-TW/en) + Settings 4-tab refactor
- M3: Embedded Python 3.12 runtime (python-build-standalone) + KneronPLUS wheels
- M4: Windows Inno Setup script (build on Windows runner)
- M5: Linux AppImage script + udev rule (build on Linux runner)
- M6: ffmpeg (GPL, pending legal review) + yt-dlp bundled
- Lifecycle: watchServer health check, fatal native dialog,
            Wails IPC raise endpoint, stale process cleanup

.autoflow/: full PRD / Design Spec / Architecture / Testing docs
            (4 rounds tri-party discussion + cross review)
.github/workflows/: macOS / Windows / Linux build CI

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-11 22:10:38 +08:00

7.7 KiB
Raw Blame History

visionA-local 設計規格（索引）

Design Agent · 第二輪正式規格 · 2026-04-11（第三輪修訂 2026-04-11） 本文件為索引檔，各章節詳細內容請見 spec/ 子檔。所有決策依據 progress.md（2026-04-11）定案。

文件結構

# 章節 檔案 一句話摘要
1 資訊架構（IA） spec/01-information-architecture.md 4 主區塊 + Settings，sidebar 導航，無 deep link
2 頁面清單與變更對照 spec/02-pages-diff.md 對照原 edge-ai-platform 的保留／刪除／修改
3 主要頁面 Wireframe spec/03-wireframes.md Dashboard / Models / Devices / Workspace / Settings 結構描述
4 First-Run Experience spec/04-first-run.md 歡迎 → 模式選擇 → 硬體偵測，可跳過
5 Tray 互動規格 — 已於第三輪決策 Q-A 砍除（不做 tray）。編號保留以避免後續引用失效
6 跨平台 UX 差異 spec/06-cross-platform.md title bar、快捷鍵、對話框、通知
7 Design Tokens spec/07-design-tokens.md 沿用 edge-ai-platform oklch tokens，補 L 級 elevation
8 錯誤與空狀態 spec/08-states.md 全域錯誤分級 + 空狀態文案庫
9 無障礙（A11y） spec/09-accessibility.md 盡力而為（R4-3 降級，非硬性目標）— 保留鍵盤、焦點、語意化 HTML 等低成本項目
10 i18n 策略 spec/10-i18n.md 中英雙語，跟隨系統，沿用 react-i18next

關鍵設計決策（摘要）

  1. 視窗模型：傳統桌面 app — 關閉視窗 = 結束程式。不做 tray icon（第三輪決策 Q-A），省跨平台圖資產與 Wails tray 踩坑，也避免與「關閉 = 結束」的語意衝突。
  2. 資訊架構扁平化：從原 5 區（含 clusters）瘦身為 4 主區 + Settings。所有 cluster／relay 相關入口完全移除，M1 就一次清乾淨（第三輪決策 Q-C）。
  3. Dashboard 重定位：原本是叢集總覽，現在改成「快速開始 + 單機狀態卡」，把首頁價值從「監看」轉為「起手」。
  4. 預設真實硬體模式：首次啟動不預設 Mock，但在模式選擇步驟提供 Mock 作為明確替代，且可隨時切換。
  5. First-Run 可全跳過：三步流程（歡迎 / 模式 / 偵測），每一步右上都有「略過」，降低挫敗。
  6. 深色模式跟隨系統：不提供手動切換（Settings 僅顯示「目前跟隨系統」唯讀狀態，避免決策疲勞）。
  7. 中英雙語：預設跟隨系統 Locale（zh-* → 繁中；其他 → 英文），Settings 可手動切換。
  8. Logo 沿用 edge-ai-platform：暫不重新設計品牌識別，僅把產品字樣改為「visionA-local」。
  9. Design Tokens 完全沿用：原專案使用 shadcn + oklch 中性色盤，local 版無變更，只補 desktop 專用的 elevation 與 window chrome token。
  10. Settings 重構為分頁式：一般 / 硬體 / 模型 / 進階（4 分頁，第三輪決策 Q-E3 取消「外觀」分頁，語言併入「一般」）。
  11. macOS 資料目錄：~/Library/Application Support/visiona-local/（第三輪決策 Q-E1，遵循 OS 慣例；第四輪 R4-5 全小寫對齊 Bundle ID 與 Linux 慣例）。

第四輪決策採納對照（2026-04-11 交叉審閱後）

# 決策 落地位置
R4-2 MJPEG 延遲目標：首次 ≤250ms / 穩定後 ≤150ms spec/03-wireframes.md Workspace Perf 示例值改為 180ms
R4-3 WCAG 2.2 AA 降級為「盡力而為」（非硬性目標） spec/09-accessibility.md 全節改寫、design-spec 索引同步
R4-5 資料目錄全小寫 visiona-local（對齊 Bundle ID 與 Linux 慣例） spec/06-cross-platform.md §6.7、spec/04-first-run.md §4.1/§4.6/§4.7、spec/03-wireframes.md §3.5、spec/10-i18n.md §10.2
R4-6 ⌘R → ⌘Shift+R；⌘Shift+W 取消 spec/06-cross-platform.md §6.2
R4-8 通知策略：裝置連/斷 → App toast；Server 崩潰 → OS 原生通知 spec/06-cross-platform.md §6.4
— Single-instance 第二次啟動 → 靜默 raise（不彈 toast） spec/06-cross-platform.md §6.9（新增）
— Python sidecar crash loading + 自動重啟 spec/08-states.md §8.8（新增）
— Python 雙策略切換 UI 入口 spec/03-wireframes.md §3.5 Settings > 進階
— 深色模式：CSS prefers-color-scheme（不需 JS emit event） spec/06-cross-platform.md §6.8、spec/07-design-tokens.md §7.5 註記
— i18n 即時切換 → M2 才做 spec/10-i18n.md §10.7 明確標註

已知 contingency

  • R9 Kneron 預置模型 re-distribution：第四輪 R4-1 決定繼續內嵌、不主動問 Kneron，發佈前 gate 維持。若 R9 觸發，First-Run 需插入「下載預置模型」步驟，完整 fallback 流程的 Wireframe 與互動規格草案保留在 design-cross-review.md §「R9 Plan B 的 First-Run 下載流程草案」，目前不納入正式 design-spec（避免誤導開發團隊）。若真的觸發，會把該草案升格為 spec/04-first-run-plan-b.md。

第三輪決策採納對照

# 原疑問 第三輪結果
1 Tray 是否要做？ Q-A 砍掉 tray。05-tray.md 已刪除；⌘0 顯示主視窗 等 tray 相關快捷鍵同步移除
3 Workspace 升為 sidebar 一級 Q-E2 採納。IA 已確定 4 主區塊含 Workspace
4 Settings「外觀」分頁取消 Q-E3 採納。Settings 為 4 分頁（一般 / 硬體 / 模型 / 進階），語言在「一般」
— macOS 資料目錄 Q-E1：~/Library/Application Support/visiona-local/（取代 ~/.visiona-local/，R4-5 全小寫）
— M1 範圍 Q-C：M1 就要清乾淨前端 cluster/relay UI，不分期

第三輪修訂後仍待確認 / 仍需使用者回饋

  1. Mock 模式的視覺標記（沿用第二輪建議） 預設真實硬體模式後，Mock 變成明確的「次要體驗」。建議在 header 右側加一個永久性 Mock badge（黃色），避免使用者誤把假結果當成真推論。此項已寫入 wireframe，未見使用者反對，視為採納。

  2. 簽章警示的 UX（Q2 決策：不買憑證） macOS 會跳 Gatekeeper 警告、Windows 會跳 SmartScreen。這些是 OS 層的對話框，App 內無法攔截；但首次啟動完成後的「歡迎畫面」應該主動說明「你可能剛才看到警告，那是因為我們是內部工具，已經安全」，降低焦慮。文案已寫入 04-first-run.md。

  3. 快捷鍵衝突（tray 砍除 + 第四輪 R4-6 重整後） 最小快捷鍵集：⌘, (Settings)、⌘W（關閉＝結束）、⌘Q（結束）、⌘1~4（切換主區塊，⌘4 即前往 Workspace）、⌘Shift+R（重新整理裝置）、⌘U（上傳模型）。 R4-6 變更：

    • ⌘R → ⌘Shift+R（避免與 WebView 的 reload 衝突）
    • 取消 ⌘Shift+W（與 macOS 內建「關閉所有視窗」衝突；⌘4 已涵蓋前往 Workspace）
    • 原 ⌘0 顯示主視窗（從 tray） 已於第三輪隨 tray 移除。

  4. [第三輪新增] Mock 模式切換入口的去留 砍掉 tray 後，原本 tray 選單提供的「一鍵切換 Mock ↔ Real」捷徑消失。目前 Mock 切換入口剩下：

    • Settings > 硬體（主要入口）
    • Devices 頁面右上角的「真實 / Mock」pill 切換
    • First-Run Step 2（僅首次）

    Design 認為這樣夠用（切換頻率不高），但若未來使用者抱怨「找不到切換入口」，可考慮在 Dashboard 的 Quick Start 區加一個二級行動。目前不改。

下一步：

  • PM / Architect 交叉 review 本規格第三輪修訂版
  • 三方確認後進入 Prototype 階段（HTML/CSS 原型，後續迭代處理）