jim800121/visionA
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
visionA/docs/autoflow/03-design/design-spec.md
jim800121chen fb7da5d180 chore(autoflow): migrate .autoflow/ 共享層文件至 docs/autoflow/ 
依 autoflow-agent workspace v2 設計把 PRD / 設計 / 架構 / 交付類
共享文件從個人層 .autoflow/（ignored）搬到 docs/autoflow/（進 git），
讓團隊可共享產品與架構文件，個人層只留 progress / review / testing 等
per-branch 筆記。

- 02-prd/        21 個檔（PRD、features、market-analysis 等）
- 03-design/     18 個檔（design-spec、wireframes、flows 等）
- 04-architecture/ 31 個檔（TDD、design-doc、ADR×14、API 規格等）
- 07-delivery/   3 個檔（project-summary、phase-0.6-handover、stage-deployment-setup）

合計 73 檔。原檔已從 .autoflow/ 移除（migration 工具執行 git mv，
但因 .autoflow/ 在 .gitignore 中、git 將此操作視為新增、無 rename history）。
2026-05-04 16:55:55 +08:00

16 KiB
Raw Blame History

visionA Cloud — 設計規格（Design Spec）索引

項目 內容
專案代號 visionA Cloud（visionA-frontend）
文件版本 v0.1（Phase 0 雛形規劃）
最後更新 2026-04-21
狀態 三方聯合討論中（Design Agent 產出）
主要負責 Design Agent
基礎設計稿 local-tool/frontend/ 既有實作（Shadcn 風）+ edge-ai-platform POC 的 clusters 頁面
模式 既有版型反向整理 + 補齊雲端版缺失 + 局部 Design Review

本規格從既有程式碼反向整理。版型與 Design Tokens 直接沿用 local-tool，以確保「離線版 / 雲端版同一套前端」的決策可執行。雲端版新增的頁面（登入、註冊、帳號、Pairing、Clusters）與狀態（在線 / 離線 / 遠端掉線）為本次新增設計。

文件結構

本規格採用模組化結構，避免單檔過大。本檔為索引，詳細內容拆成以下子檔案：

.autoflow/03-design/
├── design-spec.md                  ← 本檔（索引 + 設計系統概述 + 整體策略）
├── design-tokens.md                ← Design Tokens 三層架構
├── components.md                   ← 元件庫清單與規格
├── pages.md                        ← 頁面結構（既有 + 雲端新增）
├── flows/
│   ├── flow-pairing.md             ← Pairing 流程（最重要的新增流程）
│   ├── flow-offline-handling.md    ← 離線 / 掉線 UI 行為
│   ├── flow-auth.md                ← 登入 / 註冊流程（雛形 stub）
│   └── flow-conversion.md          ← 轉檔流程（Phase 0.8 新增）
├── design-review.md                ← 對既有 local-tool 版型的 Design Review
└── wireframes/                     ← 文字版 wireframe（僅針對雲端新增頁面）
    ├── wf-login.md
    ├── wf-register.md
    ├── wf-account.md
    ├── wf-pairing.md
    ├── wf-clusters.md
    └── wireframe-conversion.md     ← 轉檔頁面 wireframe（Phase 0.8 新增）

03-design/prototype/ 在 Phase 0 雛形暫不產出 high-fidelity prototype。版型直接沿用 local-tool 實作，前端工程師可直接參考 local-tool/frontend/ 複用元件。

1. 設計系統概述

1.1 設計哲學

「Editor-grade Console — 開發者每天要用 8 小時也不累的工作台」。

visionA Cloud 的使用者是開發者 / FAE / SI，不是一般消費者。他們：

  • 一天可能開著這個頁面數小時
  • 熟悉技術細節，不需要過度的引導
  • 重視資訊密度與快速操作，勝過視覺華麗
  • 多半在桌面環境工作（Mac / Windows）
  • 對載入狀態、連線狀態、錯誤訊息的「誠實性」非常敏感

設計原則（由此延伸）：

  1. 資訊優先於裝飾 — 任何視覺元素都要有功能理由。不用漸層、不用花俏動畫。
  2. 誠實呈現狀態 — 在線 / 離線 / 連線中 / 錯誤，一定要讓使用者看得出差別（不是只用顏色，必須搭配文字 / icon）。
  3. 一致性勝過驚喜 — 與 local-tool 完全共用同一套元件與版型，使用者在兩種模式間切換無感。
  4. 可預期勝過可愛 — 按鈕按下去會發生什麼事，應該從文字、位置、圖示就能預測。
  5. 鍵盤友善 — 所有操作都應該有鍵盤路徑（符合 WCAG 2.1 AA）。
  6. Dark Mode 第一 — 跟隨系統主題，不做強制光亮。

1.2 設計目標

目標 衡量方式（供 Testing 參考）
與 local-tool 視覺一致 同一使用者在兩種模式間能一眼認出是同個產品
雲端特性清晰 使用者隨時知道「我現在連的是哪台遠端裝置」「它在線嗎」
學習成本 < 10 分鐘 看得懂 Dashboard、能找到 /devices/pair、能開 Workspace
無障礙符合 WCAG 2.1 AA axe-core 自動掃描 0 個 Critical；鍵盤可操作所有核心流程
Dark Mode 完整 100% 頁面在 Dark Mode 下色彩對比達標

1.3 設計範圍（Phase 0 雛形）

類別 頁面 / 元件 範圍
沿用 local-tool（版型完全不動） /、/devices、/devices/[id]、/models、/models/[id]、/workspace、/workspace/[deviceId]、/settings 複用元件、複用 Design Tokens；只改 API base URL 的連法
從 POC 搬（適配雲端） /clusters、/workspace/cluster/[clusterId] 視覺風格與既有頁面對齊，搬完就等同「原生雲端功能」
雲端新增 — 雛形 stub /login、/register、/account 低保真，能 compile 可導覽即可，UI 細節可 Phase 1 細化
雲端新增 — 完整設計 /devices/pair、Sidebar 的帳號區塊、裝置掉線徽章與降級體驗 本次規格 focus 的核心
全域行為改動 頂部 ConnectionStatus、api.ts 錯誤處理、WebSocket 重連 UI 雲端場景連線邏輯不同，需要調整

1.4 設計範圍外（不做的事）

  • 高保真 prototype（Figma 或 HTML）— 版型沿用 local-tool，沒有價值
  • 行銷 Landing Page — 不在雛形範圍
  • Onboarding Wizard — 雲端版的 onboarding 等 Phase 1 再細化
  • Mobile 響應式完整版 — 雛形只保證 Desktop，Tablet 可讀，Mobile 降級（詳見第 6 節）
  • 重新發明 Design Tokens — 完全沿用 local-tool 的 CSS 變數

2. 子文件總覽

詳細內容在各子文件。以下是一句話摘要：

2.1 Design Tokens

完整沿用 local-tool 的 shadcn CSS 變數系統，包含 Reference / Semantic / Component 三層。色彩使用 oklch() 色彩空間、radius base 0.625rem、Tailwind 4 @theme inline。Dark Mode 透過 .dark class 切換。本專案不新增、不覆寫任何 Token。

2.2 元件庫清單

基礎 UI（Shadcn 風）22 個：Button、Card、Dialog、AlertDialog、Tabs、Input、Select、Badge、Slider、Progress、Checkbox、Label、Separator、ScrollArea、Sonner（toast）、EmptyState… 業務元件（沿用）：models/、devices/、inference/、camera/、dashboard/ Layout：Header、Sidebar、ConnectionStatus、HelpButton 新增（雲端版）：UserMenu、PairingTokenCard、RemoteDeviceBadge、NetworkErrorBanner

2.3 頁面結構

逐頁規格：沿用頁面列出「版型沿用 + 雲端適配點」，新增頁面列出「版型、主要區塊、互動重點」。雲端新增 5 個頁面（/login、/register、/account、/devices/pair、/clusters）。

2.4 Pairing 流程

雲端版最關鍵的新增流程。使用者在雲端 Web 登入 → 進 /devices/pair → 產生 Pairing Token（vAc_ + 32 字元 hex，TTL 15 分鐘，一次性使用；local agent 成功換取後獲得 90 天 Session Token 維持 tunnel，使用者感受不到後者）→ 複製 token → 到自己電腦的 local agent 貼上 → 顯示 local agent 已連上雲端 → 回 /devices 看到遠端裝置。

2.5 離線 / 掉線處理

雲端版特有：local agent 可能掉線、tunnel 可能斷。裝置列表、裝置詳情頁、Workspace 都要能「誠實顯示狀態」。建議新增一個全域的 RemoteDeviceBadge，在裝置列表 / 卡片 / Header 顯示「最後心跳 X 秒前」。

2.6 登入 / 註冊流程

Phase 0 雛形只需要 stub 頁面：Email + Password 輸入框、一個登入按鈕、一個「還沒有帳號？註冊」連結。後端尚未接，送出後直接跳 Dashboard 即可。實際 OAuth / 密碼驗證 Phase 1 再做。

2.7 Design Review

對既有 local-tool 版型做一次檢查。目前已知的改善點整理成 Critical / Major / Minor 三級，雛形階段不改，但寫進文件給 Phase 1+ 參考。

2.8 轉檔流程 + Wireframe

Phase 0.8 新增的核心動線。Sidebar 加「轉檔」tab（Wand2 icon），單頁 /conversion 用 state 機切 idle / uploading / processing / completed.success / completed.failed 五個畫面。上傳走 visionA backend streaming proxy（XHR + 進度條），轉檔以 polling（5–10 秒）追狀態，完成後半自動讓使用者選「加到模型庫」或「下載」（兩按鈕互不互斥）。失敗時顯示翻譯後的錯誤訊息（PRD §F5 對照表）+ suggestions。前端不持久化 jobId，由 backend GET /jobs/active 提供 source of truth，跨瀏覽器 / 多分頁 / 重新整理都能正確恢復。

3. 技術對齊

項目 決策 備註
UI 框架 Next.js App Router 16 + React 19 沿用 local-tool
樣式 Tailwind CSS 4 + shadcn/ui（Radix UI 封裝） 沿用
圖示 Lucide React 沿用
狀態管理 Zustand 5 沿用；新增 auth-store、session-store
Toast Sonner 沿用
i18n 自訂實作（src/lib/i18n），繁中 + English 沿用
圖表 Recharts 3 沿用（Workspace 效能圖表）
引導 driver.js 沿用（Dashboard onboarding）
無障礙 以 shadcn/ui 內建 ARIA 為基礎，關鍵頁面補強 目標 WCAG 2.1 AA
Dark Mode 跟隨系統主題（theme-sync.tsx） 沿用

4. 設計與開發的職責切分

為避免設計與實作脫節，明確職責：

誰做 什麼
Design Agent（本文件） Design Tokens 規格 / 元件清單 / 頁面結構 / 互動規格 / UX Writing 文案規範 / Design Review
Architect Agent API 契約 / Session 設計 / 狀態同步策略 / Token 生命週期
Frontend Agent 依本文件實作 React 元件 / 接 API / 實作 WebSocket 重連邏輯
PM Agent User Story / 成功指標 / Persona

設計規格有衝突時的排序： 使用者口述需求 > PRD > 本設計規格 > local-tool 現況 > 個人偏好。

5. 與 PM / Architect 的協作提醒

5.1 給 PM 的提醒

  • Phase 0 雛形不做完整 Onboarding。Dashboard 的 OnboardingDialog 在雲端版情境不合適（local-tool 的版本假設使用者「插 USB Dongle 掃描」，雲端版第一步是 Pairing），建議 Phase 1 重寫。
  • /settings 頁的「Advanced」分頁目前有 ServerStatusDashboard 與 ServerLogViewer，雲端版應該移除或重新定位（使用者看不到「他電腦上的 local agent log」，除非有專門的 remote log 設計）— 建議 Phase 1 再處理。
  • 未來如果有 Billing，/account 會擴展成 /account/*（profile / billing / api-keys / sessions）。Phase 0 只做單頁 stub。

5.2 給 Architect 的提醒

  • 裝置狀態同步：雲端版裝置狀態依賴 local agent 的 heartbeat / WebSocket，前端必須能顯示「上次心跳 X 秒前」。建議 API 直接回傳 lastSeenAt 欄位（ISO 8601）。
  • Pairing Token 顯示格式：設計上用「8+8 分隔顯示」（a1b2c3d4 e5f6g7h8）方便肉眼辨識複製；API 回傳請保持原始無空白字串，由前端格式化顯示。
  • WebSocket 重連策略：前端會用指數退避，但需要 Architect 確認後端能否容忍短暫重連抖動。
  • 錯誤分類：前端需要區分「雲端 API 不可達」（整個服務掛）vs「local agent 掉線」（單裝置不可用）。API 錯誤回應的 error.code 請明確分類，讓 UI 可以給不同提示。

6. 響應式策略（整體總綱，詳見 pages.md）

斷點 寬度 雛形策略
Mobile < 640px 降級顯示：能讀但不建議操作，顯示提示「建議使用桌面版」於關鍵頁面（如 Pairing、Workspace）
Tablet 640 – 1024px 可用：Sidebar 折疊為 drawer，主內容區單欄
Desktop 1024 – 1440px 主要目標：Sidebar 展開（w-60），主內容區自適應
Wide > 1440px 最大寬度限制 max-w-7xl（1280px）內容置中

核心決策：Desktop First。使用者是開發者，主要用桌機。Mobile 僅確保能登入、看 Dashboard 資訊、讀通知；不要求能操作推論。

7. 國際化策略（沿用 local-tool）

  • 支援語言：繁體中文（zh-TW）、English（en）
  • 預設語言：跟隨系統 locale，無法辨識則 en
  • 切換位置：/settings → 一般 → 語言；使用者選擇會存 localStorage
  • 文案位置：src/lib/i18n/zh-TW.ts、src/lib/i18n/en.ts
  • 新增雲端版的文案 key：
auth.login.*        登入頁
auth.register.*     註冊頁
auth.error.*        認證錯誤訊息
account.*           帳號設定頁
pairing.*           Pairing 頁與流程
cluster.*           叢集（已在 POC 存在，整併）
remote.*            遠端裝置相關（掉線、心跳、最後連線）
nav.cloudAppName    visionA Cloud（取代 visionA Local）
  • UX Writing 原則：參考 components.md 第 8 節。

8. 無障礙基準（WCAG 2.1 AA）

8.1 色彩對比

  • 一般文字對背景 ≥ 4.5:1
  • 大文字（18pt+/14pt Bold+）≥ 3:1
  • Icon / UI 元件 ≥ 3:1
  • 不只靠顏色傳達資訊（裝置狀態徽章同時有「圓點 + 文字」）

8.2 鍵盤操作

  • 所有互動元素可 Tab 聚焦
  • Focus ring 可見（shadcn 預設 ring-[3px] 已達標）
  • Modal 聚焦陷阱（Dialog 自動處理）
  • Escape 關閉 Modal（Dialog 自動處理）
  • Skip link（全新頁面需要加）

8.3 ARIA 與語意

  • 使用語意化 HTML（<nav>、<main>、<aside>、<header>）
  • 動態內容使用 aria-live 通知 Screen Reader（如 toast、裝置連線狀態變化）
  • 圖示只做裝飾時加 aria-hidden="true"
  • 表單 label 與 input 綁定

8.4 觸控目標（即使是桌面版）

  • 最小點擊區域 32×32（shadcn Button size=default h-9 px-4 剛好）
  • Mobile 版需求：最小 44×44（雛形不保證）

8.5 Reduce Motion

  • 支援 prefers-reduced-motion，停用非必要動畫（已由 Tailwind 4 內建）

詳細無障礙檢查項目見 design-review.md。

9. 交付物清單

本次 Design Agent 的交付：

檔案 內容 狀態
design-spec.md（本檔） 索引 + 設計系統概述 + 整體策略 ✅ 完成
design-tokens.md Design Tokens 三層架構（從 local-tool 反向整理） ✅ 完成
components.md 元件庫清單與規格 ✅ 完成
pages.md 頁面結構（逐頁） ✅ 完成
flows/flow-pairing.md Pairing 流程（核心新增） ✅ 完成
flows/flow-offline-handling.md 離線 / 掉線 UI 行為 ✅ 完成
flows/flow-auth.md 登入 / 註冊（雛形 stub） ✅ 完成
design-review.md 對 local-tool 的設計審查 ✅ 完成
wireframes/wf-*.md 文字版 wireframe（5 個新增頁面） ✅ 完成
prototype/ Hi-fi prototype ❌ 不做（雛形階段無價值）

10. TODO（需後續補齊）

項目 負責方 時機
/account 完整設計（Profile / API Keys / Sessions / Billing） Design Agent Phase 1
完整登入 / 註冊流程（含社群登入、密碼重設、Email 驗證） Design Agent Phase 1
雲端版 Onboarding（取代 local-tool 的 USB Dongle 版本） Design Agent + PM Phase 1
管理面 / Admin Console（若有多租戶管理需求） Design Agent Phase 2
Billing UI Design Agent + PM Phase 2
Mobile 完整響應式設計 Design Agent Phase 1+（待使用者回饋）
設計 QA（實作完成後） Design Agent Phase 0 開發完成時
對 ServerLogViewer / ServerStatusDashboard 在雲端情境的重新設計 Design Agent Phase 1

11. 交叉審閱點（Three-way review）

交給 PM 與 Architect 審閱時，請特別檢查：

PM 審閱：

  • 設計規格涵蓋的頁面是否與 PRD User Stories 完全對齊？
  • Pairing 流程的 UX 是否符合 Persona 使用情境？
  • UX Writing 的語調是否符合產品定位？

Architect 審閱：

  • RemoteDeviceBadge 顯示「最後心跳 X 秒前」需要後端提供 lastSeenAt，API 契約是否支援？
  • Pairing Token 的 vAc_ + 32 hex 格式與 15 分鐘 TTL 是否與後端實作一致？（已對齊 PRD / TDD）
  • WebSocket 掉線後的 UI 降級，前端要不要 fallback 到 polling？
  • 登入流程雛形的「送出直接跳轉」是否會導致未來改正式 auth 時大幅重寫？建議 Architect 確認 auth-store 的介面，讓雛形與正式實作 API 相容。