# Wireframe — `/devices/pair` > 文字版 wireframe。雲端版最重要的新頁面。對應設計規格見 `flows/flow-pairing.md`。 --- ## 佈局（Desktop） ``` ┌────────────────────────────────────────────────────────────────┐ │ [Sidebar] [Header] │ │ ────────────────────────────────────────────────────────────── │ │ │ │ [← 返回] │ │ │ │ 配對新裝置 │ │ 讓你的 Kneron 裝置連上雲端，就能從任何地方遠端操作 │ │ │ │ ─────────────── Stepper ─────────────── │ │ │ │ ● ──────────── ○ ──────────── ○ │ │ 1 2 3 │ │ 取得 Token 設定 Local Agent 確認連線 │ │ │ │ ─────────────── Step 1 內容 ─────────────── │ │ │ │ ┌───────────────────────────────────────────────────────┐ │ │ │ Card: PairingTokenCard │ │ │ │ │ │ │ │ 🔗 你的 Pairing Token │ │ │ │ │ │ │ │ 複製下方 token，在 Step 2 讓 local agent 使用 │ │ │ │ │ │ │ │ ┌────────────────────────────────────────────────┐ │ │ │ │ │ bg-muted, font-mono, text-xl, tracking-wider │ │ │ │ │ │ vAc_a1b2c3d4e5f6a7b8 │ │ │ │ │ │ c9d0e1f2a3b4c5d6e7f8 │ │ │ │ │ │ select-all, p-4, rounded-md │ │ │ │ │ │ (視覺切兩行；複製 = 完整 36 字元無空白) │ │ │ │ │ └────────────────────────────────────────────────┘ │ │ │ │ │ │ │ │ [📋 複製] [🔄 重新產生] │ │ │ │ │ │ │ │ ⏱ 剩餘 14:52 ────────────────── │ │ │ │ (進度條 bg-primary → amber(≤10:00) → red(≤3:00)) │ │ │ │ 過期時 token 轉灰 + 複製 disabled │ │ │ │ 📅 產生時間：14:30 │ │ │ └───────────────────────────────────────────────────────┘ │ │ │ │ ┌───────────────────────────────────────────────────────┐ │ │ │ ⚠ bg-amber-50 Alert │ │ │ │ 這組 token 15 分鐘內有效，請立刻到 Step 2 完成配對 │ │ │ │ token 是一次性使用，完成配對後自動失效 │ │ │ └───────────────────────────────────────────────────────┘ │ │ │ │ [下一步：設定 Agent] │ └────────────────────────────────────────────────────────────────┘ ``` --- ## Step 2 內容（切換後） ``` ─────────────── Step 2 內容 ─────────────── ┌───────────────────────────────────────────────────────┐ │ Tabs（作業系統） │ │ [ macOS ] [ Windows ] [ Linux ] │ │ ▲ active │ ├───────────────────────────────────────────────────────┤ │ │ │ 1. 下載 local agent │ │ ┌──────────────────────────────────────────────┐ │ │ │ [📥 下載 visionA-local-agent-macos.dmg] │ │ │ └──────────────────────────────────────────────┘ │ │ │ │ 2. 安裝並啟動 │ │ 打開 DMG，拖曳到 Applications，雙擊啟動 │ │ │ │ 3. 輸入 Pairing Token │ │ 在 local agent 的「雲端」設定頁貼上 token │ │ │ │ 或使用命令列（CLI 進階使用者）： │ │ ┌──────────────────────────────────────────────┐ │ │ │ bg-muted font-mono text-sm │ │ │ │ visiona-agent --pair-token= │ │ │ │ vAc_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8 │ │ │ │ (複製為單行 36 字元 token) [📋 複製] │ │ │ └──────────────────────────────────────────────┘ │ │ │ │ 4. 連線成功後，回到這個頁面進入 Step 3 │ └───────────────────────────────────────────────────────┘ 💡 已經有 local agent？[跳到 Step 3 Link] [上一步] [下一步：確認連線] ``` --- ## Step 3 內容 — Waiting 狀態 ``` ─────────────── Step 3 內容 ─────────────── ┌───────────────────────────────────────────────────────┐ │ Card: 等待中 │ │ │ │ ⏳ │ │ (Loader2 animate-spin) │ │ │ │ 等待 local agent 連線... │ │ │ │ 已等待 0:23（最長 3 分鐘） │ │ (text-muted-foreground) │ │ │ │ [取消] [查看 Troubleshooting] │ │ │ │ ────────────────────────────────────────── │ │ │ │ 提示： │ │ • 確認 local agent 已啟動 │ │ • 確認 token 正確無誤 │ │ • 確認網路可以連到 cloud.visiona.ai │ └───────────────────────────────────────────────────────┘ [上一步] ``` --- ## Step 3 內容 — Success 狀態 ``` ┌───────────────────────────────────────────────────────┐ │ Card: 成功 │ │ │ │ ✓ (text-green-500 大圖示) │ │ (CheckCircle2, h-16 w-16) │ │ │ │ 已成功連線！ │ │ │ │ 檢測到的裝置： │ │ │ │ ┌────────────────────────────────────┐ │ │ │ 🔌 Kneron KL520 │ │ │ │ Firmware 2.3.1 │ │ │ │ Host: office-mac │ │ │ └────────────────────────────────────┘ │ │ │ │ [進入裝置列表 →] (w-full, variant=default) │ └───────────────────────────────────────────────────────┘ ``` --- ## Step 3 內容 — Timeout / Error 狀態 ``` ┌───────────────────────────────────────────────────────┐ │ Card: 錯誤 │ │ │ │ ⚠ (text-destructive) │ │ │ │ 連線超時 │ │ │ │ 超過 3 分鐘沒收到 local agent 連線 │ │ │ │ 可能原因： │ │ • local agent 尚未啟動 │ │ • token 輸入錯誤 │ │ • 防火牆擋住 WebSocket 連線 │ │ │ │ [重新檢查] [回到 Step 2] [查看完整說明] │ └───────────────────────────────────────────────────────┘ ``` --- ## Stepper 視覺細節 ``` 已完成： ┌──┐ │✓ │ bg-primary text-primary-foreground rounded-full h-8 w-8 └──┘ flex items-center justify-center 1 取得 Token text-sm font-medium (text-foreground) 當前： ┌──┐ │●2│ ring-2 ring-primary bg-background rounded-full h-8 w-8 └──┘ flex items-center justify-center 2 設定 Agent text-sm font-medium text-foreground 未完成： ┌──┐ │ 3│ bg-muted text-muted-foreground rounded-full h-8 w-8 └──┘ 3 確認連線 text-sm text-muted-foreground 連線線： ────── 已完成段：bg-primary h-0.5 ────── 未完成段：bg-muted h-0.5 ``` --- ## URL 狀態 為了讓使用者可以中途關閉後重返，URL 編碼狀態： - `/devices/pair` → 預設 Step 1 - `/devices/pair?step=2` → 跳到 Step 2 - `/devices/pair?step=3&token=xxx` → 跳到 Step 3（繼續等待已產的 token） 重新產生 token 時更新 URL。 --- ## 響應式 | 斷點 | 調整 | |------|------| | Mobile (< 640px) | Stepper 步驟文字隱藏或縮短；Card padding 調小 `p-4` | | Tablet / Desktop | 完整呈現 | --- ## 無障礙 - Stepper：`
    ` + `
  1. ` - Token 顯示區：`aria-label="Pairing token"` + `role="text"`（不要一個一個念字元） - 複製按鈕：按下後 `aria-live="polite"` 宣告「已複製」 - Step 3 polling 狀態變更：`aria-live="polite"` - 成功 / 失敗：`role="status"` + `aria-live="assertive"` - 所有按鈕可 Tab 聚焦 --- ## 對應的 i18n key 見 `flows/flow-pairing.md` 第 4-6 節的 i18n key 清單。