momentry_studio/docs/CLUSTER_AGENT_IMPLEMENTED.md

Cluster Agent Endpoint — 實作完成

新增 Endpoint

POST /api/v1/file/:file_uuid/cluster-agent — 對指定影片觸發 on-demand face clustering。

實作邏輯

1. 查 DB 拿 file_path、fps，從 probe_json 拿 nb_frames
2. 執行 Python fast_face_clustering_processor.py（不接受 --frames）
3. 將分組結果寫入 tkg_nodes（label = cluster_id）
4. 回傳 Response

前端消費流程（不變）

POST /api/v1/file/{uuid}/cluster-agent → 觸發 clustering
GET  /api/v1/file/{uuid}/face-groups   → 輪詢結果

Response (200)

{
  "success": true,
  "file_uuid": "477b24d3...",
  "message": "Clustering completed",
  "clusters": 25,
  "total_traces": 37
}

狀態

• ✅ Code 完成、已部署
• ✅ 測試通過：477b24d3... → 25 clusters, 37 traces

其他修復（同次部署）

• OCR chunks 現在正確標為 source_type: ocr
• Rule 1 重跑會先刪舊 chunks
• store_traced_faces.py 失敗時寫入 fallback 避免 worker 卡住

相關檔案

• src/api/cluster_agent.rs — 新 endpoint handler
• src/api/server.rs — route 註冊
• src/core/chunk/rule1_ingest.rs — 先刪舊 chunks
• src/core/db/postgres_db.rs — chunk_type 用 as_str()
• src/worker/job_worker.rs — fallback face_traced.json