jim800121chen fb7da5d180 chore(autoflow): migrate .autoflow/ 共享層文件至 docs/autoflow/

依 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）。

2026-05-04 16:55:55 +08:00

4.8 KiB

Raw Permalink Blame History

Feature：裝置管理（P0）

父文件：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 索引
相關：Pairing 流程、推論操作

4.8 KiB Raw Permalink Blame History Unescape Escape