momentry_studio/CORE_TEAM_ACTION_ITEMS.md

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）是否正确更新？

测试命令：

# 找一个 processing 状态的文件 UUID
curl -X GET "http://localhost:3002/api/v1/pipeline-stats?file_uuid={FILE_UUID}" \
  -H "Authorization: Bearer {API_KEY}"

期望返回格式：

{
  "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）？

测试命令：

# 同步文件状态
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}"}'

期望返回格式：

{
  "status": "processing"
}

或

{
  "status": "completed"
}

需要验证：

• ✅ 状态是否正确更新？
• ✅ 处理完成后是否立即变为 completed？
• ✅ 错误情况是否返回 failed？

---

3. 🟡 Pipeline 进度计算逻辑（中优先级）

位置: Core API pipeline 执行引擎

需要检查：

• 各处理阶段的进度追踪是否准确？
• overall_progress 权重计算是否正确？
• 阶段状态转换是否及时？

权重设置（前端期望）：

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

# 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: 检查文件状态同步

# 对卡住的文件，手动调用 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: 检查后端日志

# 查看最近的错误日志
tail -f /path/to/core-api/logs/error.log | grep -E "pipeline|processing|file_uuid"

观察重点：

• 是否有 pipeline 执行错误？
• 是否有文件处理超时？
• 是否有数据库连接错误？

---

📊 前端已修复的内容

修复 1: syncFileStatus() 添加进度加载

文件: src/store.ts

改动：

// 在 syncFileStatus() 中，当状态为 processing 时，加载进度数据
if (newStatus === 'processing') {
  await loadPipelineStats(fileUuid, true)
}

效果：每 10 秒轮询时，会更新进度数据

---

修复 2: LibraryView 启动轮询（处理边缘情况）

文件: src/views/LibraryView.vue

改动：

// 即使没有 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 优先级: 🔴 高 - 影响用户体验