Studio Team API 變更指南¶

Version: 1.0
Date: 2026-07-26
Doc Path: /Users/accusys/momentry_core/docs_v1.0/API_WORKSPACE/modules/21_studio_team_guide.md
目標: 通知 Studio team 後端 API 狀態欄位變更，Momentry Studio 前端需配合更新

1. 概述¶

後端已將檔案狀態從技術術語改為功能導向名稱。Studio team 的 ~/momentry_studio/ 前端顯示邏輯需要更新。

影響範圍： - 後端 API：/Users/accusys/momentry_core/src/api/files.rs（Core team 已修改） - Studio 前端：~/momentry_studio/（需 Studio team 更新）

2. 團隊職責¶

團隊	負責專案	目錄
Core team	Momentry Core 後端	`~/momentry_core/`
Studio team	Momentry Studio 前端	`~/momentry_studio/`
Marcom team	WordPress 網站	`/Users/accusys/wordpress/`

3. API 變更¶

`/api/v1/file/{file_uuid}/sync-status` 回傳格式¶

POST /api/v1/file/{file_uuid}/sync-status

{
  "success": true,
  "file_uuid": "4655a0ab3c077e30c12b2298c2750650",
  "status": "face_mgmt_ready",
  "processors_complete": 4,
  "processors_total": 5,
  "worker": {
    "has_job": true,
    "job_status": "pending",
    "current_processor": null,
    "progress_total": 7,
    "progress_current": 7,
    "completed_processors": ["cut", "asr", "face", "ocr", "pose", "asrx", "face_cluster"],
    "failed_processors": [],
    "updated_at": "2026-07-24T21:26:06"
  }
}

無 job 的檔案：

{
  "success": true,
  "file_uuid": "...",
  "status": "registered",
  "processors_complete": 0,
  "processors_total": 5,
  "worker": {
    "has_job": false
  }
}

Worker 狀態說明¶

欄位	說明
`has_job`	是否有 monitor_job 紀錄
`job_status`	pending / running / completed / failed
`current_processor`	目前正在執行的 processor
`progress_total`	總 processor 數量
`progress_current`	已完成的 processor 數量
`completed_processors`	已完成的 processor 列表
`failed_processors`	失敗的 processor 列表
`updated_at`	最後更新時間

使用者可區分的情境¶

情境	`job_status`	`current_processor`	顯示建議
正在處理	`running`	`face`	🔄 正在執行 Face
排隊等待	`pending`	`null`	⏳ 等待處理
已完成	`completed`	`null`	✅ Processor 完成
處理失敗	`failed`	`face`	❌ Face 失敗
從未提交	`has_job=false`	-	📋 僅註冊

新狀態清單¶

Status	中文顯示	圖示	說明
`registered`	已註冊	📋	0 processor outputs
`scanning`	掃描中	🔍	1-4/5 processor outputs
`keyword_ready`	關鍵字可用	🔎	sentence chunks > 0
`semantic_ready`	語意可用	🧠	embedded chunks > 0
`face_mgmt_ready`	臉部管理可用	🎭	trace_profiles + tkg_nodes > 0
`agent_ready`	Agent 可用	🤖	tkg_edges > 0
`completed`	已完成	✅	全部就緒

已移除的舊狀態¶

舊狀態	新狀態
`pending`	`registered`
`processing`	`scanning`

4. Studio 前端需修改項目¶

4.1 狀態顯示邏輯¶

位置： ~/momentry_studio/ 中處理檔案狀態顯示的元件

修改前：

switch (file.status) {
  case 'completed': return '✅ 已完成';
  case 'processing': return '🔄 處理中';
  case 'pending': return '⏳ 待處理';
  default: return '📦 未註冊';
}

修改後：

const statusMap = {
  completed:       { label: '已完成', icon: '✅', color: 'green' },
  agent_ready:     { label: 'Agent 可用', icon: '🤖', color: 'orange' },
  face_mgmt_ready: { label: '臉部管理可用', icon: '🎭', color: 'cyan' },
  semantic_ready:  { label: '語意可用', icon: '🧠', color: 'purple' },
  keyword_ready:   { label: '關鍵字可用', icon: '🔎', color: 'green' },
  scanning:        { label: '掃描中', icon: '🔍', color: 'blue' },
  registered:      { label: '已註冊', icon: '📋', color: 'gray' },
};

const display = statusMap[file.status] || { label: '未註冊', icon: '📦', color: 'gray' };
return `${display.icon} ${display.label}`;

4.2 狀態過濾選項¶

位置： ~/momentry_studio/ 中檔案列表過濾元件

移除： pending, processing
新增： registered, scanning, keyword_ready, semantic_ready, face_mgmt_ready, agent_ready

5. Face Management Ready 明確定義¶

face_mgmt_ready 表示檔案已具備完整臉部管理功能，需同時滿足以下四個條件：

依賴項	檢查條件	說明
Face Qdrant Ready	`_faces` collection 有 face points	Face embeddings 已存入 Qdrant
Face Trace Ready	`face_traced.json` 存在且有 traces	Face tracking 已完成
Face Profile Ready	`trace_profiles` 有紀錄	Profile 資料已建立
Face TKG Node Ready	`tkg_nodes` 有 `face_track` nodes	TKG 圖譜節點已建立

6. 狀態依賴關係¶

registered → scanning → keyword_ready → semantic_ready
                                         ↓
                              face_mgmt_ready → agent_ready → completed

7. 測試 API¶

# 取得所有檔案
curl http://localhost:3002/api/v1/files \
  -H "Authorization: Bearer <api_key>"

# 觸發狀態同步
curl -X POST http://localhost:3002/api/v1/file/{file_uuid}/sync-status \
  -H "Authorization: Bearer <api_key>"

8. 參考文件¶

文件	完整路徑
People API	`/Users/accusys/momentry_core/docs_v1.0/API_WORKSPACE/modules/19_people_api.md`
Status Unification	`/Users/accusys/momentry_core/docs_v1.0/API_WORKSPACE/modules/20_status_unification.md`
Studio Team Guide	`/Users/accusys/momentry_core/docs_v1.0/API_WORKSPACE/modules/21_studio_team_guide.md`
AGENTS.md	`/Users/accusys/momentry_core/AGENTS.md`