Skip to content

Studio Team 配套修改指南

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

1. 概述

後端已完成以下修改： 1. 移除 identity_agent，替換為 face_dedup（Face Deduplication） 2. 重構 sync_file_status 邏輯：檢查 JSON 存在 + DB 一致性 3. Pipeline 進度階段重新分配

影響範圍： - 檔案狀態顯示（status） - Pipeline 進度顯示（progress stages） - 統計 API 回傳格式

2. 檔案狀態變更

新狀態清單

Status 中文顯示 圖示 說明
registered 已註冊 📋 尚未開始處理
scanning 掃描中 🔍 處理中（JSON 存在但 DB 不一致）
completed 已完成 ✅ 所有 processor 完成且 DB 一致
agent_ready Agent 可用 🤖 TKG edges 存在

已移除的狀態

舊狀態 新狀態 說明
processing scanning 更明確表示正在處理
pending registered 尚未開始
face_mgmt_ready completed 最終狀態統一為 completed

狀態判斷邏輯

條件 狀態
所有 JSON 存在且 DB 一致 completed
部分 JSON 存在但不一致 scanning
無 JSON 存在 registered
TKG edges 存在 agent_ready

3. Pipeline 進度階段變更

修改前（7 個 stage）

Processors (30%) → Rule1 (5%) → Face Tracing (5%) → identity_agent (10%) → TKG Nodes (20%) → TKG Edges (15%) → Rule2 (15%)

修改後（7 個 stage）

Processors (30%) → Rule1 (5%) → Face Tracing (5%) → face_dedup (10%) → TKG Nodes (20%) → TKG Edges (15%) → Rule2 (15%)

需要修改的前端元件

元件 修改內容
Pipeline Progress Bar 移除 identity_agent，新增 face_dedup
Stage Labels 更新 stage 名稱
Overall Progress 重新計算權重

4. API 變更

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

回傳格式變更：

修改前： 

{
  "status": "face_mgmt_ready",
  "processors_complete": 5,
  "processors_total": 5,
  "worker": { ... }
}

修改後： 

{
  "success": true,
  "file_uuid": "...",
  "status": "completed",
  "processors": {
    "asr": { "json_exists": true, "consistent": true },
    "asrx": { "json_exists": true, "consistent": true },
    "ocr": { "json_exists": true, "consistent": true },
    "pose": { "json_exists": true, "consistent": true },
    "cut": { "json_exists": true, "consistent": true },
    "face": { "json_exists": true, "consistent": true },
    "face_cluster": { "json_exists": true, "consistent": true }
  },
  "worker": { ... }
}

/api/v1/file/{file_uuid}/stats

回傳格式變更：

修改前： 

{
  "identity_agent": {
    "clusters": 0,
    "identities_created": 0,
    "tmdb_matches": 0,
    "speaker_bindings": 0,
    "confirmations": 0
  }
}

修改後： 

{
  "face_dedup": {
    "clusters": 5,
    "face_tracks": 24,
    "consistent": true
  }
}

5. Studio 前端需修改項目

5.1 狀態顯示邏輯

位置： Studio 前端檔案列表元件

修改前： 

const statusLabels = {
  'completed': '✅ 已完成',
  'processing': '🔄 處理中',
  'pending': '⏳ 待處理',
  'face_mgmt_ready': '🎭 臉部管理可用',
  'agent_ready': '🤖 Agent 可用'
};

修改後： 

const statusLabels = {
  'completed': '✅ 已完成',
  'scanning': '🔍 掃描中',
  'registered': '📋 已註冊',
  'agent_ready': '🤖 Agent 可用'
};

5.2 Pipeline 進度顯示

位置： Studio 前端 Pipeline Progress 元件

修改項目： 1. 移除 identity_agent stage 2. 新增 face_dedup stage 3. 更新 stage 名稱映射

5.3 統計面板

位置： Studio 前端檔案統計面板

修改項目： 1. 移除 Identity Agent 區塊 2. 新增 Face Deduplication 區塊 3. 顯示欄位：clusters, face_tracks, consistent

6. 測試清單

  • 檔案列表狀態顯示正確
  • Pipeline 進度階段正確顯示
  • Overall Progress 計算正確
  • 統計面板 Face Dedup 區塊顯示正確
  • sync-status API 回傳格式解析正確
  • stats API 回傳格式解析正確

7. 參考文件

文件 完整路徑
Studio Team Guide /Users/accusys/momentry_core/docs_v1.0/API_WORKSPACE/modules/21_studio_team_guide.md
People API /Users/accusys/momentry_core/docs_v1.0/API_WORKSPACE/modules/19_people_api.md
Pipeline Changes /Users/accusys/momentry_core/docs_v1.0/API_WORKSPACE/modules/22_studio_pipeline_changes.md