docs: 新增 Pipeline 四階段進度更新說明 (Core Team)

新增文件:
- docs/PIPELINE_PROGRESS_UPDATE_FOR_CORE.md

目的:
說明 Momentry Studio 前端對 Pipeline 進度顯示的實現和需求，供 Core Team 參考實現後端 API。

文件內容:

1. 四階段架構說明
   - 階段 1: 處理器 (30%) - ASR、ASRX、FACE、Face Tracing、OCR、CUT
   - 階段 2: 知識圖譜 (35%) - TKG Nodes、TKG Edges
   - 階段 3: 片段提取 (6%) - VLM Summary、Scene VLM、Moment Chunks
   - 階段 4: 資料整合 (29%) - Rule1、Rule2、Face Dedup

2. 關鍵更新說明
   - ASRX 處理器: 說話人向量化 (VOD)
   - Face Tracing: 從階段 4 移至階段 1
   - 向量入庫: 文字、說話人、人臉

3. 進度計算方式
   - 總體進度 = 加權平均
   - 計算範例

4. 需要的 API 端點
   - GET /api/v1/pipeline/phases (主要)
   - GET /api/v1/file/{uuid}/progress (快速輪詢)
   - GET /api/v1/file/{uuid}/scene-vlm-stats (已實現)

5. API 回應格式
   - 完整的 JSON 結構
   - 狀態值定義
   - 進度範例

6. 前端實現說明
   - 顯示位置
   - 顯示內容
   - 更新機制

7. 處理器完整列表
   - 名稱、功能、輸出

8. 建議實現順序
   - Phase 1-4 實現步驟

9. 驗收標準
   - API 驗收
   - 進度更新驗收
   - 前端顯示驗收

用途:
- Core Team 實現後端 API 的參考文件
- 前後端協作規範
- 測試驗收標準

docs/PIPELINE_PROGRESS_UPDATE_FOR_CORE.md

@@ -0,0 +1,473 @@
+# Pipeline 四階段進度更新說明 - Core Team 參考
+
+**文件**: Pipeline Progress Update for Core Team  
+**日期**: 2026-10-15  
+**版本**: v0.1.0  
+**作者**: Momentry Studio Team
+
+---
+
+## 📌 目的
+
+說明 Momentry Studio 前端對 Pipeline 進度顯示的實現和需求，供 Core Team 參考實現後端 API。
+
+---
+
+## 🎯 四階段架構
+
+### 階段總覽
+
+Momentry Studio 將 Pipeline 分為四個主要階段：
+
+| 階段 | 名稱 | 權重 | 功能 |
+|-----|------|------|------|
+| **1** | 處理器 (Processors) | 30% | 原始媒體分析 |
+| **2** | 知識圖譜 (Knowledge Graph) | 35% | 關係網路建構 |
+| **3** | 片段提取 (Moment Extraction) | 6% | AI 內容理解 |
+| **4** | 資料整合 (Integration) | 29% | 資料入庫儲存 |
+
+---
+
+### 階段 1: 處理器 (Processors)
+
+**權重**: 30%
+
+**包含的處理器**:
+- **ASR**: 語音識別 - 轉換語音為文字
+- **ASRX**: 說話人向量化 (VOD) - 建立說話人身分
+- **FACE**: 人臉檢測 - 檢測人臉位置和特徵
+- **Face Tracing**: 人臉追蹤 - 追蹤人臉在視訊中的軌跡
+- **OCR**: 文字識別 - 識別畫面文字
+- **CUT**: 鏡頭切換 - 識別場景切換點
+
+**說明**:
+- ASRX 使用 VOD 技術將說話人語音特徵向量化
+- Face Tracing 已從階段 4 移至階段 1，作為處理器執行
+- 所有處理器並行執行
+
+---
+
+### 階段 2: 知識圖譜 (Knowledge Graph)
+
+**權重**: 35%
+
+**包含的步驟**:
+- **TKG Nodes**: 人物/物品/對話節點建構
+- **TKG Edges**: 人物關係/共現關係建構
+
+---
+
+### 階段 3: 片段提取 (Moment Extraction)
+
+**權重**: 6%
+
+**包含的步驟**:
+- **VLM Summary**: 視訊總結
+- **Scene VLM**: 場景理解
+- **Moment Chunks**: 片段分割
+
+---
+
+### 階段 4: 資料整合 (Integration)
+
+**權重**: 29%
+
+**包含的步驟**:
+
+##### Rule1 Ingestion (PostgreSQL 入庫)
+- 句子區塊 (sentence_chunks)
+- 關係資料 (relationship_chunks)
+- 追蹤區塊 (trace_chunks)
+
+##### Rule2 Ingestion (向量入庫 - Qdrant)
+- **文字向量入庫**: 句子嵌入向量，支援語意搜尋
+- **說話人語音向量入庫**: 由 ASRX 處理器生成，VOD 實現
+- **人臉向量入庫**: 人臉嵌入向量，支援人臉識別
+
+##### Face Dedup (人臉去重)
+- 去除重複的人臉檢測結果
+- 合併同一人的多次檢測
+
+---
+
+## 🔍 關鍵更新說明
+
+### 1. ASRX 處理器 (說話人向量化)
+
+**名稱**: ASRX (非 VSRX)
+
+**功能**: 
+- 使用 VOD 技術
+- 將說話人語音特徵轉換為向量
+- 建立說話人身分
+
+**位置**: 階段 1 (處理器)
+
+**輸出**: 
+- 說話人嵌入向量
+- 用於後續的說話人向量入庫 (階段 4)
+
+---
+
+### 2. Face Tracing 處理器
+
+**位置變更**: 階段 4 → 階段 1
+
+**原因**:
+- Face Tracing 是基於人臉檢測結果的追蹤
+- 屬於原始媒體分析的一部分
+- 應該在處理器階段完成
+
+**功能**:
+- 追蹤人臉在視訊中的軌跡
+- 建立人臉出現序列
+- 關聯同一人的多次出現
+
+---
+
+### 3. 向量入庫說明
+
+**文字向量入庫**:
+- 句子嵌入向量
+- 支援語意搜尋和相似度匹配
+
+**說話人語音向量入庫 (VOD)**:
+- 由 ASRX 處理器生成
+- 說話人嵌入向量
+- 支援說話人識別和跨視訊追蹤
+
+**人臉向量入庫**:
+- 人臉嵌入向量
+- 支援人臉相似度搜尋和身分識別
+
+---
+
+## 📊 進度計算方式
+
+### 總體進度公式
+
+```
+總體進度 = (階段1進度 × 30%) + (階段2進度 × 35%) + (階段3進度 × 6%) + (階段4進度 × 29%)
+```
+
+### 計算範例
+
+**範例 1: 處理器階段完成**
+```
+Processors: 100% × 30% = 30%
+Knowledge Graph: 0% × 35% = 0%
+Moment Extraction: 0% × 6% = 0%
+Integration: 0% × 29% = 0%
+
+總體進度 = 30%
+```
+
+**範例 2: 知識圖譜階段完成**
+```
+Processors: 100% × 30% = 30%
+Knowledge Graph: 100% × 35% = 35%
+Moment Extraction: 0% × 6% = 0%
+Integration: 0% × 29% = 0%
+
+總體進度 = 65%
+```
+
+**範例 3: 全部完成**
+```
+Processors: 100% × 30% = 30%
+Knowledge Graph: 100% × 35% = 35%
+Moment Extraction: 100% × 6% = 6%
+Integration: 100% × 29% = 29%
+
+總體進度 = 100%
+```
+
+---
+
+## 🔌 需要的 API 端點
+
+### 1. Pipeline Phases API
+
+**端點**: `GET /api/v1/pipeline/phases`
+
+**用途**: 獲取檔案的 Pipeline 四階段進度
+
+**請求參數**:
+```json
+{
+  "file_uuid": "string"
+}
+```
+
+**回應格式**:
+```json
+{
+  "file_uuid": "abc-123",
+  "phases": [
+    {
+      "name": "processors",
+      "weight": 30,
+      "progress": 0.75,
+      "status": "processing",
+      "processors": [
+        {
+          "name": "asr",
+          "progress": 1.0,
+          "status": "completed"
+        },
+        {
+          "name": "asrx",
+          "progress": 0.8,
+          "status": "processing"
+        },
+        {
+          "name": "face",
+          "progress": 1.0,
+          "status": "completed"
+        },
+        {
+          "name": "face_tracing",
+          "progress": 0.5,
+          "status": "processing"
+        },
+        {
+          "name": "ocr",
+          "progress": 0.0,
+          "status": "pending"
+        },
+        {
+          "name": "cut",
+          "progress": 0.0,
+          "status": "pending"
+        }
+      ]
+    },
+    {
+      "name": "knowledge_graph",
+      "weight": 35,
+      "progress": 0.0,
+      "status": "pending",
+      "steps": [
+        {
+          "name": "tkg_nodes",
+          "progress": 0.0,
+          "status": "pending"
+        },
+        {
+          "name": "tkg_edges",
+          "progress": 0.0,
+          "status": "pending"
+        }
+      ]
+    },
+    {
+      "name": "moment_extraction",
+      "weight": 6,
+      "progress": 0.0,
+      "status": "pending",
+      "steps": [
+        {
+          "name": "vlm_summary",
+          "progress": 0.0,
+          "status": "pending"
+        },
+        {
+          "name": "scene_vlm",
+          "progress": 0.0,
+          "status": "pending"
+        },
+        {
+          "name": "moment_chunks",
+          "progress": 0.0,
+          "status": "pending"
+        }
+      ]
+    },
+    {
+      "name": "integration",
+      "weight": 29,
+      "progress": 0.0,
+      "status": "pending",
+      "steps": [
+        {
+          "name": "rule1_ingestion",
+          "progress": 0.0,
+          "status": "pending"
+        },
+        {
+          "name": "rule2_ingestion",
+          "progress": 0.0,
+          "status": "pending"
+        },
+        {
+          "name": "face_dedup",
+          "progress": 0.0,
+          "status": "pending"
+        }
+      ]
+    }
+  ],
+  "overall_progress": 0.225
+}
+```
+
+**狀態值**:
+- `pending`: 等待中
+- `processing`: 處理中
+- `completed`: 已完成
+- `failed`: 失敗
+
+---
+
+### 2. File Progress API (可選，用於快速輪詢)
+
+**端點**: `GET /api/v1/file/{uuid}/progress`
+
+**用途**: 快速獲取檔案的總體進度（不包含詳細階段資訊）
+
+**回應格式**:
+```json
+{
+  "file_uuid": "abc-123",
+  "overall_progress": 0.65,
+  "status": "processing",
+  "phases": {
+    "processors": 100,
+    "knowledge_graph": 100,
+    "moment_extraction": 50,
+    "integration": 0
+  }
+}
+```
+
+---
+
+### 3. Scene VLM Stats API (已實現)
+
+**端點**: `GET /api/v1/file/{uuid}/scene-vlm-stats`
+
+**用途**: 獲取 Scene VLM 處理統計
+
+**回應格式**:
+```json
+{
+  "file_uuid": "abc-123",
+  "total_scenes": 10,
+  "processed_scenes": 8,
+  "progress": 0.8,
+  "status": "processing"
+}
+```
+
+---
+
+## 🎨 前端實現說明
+
+### 顯示位置
+
+**Library 頁面** → 右鍵選單 → **Pipeline Progress**
+
+### 顯示內容
+
+1. **四階段進度條**
+   - 各階段進度百分比
+   - 狀態圖標 (✓ ○ ✗)
+   - 階段權重標示
+
+2. **處理器/步驟詳情**
+   - 階段 1: 6 個處理器進度
+   - 階段 2: TKG Nodes + TKG Edges
+   - 階段 3: VLM Summary + Scene VLM + Moment Chunks
+   - 階段 4: Rule1 + Rule2 + Face Dedup
+
+3. **總體進度**
+   - 四階段加權平均
+   - 整體處理狀態
+
+### 更新機制
+
+- **輪詢間隔**: 2 秒
+- **更新條件**: 檔案狀態為 `scanning`
+- **停止條件**: 檔案狀態為 `agent_ready` 或失敗
+
+---
+
+## 📋 處理器完整列表
+
+### 階段 1: 處理器 (Processors)
+
+| 處理器名稱 | 功能 | 輸出 |
+|-----------|------|------|
+| **ASR** | 語音識別 | 文字稿 |
+| **ASRX** | 說話人向量化 (VOD) | 說話人嵌入向量 |
+| **FACE** | 人臉檢測 | 人臉位置、特徵 |
+| **Face Tracing** | 人臉追蹤 | 人臉軌跡、出現序列 |
+| **OCR** | 文字識別 | 畫面文字內容 |
+| **CUT** | 鏡頭切換 | 場景切換點 |
+
+---
+
+## 🚀 建議實現順序
+
+### Phase 1: 基礎進度 API
+1. 實現 `GET /api/v1/pipeline/phases` 端點
+2. 在 Redis 中儲存進度資訊
+3. Worker 更新進度
+
+### Phase 2: 階段劃分
+1. 將處理器分為四個階段
+2. ASRX 作為處理器 (階段 1)
+3. Face Tracing 作為處理器 (階段 1)
+
+### Phase 3: 進度計算
+1. 實現加權進度計算
+2. 計算各階段進度
+3. 計算總體進度
+
+### Phase 4: 前端整合
+1. 前端調用 API
+2. 顯示四階段進度
+3. 即時更新
+
+---
+
+## 🔗 相關文件
+
+1. **前端實現**: `src/store.ts` - `loadPipelinePhases()`, `loadFileProgress()`
+2. **UI 顯示**: `src/views/LibraryView.vue` - Pipeline Progress 對話框
+3. **用戶說明**: `docs/PIPELINE_STAGES_EXPLANATION.md`
+4. **快速參考**: `docs/PIPELINE_STAGES_QUICK_REF.md`
+
+---
+
+## ✅ 驗收標準
+
+### API 驗收
+- [ ] `GET /api/v1/pipeline/phases` 返回正確的四階段資料
+- [ ] 各階段進度準確
+- [ ] 處理器列表包含 ASRX 和 Face Tracing
+- [ ] 總體進度計算正確
+
+### 進度更新驗收
+- [ ] Worker 在各階段完成時更新進度
+- [ ] 進度儲存在 Redis
+- [ ] 前端可正確獲取進度
+
+### 前端顯示驗收
+- [ ] Library 頁面顯示四階段進度
+- [ ] 各階段權重正確顯示
+- [ ] 總體進度計算正確
+- [ ] 狀態圖標正確顯示
+
+---
+
+## 📞 聯絡資訊
+
+如有問題或需要討論，請聯繫：
+
+**Momentry Studio Team**
+
+---
+
+**最後更新**: 2026-10-15  
+**版本**: v0.1.0