# Core Team Action Items - Pipeline Progress Issue

## ✅ Studio Team 已完成修复

**修复内容**：
1. ✅ 权重配置已修正（基于 Core team 规格）
2. ✅ 移除 identity_agent 过滤
3. ✅ API 端点已验证正确

**Commit**: `待推送`

---

## 🚨 问题摘要（已部分解决）

**现象**：Library 卡片在 deep scan 时卡在 "Scanning..." 状态，没有进度百分比

**前端已修复**：
- ✅ 权重配置已修正（基于 Core team 规格）
- ✅ 移除 identity_agent 过滤
- ✅ API 端点已验证正确（无需修改）
- ✅ `syncFileStatus()` 现在会加载进度数据
- ✅ LibraryView 会启动轮询即使 pipeline 数据缺失

**后端需要诊断**：3 项核心问题

---

## 📋 Core Team 需要检查的项目

### 1. 🟡 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 执行错误？
- 是否有文件处理超时？
- 是否有数据库连接错误？

---

## 📊 API 端点验证结果

### ✅ 已验证正确（无需修改）

**API 端点已是正确的**：
- ✅ `get_pipeline_stats`: `/api/v1/stats/pipeline/:file_uuid` (src/api/index.ts:510)
- ✅ `sync_file_status`: `/api/v1/file/:file_uuid/sync-status` (src/api/index.ts:582)

**权重配置已修正**：
```typescript
const WEIGHT_MAP = {
  processors: 0.30,
  rule1_ingestion: 0.05,      // ✅ 已修正（was 0.10）
  face_tracing: 0.05,         // ✅ 已修正（was 0.10）
  identity_agent: 0.10,       // ✅ 已添加（was filtered out）
  tkg_nodes: 0.20,
  tkg_edges: 0.15,
  rule2_ingestion: 0.15
}
```

---

## 📊 前端已修复的内容

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

**文件**: `src/store.ts:888-891`

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

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

---

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

**文件**: `src/views/LibraryView.vue:789-790`

**改动**：
```typescript
// 即使没有 pipeline 数据，如果状态是 processing，也启动轮询
else if (!pipeline && f.status === 'processing') {
  pollPipelineProgress(f.file_uuid)
}
```

**效果**：不会因为 pipeline 数据缺失而无法启动轮询

---

### 修复 3: 权重配置修正

**文件**: `src/store.ts:923-931`

**改动**：
```typescript
const WEIGHT_MAP: Record<string, number> = {
  processors: 0.30,
  rule1_ingestion: 0.05,      // ✅ 修正（was 0.10）
  face_tracing: 0.05,         // ✅ 修正（was 0.10）
  identity_agent: 0.10,       // ✅ 添加（was filtered out）
  tkg_nodes: 0.20,
  tkg_edges: 0.15,
  rule2_ingestion: 0.15
}
```

**效果**：进度百分比计算准确

---

### 修复 4: 移除 identity_agent 过滤

**文件**: `src/store.ts:919`

**改动**：
```typescript
// 移除过滤，包含所有阶段
const stages = data.stages || []
```

**效果**：identity_agent 阶段被正确追踪

---

## ✅ 修复验证清单

修复后，前端期望看到：

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
**优先级**: 🔴 高 - 影响用户体验