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
2026-07-25 01:36:32 +08:00
parent c347c200b2
commit 36074b1017
1 changed files with 293 additions and 0 deletions
--- a/CORE_TEAM_ACTION_ITEMS.md
+++ b/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
+**优先级**: 🔴 高 - 影响用户体验