# Feature：叢集推論（P1）

> 父文件：[PRD.md](../PRD.md) | 對應 User Stories：US-16、US-17
>
> **Phase 0 不實作**。Phase 0 只留模組目錄（`internal/cluster/`），從 POC 搬過來但不接入 API。Phase 1 正式產品化。

---

## 概述

叢集推論是 edge-ai-platform POC 驗證過的功能：把多台 Kneron 裝置組成叢集，按**加權 Round-Robin** 分派推論任務。

這是 visionA Cloud 相對於 local-tool 的**核心差異化功能**。

---

## 使用者行為（Phase 1）

### 叢集列表頁（`/clusters`）

- 使用者能看到自己建立的叢集
- 每個叢集顯示：名稱、裝置數、活躍狀態、最近推論量
- 能建立新叢集、刪除叢集、編輯叢集

### 建立叢集流程

1. 點「新建叢集」
2. 輸入叢集名稱
3. 從已配對裝置挑選 2+ 台裝置加入
4. 為每台裝置設權重（1-10）
5. 確認建立

### 叢集推論操作

- 進入某叢集的 workspace：`/clusters/[id]/workspace`
- 選模型（必須叢集內所有裝置都相容）
- 選來源（Camera / Image / Video / Batch）
- 啟動後，dispatcher 按加權 RR 分派任務到各裝置
- UI 顯示：
  - 每台裝置的即時負載（%）
  - 每台裝置的推論 FPS
  - 整體吞吐量
  - Bounding box overlay 仍然顯示（但標注是哪台裝置推論的）

### 故障降級

- 某台裝置 tunnel 斷線 → 自動從 dispatcher 移除
- 叢集內剩餘裝置繼續服務
- 裝置重新上線 → 自動回加入叢集

---

## 技術細節（從 POC 搬）

從 POC `cluster/` 模組搬：

- `Dispatcher`：加權 RR 邏輯
- `Manager`：叢集 CRUD
- `Pipeline`：單幀 `RunInference` 或連續 `StartContinuous`

**要做的產品化改造**：

- 加 user_id 隔離（POC 只有一個用戶）
- 叢集 metadata 存 DB（Phase 1 接 DB 後）
- MaxClusterSize 可配置
- 健康度監控與告警

---

## 驗收條件（Phase 1，不在 Phase 0 範圍）

- [ ] 能建立、編輯、刪除叢集
- [ ] 叢集內至少能加 5 台裝置（上限可配置）
- [ ] 加權 RR 分派正確（實測權重 3:1 的裝置，流量比約 3:1）
- [ ] 某裝置離線時，叢集自動降級，剩餘裝置繼續服務
- [ ] 裝置重新上線自動加回
- [ ] 每台裝置的即時負載 UI 更新
- [ ] 不同使用者的叢集互相隔離

---

## Phase 0 要做的準備

- [ ] `internal/cluster/` 模組從 POC 搬到 visionA-backend，但**不接入 API handlers**
- [ ] Phase 0 的前端 `/clusters` 頁面：可留空白或顯示「即將推出」
- [ ] 介面層面預留：API Server router 保留 `/api/clusters/...` 路徑的預定義，先回 501 Not Implemented

---

## Phase 2 的 TODO

- **TODO 1**：跨使用者的叢集共享（多租戶團隊功能）
- **TODO 2**：動態權重調整（根據實測效能自動調）
- **TODO 3**：叢集級別的 Model A/B Testing
- **TODO 4**：叢集級別的 fallback policy（不只 RR，還能 failover）

---

## 連結

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