# Face Clustering Agent Endpoint Request

## 需求
新增一個 on-demand face clustering endpoint，讓前端可以手動觸發 face trace 分組。

## 背景
Momentry Studio 的 People 頁面有「Face Deduplication」按鈕，目的是讓使用者可以對已處理 face 的影片執行 face 分組（clustering）。目前這個功能無法使用，因為對應的 API endpoint 不存在。

## 需要的 Endpoint

### `POST /api/v1/file/:file_uuid/cluster-agent`

**用途**：對指定檔案觸發 face clustering，將相似的 face traces 分組。

#### Request
```
POST /api/v1/file/{file_uuid}/cluster-agent
Content-Type: application/json
X-API-Key: {key}

{}
```

| 參數 | 類型 | 必填 | 說明 |
|------|------|------|------|
| `file_uuid` | string | ✅ (URL path) | 檔案 UUID |

#### Response (200)
```json
{
  "success": true,
  "file_uuid": "477b24d3...",
  "message": "Clustering started for file",
  "clusters": 0,
  "total_traces": 2
}
```

| 欄位 | 類型 | 說明 |
|------|------|------|
| `success` | boolean | 是否成功觸發 |
| `file_uuid` | string | 檔案 UUID |
| `message` | string | 狀態訊息 |
| `clusters` | integer | 已分組數量（剛觸發時為 0） |
| `total_traces` | integer | 該檔案總 face trace 數 |

#### 實作邏輯（建議）
1. 檢查檔案是否存在且 face 已處理完成
2. 讀取 face detections / face embeddings
3. 執行 face clustering（可參考 pipeline 中的 clustering 邏輯）
4. 將分組結果寫入 TKG（更新 `face_trace` node 的 `label`）
5. 回傳觸發結果（clustering 可非同步執行）

### 前端消費流程
```
1. POST /api/v1/file/{uuid}/cluster-agent   → 觸發 clustering
2. GET  /api/v1/file/{uuid}/face-groups      → 輪詢直到 face_groups 有資料
3. 顯示 face groups 在 People 頁面
```

## 相關檔案
- **前端按鈕**: `src/views/PeopleView.vue` line 14-18 (`runClusterAgent()`)
- **API 映射**: `src/api/index.ts` line 369-371 (`run_cluster_agent`)
- **現有 face-groups**: `GET /api/v1/file/:file_uuid/face-groups` (已存在，用於讀取結果)
- **Pipeline 處理**: `docs_v1.0/doc_wasm/modules/05_process.md` (face 處理流程)

## 優先級
中優先級 — 目前有 2 個 unassigned traces 但無法分組，使用者無法有效的進行 face deduplication。