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）。
121 lines
4.8 KiB
Markdown
121 lines
4.8 KiB
Markdown
# 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)
|