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）。
247 lines
14 KiB
Markdown
247 lines
14 KiB
Markdown
# 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：`<ol role="list">` + `<li role="listitem" aria-current="step">`
|
||
- 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 清單。
|