jim800121chen
fb7da5d180
依 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）。
310 lines
16 KiB
Markdown
310 lines
16 KiB
Markdown
# 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](design-tokens.md)
|
||
|
||
**完整沿用 local-tool 的 shadcn CSS 變數系統**，包含 Reference / Semantic / Component 三層。色彩使用 `oklch()` 色彩空間、radius base `0.625rem`、Tailwind 4 `@theme inline`。Dark Mode 透過 `.dark` class 切換。**本專案不新增、不覆寫任何 Token。**
|
||
|
||
### [2.2 元件庫清單](components.md)
|
||
|
||
**基礎 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 頁面結構](pages.md)
|
||
|
||
逐頁規格：沿用頁面列出「版型沿用 + 雲端適配點」，新增頁面列出「版型、主要區塊、互動重點」。雲端新增 5 個頁面（`/login`、`/register`、`/account`、`/devices/pair`、`/clusters`）。
|
||
|
||
### [2.4 Pairing 流程](flows/flow-pairing.md)
|
||
|
||
**雲端版最關鍵的新增流程**。使用者在雲端 Web 登入 → 進 `/devices/pair` → 產生 Pairing Token（`vAc_` + 32 字元 hex，TTL **15 分鐘**，一次性使用；local agent 成功換取後獲得 90 天 Session Token 維持 tunnel，使用者感受不到後者）→ 複製 token → 到自己電腦的 local agent 貼上 → 顯示 local agent 已連上雲端 → 回 `/devices` 看到遠端裝置。
|
||
|
||
### [2.5 離線 / 掉線處理](flows/flow-offline-handling.md)
|
||
|
||
雲端版特有：local agent 可能掉線、tunnel 可能斷。裝置列表、裝置詳情頁、Workspace 都要能「誠實顯示狀態」。建議新增一個全域的 `RemoteDeviceBadge`，在裝置列表 / 卡片 / Header 顯示「最後心跳 X 秒前」。
|
||
|
||
### [2.6 登入 / 註冊流程](flows/flow-auth.md)
|
||
|
||
Phase 0 雛形只需要 **stub 頁面**：Email + Password 輸入框、一個登入按鈕、一個「還沒有帳號？註冊」連結。後端尚未接，送出後直接跳 Dashboard 即可。實際 OAuth / 密碼驗證 Phase 1 再做。
|
||
|
||
### [2.7 Design Review](design-review.md)
|
||
|
||
對既有 local-tool 版型做一次檢查。目前已知的改善點整理成 Critical / Major / Minor 三級，**雛形階段不改**，但寫進文件給 Phase 1+ 參考。
|
||
|
||
### [2.8 轉檔流程](flows/flow-conversion.md) + [Wireframe](wireframes/wireframe-conversion.md)
|
||
|
||
**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 相容。
|