docs: add Core Team action items document

Document 5 key issues that Core team needs to diagnose:

1. get_pipeline_stats API data accuracy (HIGH)
2. sync_file_status API state updates (HIGH)
3. Pipeline progress calculation logic (MEDIUM)
4. Pipeline stages initialization (MEDIUM)
5. File processing error handling (MEDIUM)

Includes:
- Test commands for API diagnosis
- Expected response formats
- Verification checklist
- Diagnostic steps

Related: Studio team fixes in previous commit

CORE_TEAM_ACTION_ITEMS.md

@@ -0,0 +1,293 @@
+# Core Team Action Items - Pipeline Progress Issue
+
+## 🚨 问题摘要
+
+**现象**：Library 卡片在 deep scan 时卡在 "Scanning..." 状态，没有进度百分比
+
+**前端已修复**：
+- ✅ `syncFileStatus()` 现在会加载进度数据
+- ✅ LibraryView 会启动轮询即使 pipeline 数据缺失
+- ✅ Commit: `待推送`
+
+**后端需要诊断**：5 项核心问题
+
+---
+
+## 📋 Core Team 需要检查的项目
+
+### 1. 🔴 `get_pipeline_stats` API 数据准确性（高优先级）
+
+**API**: `GET /api/v1/pipeline-stats?file_uuid={uuid}`
+
+**需要检查**：
+- API 是否正常返回数据？
+- 返回的 `stages` 数组是否包含正在运行的阶段？
+- `overall_progress` 计算是否正确？
+- 阶段状态（pending/running/completed/failed）是否正确更新？
+
+**测试命令**：
+```bash
+# 找一个 processing 状态的文件 UUID
+curl -X GET "http://localhost:3002/api/v1/pipeline-stats?file_uuid={FILE_UUID}" \
+  -H "Authorization: Bearer {API_KEY}"
+```
+
+**期望返回格式**：
+```json
+{
+  "overall_progress": 0.45,
+  "stages": [
+    {
+      "name": "processors",
+      "weight": 0.30,
+      "progress": 0.8,
+      "status": "running"
+    },
+    {
+      "name": "rule1_ingestion",
+      "weight": 0.10,
+      "progress": 0.0,
+      "status": "pending"
+    }
+  ]
+}
+```
+
+**需要验证**：
+- ✅ `overall_progress` 是否在 0-1 之间？
+- ✅ `stages` 数组是否非空？
+- ✅ 至少有一个 stage 的 `status === 'running'`？
+- ✅ 所有 stage 的 `progress` 总和是否合理？
+
+---
+
+### 2. 🔴 `sync_file_status` API 状态更新（高优先级）
+
+**API**: `POST /api/v1/sync-file-status`
+
+**需要检查**：
+- 文件处理完成后，状态是否从 `processing` 变为 `completed`？
+- 处理失败时，状态是否变为 `failed`？
+- API 响应时间是否合理（< 1s）？
+
+**测试命令**：
+```bash
+# 同步文件状态
+curl -X POST "http://localhost:3002/api/v1/sync-file-status" \
+  -H "Authorization: Bearer {API_KEY}" \
+  -H "Content-Type: application/json" \
+  -d '{"file_uuid": "{FILE_UUID}"}'
+```
+
+**期望返回格式**：
+```json
+{
+  "status": "processing"
+}
+```
+或
+```json
+{
+  "status": "completed"
+}
+```
+
+**需要验证**：
+- ✅ 状态是否正确更新？
+- ✅ 处理完成后是否立即变为 `completed`？
+- ✅ 错误情况是否返回 `failed`？
+
+---
+
+### 3. 🟡 Pipeline 进度计算逻辑（中优先级）
+
+**位置**: Core API pipeline 执行引擎
+
+**需要检查**：
+- 各处理阶段的进度追踪是否准确？
+- `overall_progress` 权重计算是否正确？
+- 阶段状态转换是否及时？
+
+**权重设置**（前端期望）：
+```typescript
+const WEIGHT_MAP = {
+  processors: 0.30,
+  rule1_ingestion: 0.10,
+  face_tracing: 0.10,
+  tkg_nodes: 0.20,
+  tkg_edges: 0.15,
+  rule2_ingestion: 0.15
+}
+```
+
+**需要验证**：
+- ✅ 后端权重是否与前端一致？
+- ✅ 各阶段进度是否正确追踪？
+- ✅ 阶段完成时是否立即更新状态？
+
+---
+
+### 4. 🟡 Pipeline stages 初始化（中优先级）
+
+**需要检查**：
+- 文件开始处理时，是否立即创建 stages 数据？
+- 所有必要的阶段是否都被追踪？
+- 阶段顺序是否正确？
+
+**可能的问题**：
+- 文件开始处理时，`stages` 数组为空
+- 导致前端无法判断是否有正在运行的阶段
+- `pollPipelineProgress()` 不会被启动
+
+**需要验证**：
+- ✅ 文件注册后，立即创建初始 stages？
+- ✅ 所有阶段都被包含在返回数据中？
+- ✅ 阶段顺序是否符合 pipeline 流程？
+
+---
+
+### 5. 🟡 文件处理异常处理（中优先级）
+
+**需要检查**：
+- 处理过程出错时，文件状态是否正确更新？
+- 是否有文件卡在 `processing` 状态无法完成？
+- 错误日志是否完整？
+
+**可能的问题**：
+- 文件处理出错，但状态未更新为 `failed`
+- 文件永远卡在 `processing` 状态
+- 前端无法判断文件是否完成
+
+**需要验证**：
+- ✅ 错误处理机制是否完善？
+- ✅ 失败文件是否有明确的 `failed` 状态？
+- ✅ 错误日志是否包含足够信息？
+
+---
+
+## 🧪 诊断步骤
+
+### Step 1: 检查 processing 文件的 pipeline stats
+
+```bash
+# 1. 获取 processing 文件列表
+curl -X GET "http://localhost:3002/api/v1/files?status=processing&per_page=10" \
+  -H "Authorization: Bearer {API_KEY}"
+
+# 2. 对每个 processing 文件，检查 pipeline stats
+for uuid in $(processing_files); do
+  echo "=== File: $uuid ==="
+  curl -X GET "http://localhost:3002/api/v1/pipeline-stats?file_uuid=$uuid" \
+    -H "Authorization: Bearer {API_KEY}"
+  echo ""
+done
+```
+
+**观察重点**：
+- `overall_progress` 是否为 0 或 null？
+- `stages` 数组是否为空？
+- 是否有 stage 的 `status === 'running'`？
+
+---
+
+### Step 2: 检查文件状态同步
+
+```bash
+# 对卡住的文件，手动调用 sync_file_status
+curl -X POST "http://localhost:3002/api/v1/sync-file-status" \
+  -H "Authorization: Bearer {API_KEY}" \
+  -H "Content-Type: application/json" \
+  -d '{"file_uuid": "{STUCK_FILE_UUID}"}'
+```
+
+**观察重点**：
+- API 是否返回正确的状态？
+- 状态是否从 `processing` 变为 `completed`？
+
+---
+
+### Step 3: 检查后端日志
+
+```bash
+# 查看最近的错误日志
+tail -f /path/to/core-api/logs/error.log | grep -E "pipeline|processing|file_uuid"
+```
+
+**观察重点**：
+- 是否有 pipeline 执行错误？
+- 是否有文件处理超时？
+- 是否有数据库连接错误？
+
+---
+
+## 📊 前端已修复的内容
+
+### 修复 1: `syncFileStatus()` 添加进度加载
+
+**文件**: `src/store.ts`
+
+**改动**：
+```typescript
+// 在 syncFileStatus() 中，当状态为 processing 时，加载进度数据
+if (newStatus === 'processing') {
+  await loadPipelineStats(fileUuid, true)
+}
+```
+
+**效果**：每 10 秒轮询时，会更新进度数据
+
+---
+
+### 修复 2: LibraryView 启动轮询（处理边缘情况）
+
+**文件**: `src/views/LibraryView.vue`
+
+**改动**：
+```typescript
+// 即使没有 pipeline 数据，如果状态是 processing，也启动轮询
+else if (!pipeline && f.status === 'processing') {
+  pollPipelineProgress(f.file_uuid)
+}
+```
+
+**效果**：不会因为 pipeline 数据缺失而无法启动轮询
+
+---
+
+## ✅ 修复验证清单
+
+修复后，前端期望看到：
+
+1. **进度条显示百分比**
+   - 不再只显示 "Scanning..."
+   - 显示具体进度（如 "45%"）
+
+2. **进度数据定期更新**
+   - 每 10 秒更新一次
+   - 进度条实时变化
+
+3. **文件状态正确转换**
+   - `processing` → `completed`
+   - 处理失败的文件显示 `failed`
+
+4. **无卡住现象**
+   - 文件不会永远卡在 `processing`
+   - 有明确的完成时间
+
+---
+
+## 📞 联系方式
+
+如有疑问，请联系 Studio team：
+
+- **前端修复 Commit**: `{COMMIT_HASH}`
+- **修复文件**:
+  - `src/store.ts:888-891`
+  - `src/views/LibraryView.vue:789-790`
+- **测试环境**: `http://localhost:5173`
+- **API 文档**: `AGENTS.md`
+
+---
+
+**生成时间**: 2026-07-25
+**优先级**: 🔴 高 - 影响用户体验

dist/index.html

@@ -1,13 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>Momentry Studio</title>
-  <script type="module" crossorigin src="/assets/index-XYmskk93.js"></script>
-  <link rel="stylesheet" crossorigin href="/assets/index-D8U_cUr3.css">
-</head>
-<body>
-  <div id="app"></div>
-</body>
-</html>

src/store.ts

@@ -886,6 +886,10 @@ export async function syncFileStatus(fileUuid: string): Promise<any> {
           delete fileProgressCache.value[fileUuid]
         }
         f.status = newStatus
+        
+        if (newStatus === 'processing') {
+          await loadPipelineStats(fileUuid, true)
+        }
       }
     }
     

src/views/LibraryView.vue

@@ -108,7 +108,7 @@
             </div>
             <div v-else-if="f.status === 'processing'" class="ms-fm-progress">
               <div class="ms-fm-progress-bar" style="width: 100%"></div>
-              <div class="ms-fm-progress-text">Processing...</div>
+              <div class="ms-fm-progress-text">Scanning...</div>
             </div>
             <div class="ms-fm-meta">
               <div class="ms-fm-name">{{ f.file_name }}</div>
@@ -191,7 +191,7 @@
             <button class="ms-proc-redo" @click.stop="redoProcessor('asrx')" title="Re-run ASRX">🔄</button>
           </div>
           <div class="ms-proc-line" :class="procStatusClass('face_cluster')">
-            <label class="ms-fm-check-label"><input type="checkbox" v-model="procFaceCluster"> Face Cluster</label>
+            <label class="ms-fm-check-label"><input type="checkbox" v-model="procFaceCluster"> Face Deduplication</label>
             <span class="ms-proc-status">{{ procStatusIcon('face_cluster') }}</span>
             <span class="ms-proc-count" @click.stop="viewProcessorJson('face_cluster')">{{ procCountLabel('face_cluster', 'frame') }}</span>
             <button class="ms-proc-redo" @click.stop="redoProcessor('face_cluster')" title="Re-run Face Cluster">🔄</button>
@@ -786,7 +786,7 @@ async function loadFiles() {
       } else if (pipeline && pipeline.overall_progress >= 1.0) {
         f.status = 'completed'
       } else if (!pipeline && f.status === 'processing') {
-        f.status = 'registered'
+        pollPipelineProgress(f.file_uuid)
       }
       
       await loadFileStats(f.file_uuid, true)