# Feature：裝置管理（P0）

> 父文件：[PRD.md](../PRD.md) | 對應 User Stories：US-03、US-06、US-07

---

## 概述

使用者能在雲端瀏覽自己所有已配對的 Kneron 裝置、查看狀態、連接 / 斷開、查看韌體資訊。

對比 local-tool：UI 幾乎一樣，差別在「裝置來源」— local-tool 掃本機 USB，visionA Cloud 列表來自 pairing 的 local agent（透過 tunnel 掃 agent 端的 USB）。

---

## 使用者行為

### 裝置列表頁（`/devices`）

顯示當前使用者名下所有已配對的裝置：

| 欄位 | 內容 | 來源 |
|------|------|------|
| 裝置名稱 | 使用者自訂或預設（例如「KL520-001」）| Phase 0：預設；Phase 1：可編輯 |
| 型號 | KL520 / KL720 | 從 local agent 回報 |
| 連線狀態 | 🟢 在線 / 🟡 Tunnel 重連中 / ⚪ 離線 | Remote-proxy session 狀態 |
| Tunnel 延遲 | RTT ms | 定期 ping |
| 韌體版本 | 例如 `KL520_FW_v1.2.3` | 從 local agent 回報 |
| 所屬 agent | 哪台筆電 / 機台 | Pairing 時填（Phase 1）|
| 最後活動 | 時間戳記 | 推論紀錄 |
| 操作 | 連接 / 斷開 / 詳細 / 撤銷配對（Phase 1）| — |

### 裝置詳細頁（`/devices/[id]`）

沿用 local-tool 的版型，新增：

- **Tunnel 資訊區塊**：當前 session ID、連線時長、延遲圖、斷線重連次數
- **Agent 資訊**：這台裝置來自哪個 local agent、agent 版本
- **撤銷配對按鈕**（Phase 1）

### 操作

- **連接 / 斷開**：和 local-tool 一樣（透過 tunnel 轉發 `/api/devices/{id}/connect`）
- **掃描新裝置**：觸發 agent 端的 USB 掃描（tunnel 轉發 `/api/devices/scan`）
- **撤銷配對**（Phase 1）：撤銷該裝置的 Session Token，強制斷線

---

## 技術細節（給 Architect 參考）

### 裝置狀態來源

```
┌─────────────────────────────────────────────────────────┐
│  Phase 0 資料流（in-memory）                            │
│                                                         │
│  Browser ──GET /api/devices──> api-server               │
│                                     │                   │
│                                     │ 查 session 狀態   │
│                                     ▼                   │
│                              SessionStore (in-mem)      │
│                                     │                   │
│                                     │ 對每個在線 session │
│                                     ▼                   │
│                         remote-proxy (tunnel)           │
│                                     │                   │
│                                     │ yamux stream      │
│                                     ▼                   │
│                            local agent (:3721)          │
│                                     │                   │
│                                     │ 本機 KneronPLUS    │
│                                     ▼                   │
│                             Kneron KL520/KL720          │
└─────────────────────────────────────────────────────────┘
```

### 快取策略

Phase 0：不快取，每次 GET 都即時查 local agent。

Phase 1：考慮前端 SWR 快取 + 後端 5 秒 memory cache，減少 tunnel 流量。

### 即時事件

沿用 local-tool 的 `/ws/devices/events` WebSocket，但改由 visionA-backend 的 api-server 廣播：

- Agent 上線 / 下線
- 裝置連接 / 斷開
- 裝置健康度變化

api-server 透過 remote-proxy 的 events 通道接收 agent 事件，再廣播給對應的前端 WebSocket client。

---

## 驗收條件（Phase 0）

- [ ] 登入後 `/devices` 頁面顯示當前使用者的裝置列表
- [ ] 未配對時顯示空狀態 + 「配對新裝置」CTA
- [ ] 裝置在線 / 離線狀態正確（agent 下線 5 秒內反映）
- [ ] 能打開裝置詳細頁，顯示韌體版本等資訊
- [ ] 連接 / 斷開操作能成功執行
- [ ] 掃描 USB 裝置能觸發 agent 端動作
- [ ] Tunnel 延遲顯示正確（單位 ms）
- [ ] 兩個不同使用者的裝置列表互相隔離（multi-tenant 基本）
- [ ] UI 與 local-tool 一致性達到 90%+

---

## Phase 0 的 TODO

- **TODO**：裝置名稱自訂編輯（Phase 1）
- **TODO**：裝置分組 / 標籤（Phase 2）
- **TODO**：裝置健康度告警規則（Phase 2）
- **TODO**：撤銷配對按鈕（Phase 0 顯示 disabled，Phase 1 實作）

---

## 連結

- 回：[PRD 索引](../PRD.md)
- 相關：[Pairing 流程](feature-pairing.md)、[推論操作](feature-inference.md)