visionA/docs/autoflow/03-design/pages.md

頁面結構規格 — visionA Cloud

本文件逐頁列出所有頁面的版型、主要區塊、互動重點與雲端版改動。

• 沿用頁面：版型與行為 100% 沿用 local-tool，只改 API base URL 與新增遠端狀態顯示
• 雲端新增 stub：Phase 0 雛形只做低保真骨架，Phase 1 完整化
• 雲端新增完整：本次完整設計，工程師可直接實作

---

頁面總覽

路由	類型	主要元件	Phase 0 狀態
/	沿用	Dashboard（Stats + Activity + Devices）	沿用 + 小調整
/login	新增 stub	登入表單	Stub（簡化）
/register	新增 stub	註冊表單	Stub（簡化）
/account	新增 stub	帳號設定	Stub（單頁）
/devices	沿用	裝置列表	沿用 + 改造
/devices/pair	新增	Pairing 流程	完整設計
/devices/[id]	沿用	裝置詳情	沿用 + 遠端狀態
/models	沿用	模型庫	沿用
/models/[id]	沿用	模型詳情	沿用
/clusters	從 POC 搬	叢集列表	沿用 POC 設計
/workspace	沿用	工作區選擇	沿用 + 遠端狀態
/workspace/[deviceId]	沿用	推論操作	沿用 + 掉線降級
/settings	沿用	設定	沿用 + 小調整

---

1. / — Dashboard（儀表板）

類型：沿用 + 小調整

1.1 既有版型（不變）

┌─────────────────────────────────────────────────────────┐
│                  標題 + 副標題                           │
├─────────────────────────────────────────────────────────┤
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐    │
│  │ StatCard │ │ StatCard │ │ StatCard │ │ StatCard │    │
│  │ 模型數    │ │ 裝置數    │ │ 已連線    │ │ 燒錄次數  │    │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘    │
├─────────────────────────────────────────────────────────┤
│  ┌──────────────────────┐  ┌──────────────────────┐     │
│  │ ConnectedDevicesList │  │ ActivityTimeline     │     │
│  │（已連線裝置）          │  │（近期活動）            │     │
│  └──────────────────────┘  └──────────────────────┘     │
├─────────────────────────────────────────────────────────┤
│  Quick Actions                                          │
│  [瀏覽模型] [管理裝置] [上傳模型]                          │
└─────────────────────────────────────────────────────────┘

1.2 雲端版調整

項目	改動
標題	visionA Local → visionA Cloud
StatCard「已連線」	指「線上遠端裝置」，不再是 USB 連接狀態
ConnectedDevicesList	每個項目右側新增 RemoteDeviceBadge（離線 / 最後心跳）
OnboardingDialog	Phase 0 暫時移除（或改為「去配對裝置」CTA）
Quick Actions	新增「配對裝置（Pair Device）」按鈕，導向 /devices/pair

1.3 空狀態

當使用者是第一次進入（沒有裝置、沒有活動）：

┌─────────────────────────────────────────────────────────┐
│         🔗                                              │
│         還沒有任何裝置                                    │
│         配對你的第一台 Kneron 裝置，開始雲端推論之旅          │
│                                                         │
│         [配對裝置]                                        │
└─────────────────────────────────────────────────────────┘

使用 EmptyState 元件，Icon=Lucide Link2，action=跳 /devices/pair。

1.4 互動重點

• StatCard 點擊 → 跳對應列表頁
• ConnectedDevicesList 點擊裝置 → 跳 /workspace/[deviceId]
• ActivityTimeline 自動 polling / WebSocket 更新（每 5 秒 or 即時）

---

2. /login — 登入（新增 stub）

類型：新增 stub（Phase 0 簡化，Phase 1 完整化）

2.1 Phase 0 版型

┌─────────────────────────────────────────────────────────┐
│                                                         │
│                                                         │
│                  [Logo] visionA Cloud                    │
│                  Edge AI Platform                       │
│                                                         │
│          ┌────────────────────────────────┐            │
│          │  Email                          │            │
│          │  ┌────────────────────────┐    │            │
│          │  │ you@example.com        │    │            │
│          │  └────────────────────────┘    │            │
│          │                                 │            │
│          │  Password                       │            │
│          │  ┌────────────────────────┐    │            │
│          │  │ ••••••••               │    │            │
│          │  └────────────────────────┘    │            │
│          │                                 │            │
│          │  [        登入         ]        │            │
│          │                                 │            │
│          │  ────── 還沒有帳號？ ──────       │            │
│          │  [      建立新帳號       ]       │            │
│          └────────────────────────────────┘            │
│                                                         │
│          忘記密碼？  |  語言切換：繁中 ▾                  │
│                                                         │
└─────────────────────────────────────────────────────────┘

2.2 規格

• Layout：無 Sidebar / Header 的獨立版型（app/(auth)/layout.tsx）
• 容器：max-w-md 置中，背景 bg-background
• Logo：與 Sidebar 同一個（/visiona-logo.png）
• 表單：Card 包起來，內含 Label + Input + Button
• 登入按鈕：variant=default size=default 撐滿寬度（w-full）
• 註冊連結：variant=outline 撐滿寬度
• 底部：忘記密碼連結 + 語言切換（小型 Select）

2.3 Phase 0 雛形簡化

• 送出表單不接後端：直接 router.push('/')
• 表單驗證：只有「必填」（HTML5 required），無格式驗證
• 「忘記密碼」：灰色 disabled
• 「建立新帳號」：跳 /register
• 登入 error 狀態：不做

2.4 Phase 1 待辦

• OAuth（Google / GitHub）
• 密碼強度驗證、Email 格式驗證
• 「記住我」Checkbox
• Email 驗證流程
• 登入失敗的明確錯誤訊息（密碼錯 / 帳號不存在 / 被鎖）
• Rate limit 提示
• 雙因素驗證（2FA）

2.5 響應式

• Desktop / Tablet / Mobile 都單欄置中，自然 responsive
• Mobile：表單寬度自適應 w-full + padding px-4

2.6 i18n key（新增）

auth.login.title → 登入 / Sign in
auth.login.subtitle → 歡迎回到 visionA Cloud
auth.login.email → Email
auth.login.password → 密碼 / Password
auth.login.submit → 登入
auth.login.forgotPassword → 忘記密碼？
auth.login.noAccount → 還沒有帳號？
auth.login.createAccount → 建立新帳號

2.7 無障礙

• 表單 Label 與 Input htmlFor / id 對應
• Email input type="email" autoComplete="email"
• Password input type="password" autoComplete="current-password"
• 提交按鈕在 Input 聚焦時 Enter 可觸發
• Tab 順序：Email → Password → 登入 → 建立新帳號 → 忘記密碼 → 語言

---

3. /register — 註冊（新增 stub）

類型：新增 stub

3.1 Phase 0 版型

與 /login 類似，差異：

標題：建立帳號
表單欄位：
  - Email（必填）
  - 密碼（必填）
  - 確認密碼（必填，與密碼相同）
按鈕：[建立帳號] → 成功後跳 /devices/pair（引導第一次配對）
返回連結：已有帳號？ [登入]

3.2 雛形簡化

• 送出不接 API，直接 router.push('/devices/pair')（引導第一次 Pairing）
• 密碼確認檢查：用 client-side 即時比對（失焦驗證）
• 無 ToS / Privacy Policy 勾選（Phase 1 補）

3.3 Phase 1 待辦

• Email 驗證流程
• 密碼強度指示器
• ToS / Privacy Policy 勾選
• 防機器人（reCAPTCHA / Turnstile）
• 重複 Email 檢查

---

4. /account — 帳號設定（新增 stub）

類型：新增 stub（Phase 0 單頁，Phase 1 拆成多頁）

4.1 Phase 0 版型

┌─────────────────────────────────────────────────────────┐
│ 帳號設定                                                  │
│ 管理你的個人資料與偏好                                     │
├─────────────────────────────────────────────────────────┤
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 個人資料                                              │ │
│ │ Email       jim@example.com（不可編輯）               │ │
│ │ 顯示名稱    [Jim Chen____________] [儲存]             │ │
│ └─────────────────────────────────────────────────────┘ │
│                                                         │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 已配對的裝置                                          │ │
│ │  • KL520 (192.168.1.23)  配對於 04/18  [解除配對]     │ │
│ │  • KL720 (office-mac)    配對於 04/21  [解除配對]     │ │
│ └─────────────────────────────────────────────────────┘ │
│                                                         │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 危險區（Danger Zone）                                 │ │
│ │ 刪除帳號 [刪除帳號]                                    │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘

4.2 規格

• 使用既有 Tabs or 單頁 Card 多區塊（雛形選單頁）
• 每個區塊 Card，內含 Header + Content
• 危險區使用 destructive 變體

4.3 雛形簡化

• 所有操作不接 API，按鈕點擊只顯示 toast「此功能開發中」
• 資料顯示為假資料（mock）
• 「刪除帳號」按下後只顯示 AlertDialog，確認後也不真執行

4.4 Phase 1 TODO

• 拆成子路由 /account/profile、/account/devices、/account/api-keys、/account/sessions
• 頭像上傳
• 密碼變更
• API Keys 管理
• Session 管理（顯示登入過的裝置 / 瀏覽器）
• Billing 頁面
• 團隊 / 組織切換

---

5. /devices — 裝置列表（沿用 + 改造）

類型：沿用版型，改造行為

5.1 既有版型

┌─────────────────────────────────────────────────────────┐
│ 裝置                          [安裝 USB Driver] [掃描]    │
│ 管理你的 Edge AI 裝置                                     │
├─────────────────────────────────────────────────────────┤
│ [⚠ udev hint banner，需要時顯示]                          │
├─────────────────────────────────────────────────────────┤
│ ┌──────────┐ ┌──────────┐ ┌──────────┐                  │
│ │ Device    │ │ Device    │ │ Device    │                  │
│ │ Card      │ │ Card      │ │ Card      │                  │
│ └──────────┘ └──────────┘ └──────────┘                  │
└─────────────────────────────────────────────────────────┘

5.2 雲端版改造

項目	改動
右上按鈕	移除「安裝 USB Driver」「掃描」（local-tool 限定）；新增 [配對新裝置] → 導向 /devices/pair
udev hint banner	移除（雲端版不需要）
DeviceCard	右上角狀態從 DeviceStatusBadge 改為 RemoteDeviceBadge；顯示「最後心跳」
空狀態	無裝置時顯示：「還沒有配對的裝置，[配對第一台裝置] →」
排序 / 篩選	Phase 0 維持原樣（按建立時間排序）；Phase 1 加篩選「在線 / 全部」

5.3 空狀態設計

┌─────────────────────────────────────────────────────────┐
│              🔗                                         │
│         還沒有配對的裝置                                   │
│    在你的電腦上執行 local agent 並完成配對，              │
│    就能從任何地方存取你的 Kneron 裝置                     │
│                                                         │
│    [配對第一台裝置]  [查看配對說明]                         │
└─────────────────────────────────────────────────────────┘

---

6. /devices/pair — Pairing 流程（新增 — 完整設計）

類型：新增，雲端版核心流程。

完整設計見 flows/flow-pairing.md 與 wireframes/wf-pairing.md。

6.1 簡要概念

三步式 Stepper：

[1] 取得 Token  →  [2] 下載 / 設定 local agent  →  [3] 確認連線

• 第 1 步：PairingTokenCard（見 components.md 10.2）
• 第 2 步：平台選擇（Mac / Windows / Linux）→ 顯示下載連結 + 一行設定指令
• 第 3 步：即時狀態（polling /api/pairing/status?token=...）→ 成功後自動跳 /devices

---

7. /devices/[id] — 裝置詳情（沿用 + 遠端狀態）

類型：沿用版型 + 小擴充

7.1 既有版型

┌─────────────────────────────────────────────────────────┐
│ ← 返回                                                   │
│ [裝置名稱] (alias)                                        │
│ [原始名稱]                                                │
│ [DeviceStatusBadge]           [燒錄] [開啟工作區] [中斷]    │
├─────────────────────────────────────────────────────────┤
│ ┌──────────────────────┐  ┌──────────────────────┐      │
│ │ 裝置資訊              │  │ 模型狀態              │      │
│ │ ID / 類型 / 韌體 / Port│  │ 已燒錄模型 / 準備狀態  │      │
│ └──────────────────────┘  └──────────────────────┘      │
│ ┌──────────────────────┐  ┌──────────────────────┐      │
│ │ DeviceHealthCard     │  │ DeviceConnectionLog  │      │
│ └──────────────────────┘  └──────────────────────┘      │
│ DeviceSettingsCard（alias / notes）                      │
└─────────────────────────────────────────────────────────┘

7.2 雲端版擴充

項目	改動
標題區狀態	DeviceStatusBadge → RemoteDeviceBadge（顯示最後心跳時間）
DeviceHealthCard	新增 Pairing Token（遮罩顯示後 4 碼）、配對時間、所在電腦 hostname（local agent 提供）
DeviceConnectionLog	新增 tunnel reconnect 事件
DeviceSettingsCard	新增「解除配對」按鈕（destructive）

7.3 掉線降級

當裝置 RemoteDeviceBadge.status === 'offline'：

• 大型警告橫幅：「此裝置目前離線，部分操作無法使用」
• 「燒錄」「開啟工作區」按鈕 disabled
• 顯示最後已知狀態（韌體版本、已燒錄模型等，讀自 cache）
• 「解除配對」仍可用

---

8. /models、/models/[id]、/workspace、/settings（沿用）

8.1 /models — 模型庫

• 版型完全沿用（ModelGrid + ModelFilters + ModelUploadDialog + 比較模式）
• 雲端版差異：上傳 .nef 走雲端儲存（S3-compat），UI 不變
• 空狀態使用既有 EmptyState

8.2 /models/[id] — 模型詳情

• 完全沿用
• 「部署至裝置」的 FlashDialog 會列出使用者所有在線遠端裝置

8.3 /workspace — 工作區選擇

• 版型沿用（卡片網格，每個是可開啟工作區的裝置）
• 雲端版：卡片上顯示 RemoteDeviceBadge；離線裝置卡片 opacity-50 且 disabled 無法點擊
• 空狀態保持：「沒有已連線的裝置，前往裝置管理」

8.4 /workspace/[deviceId] — 推論操作介面

• 版型完全沿用（左側 CameraInferenceView + 右側 InferencePanel）
• 新增掉線降級：
  • 頂部新增 RemoteDeviceBadge，顯著顯示狀態
  • 裝置掉線時：
    • 停止推論（前端主動呼叫 stop）
    • 顯示全頁遮罩：「裝置已離線，請稍候或返回裝置列表」+ 兩個按鈕 [返回] [重試]
    • Camera stream 暫停，顯示「連線中斷」占位圖

8.5 /settings — 設定

• 版型沿用 Tabs（一般 / 硬體 / 模型 / 進階）
• 雲端版調整：
  • 「硬體」分頁：Phase 0 暫時隱藏或改名（雲端版使用者看不到自己電腦的 Python runtime）；Phase 1 改為「Local Agent 設定」
  • 「進階」分頁：ServerStatusDashboard / ServerLogViewer 暫時隱藏；Backend URL 可改為「雲端 API Endpoint」（開發者可切 staging / production）
  • 「一般」分頁不變

---

9. /clusters — 叢集列表（從 POC 搬）

類型：從 edge-ai-platform POC 搬，視覺對齊既有版型

9.1 版型（已在 POC 存在）

┌─────────────────────────────────────────────────────────┐
│ 叢集                              [建立叢集]              │
│ 管理你的多裝置推論叢集                                     │
├─────────────────────────────────────────────────────────┤
│ ┌──────────┐ ┌──────────┐ ┌──────────┐                  │
│ │ Cluster   │ │ Cluster   │ │ Cluster   │                  │
│ │ Card      │ │ Card      │ │ Card      │                  │
│ └──────────┘ └──────────┘ └──────────┘                  │
└─────────────────────────────────────────────────────────┘

每個 ClusterCard（見 POC cluster-card.tsx）：

• 叢集名稱 + 狀態 Badge（idle / inferencing / degraded）
• 裝置數量、模型
• 裝置列表（每個顯示 deviceName + type + weight）
• 操作：[開啟工作區] / [刪除]

9.2 雲端版調整

項目	改動
裝置列表顯示	每個裝置項目新增 RemoteDeviceBadge（顯示在線狀態）
degraded 狀態	Badge 旁新增 tooltip 說明「某裝置離線，已自動降級」
建立叢集 Dialog	Device 選擇只列出「在線」裝置

9.3 空狀態

還沒有叢集
叢集讓你把多台 Kneron 裝置組合起來做平行推論

[建立第一個叢集]（disabled 當沒有任何裝置時）

9.4 /workspace/cluster/[clusterId] — 叢集工作區

• 從 POC 搬（workspace/cluster/[clusterId]/cluster-workspace-client.tsx）
• 視覺對齊單裝置 Workspace，版型相似
• 裝置狀態列顯示所有叢集成員的 RemoteDeviceBadge
• 任一裝置離線 → 狀態列顯示「降級執行中（X/Y 裝置在線）」

---

10. 頁面互動總表

頁面	主要互動	資料載入方式
/	讀取 stats、裝置、活動	useEffect + polling / WS
/login	提交登入	form submit
/register	提交註冊	form submit
/account	編輯個人資料	form submit
/devices	列表、配對 CTA	useEffect + WS
/devices/pair	產 token、複製、輪詢	polling(/api/pairing/status)
/devices/[id]	CRUD 裝置設定、燒錄、開工作區	useEffect + WS
/models	篩選、上傳、比較	useEffect
/models/[id]	檢視、部署、刪除	useEffect
/clusters	建立、開啟工作區、刪除	useEffect
/workspace	選擇裝置	useEffect
/workspace/[deviceId]	推論控制（start/stop/source）	useEffect + WS
/workspace/cluster/[id]	叢集推論	useEffect + WS
/settings	切語言、主題、重置	localStorage

---

11. 響應式表現（逐頁）

頁面	Mobile (< 640px)	Tablet (640–1024)	Desktop (≥ 1024)
/	降級（單欄）	單欄	4 欄 Stats + 2 欄主內容
/login / /register	可用	可用	可用
/devices / /models / /clusters	單欄卡片	2 欄	3 欄
/devices/pair	可用（步驟堆疊）	可用	可用（步驟橫排）
/workspace/[deviceId]	不支援（顯示提示「請用桌面版」）	簡化（上下排）	左右分欄
/settings	單欄 Tab	單欄	單欄（Tab 橫排）

雛形 Mobile 策略：

• Sidebar 改 Sheet（drawer），漢堡選單觸發
• 非關鍵頁面能用，但不保證完整體驗
• /workspace/[deviceId] 這類需要大畫面的，顯示：「建議使用桌面版以獲得最佳體驗」

---

12. 頁面載入策略

所有頁面：

載入階段	顯示
0–200ms	什麼都不顯示（避免閃爍）
200ms–資料回傳	Skeleton（灰色塊，shimmer 動畫可選）
資料回傳	內容顯示
資料錯誤	錯誤狀態 + 重試按鈕
資料為空	EmptyState

Skeleton 使用 shadcn 慣例 bg-muted animate-pulse，已在 device-detail-client.tsx 示範。