# V4.0 Migration 问题追踪报告

> Date: 2026-04-28 20:50
> Status: Phase 1 + Phase 2 完成，数据源问题修复中

---

## 已完成工作

### Phase 1: 术语统一 (video_uuid → file_uuid)

| 类别 | 数量 | 状态 |
|------|------|------|
| **Rust 代码** | 11 文件 | ✅ 完成 |
| **Portal (PHP)** | 6 文件 | ✅ 完成 |
| **文档** | 117 处 | ✅ 完成 |
| **Migration 025** | DB 列重命名 | ✅ 完成 |

### Phase 2: 架构简化 (person_identities 删除)

| 类别 | 状态 |
|------|------|
| **Migration 026** | file_identities 表创建 ✅ |
| **Migration 027** | identities.identity_id 添加 ✅ |
| **Migration 028** | person_identities 删除 ✅ |
| **SQLx Cache** | 已更新 ✅ |

### 今日修复

| 问题 | 分析报告 | 修复状态 |
|------|----------|----------|
| **UUID 长度问题** | `UUID_LENGTH_ISSUE.md` | ✅ 分析完成（保持兼容） |
| **Videos 表命名** | `VIDEOS_TABLE_NAMING_ISSUE.md` | ✅ 分析完成（保持现状） |
| **Rule 1 Face 数据源** | `RULE1_FACE_DATA_SOURCE_FIX.md` | ✅ 修复完成 |

---

## 发现的问题

### 问题 1: UUID 长度不一致

**现象**:
- 20 个 video 使用 16-char UUID（旧格式）
- 7479 个 video 使用 32-char UUID（Birth UUID）

**示例**: `384b0ff44aaaa1f14cb2cd63b3fea966` (16-char)

**原因**:
- `compute_uuid()` 取 SHA256[0:16]
- `compute_birth_uuid()` 取 SHA256[0:32]

**决策**: 保持兼容模式（不强制迁移）

**影响**: 
- Birth UUID 功能受限（`is_birth_uuid()` 返回 false）
- 跨设备同步不支持

---

### 问题 2: 表命名不一致

**现象**:
- 表名: `videos`
- 术语: `file_uuid`

**原因**: Phase 1 迁移计划缺失表重命名

**对比**: `talents → identities` 已完成，但 `videos → files` 未执行

**决策**: 短期保持现状，中期添加别名，长期完整重命名

**影响**:
- 文档与代码不一致
- 新开发者困惑

---

### 问题 3: Rule 1 数据源不匹配

**现象**:
- Face 数据在 face_detections 表
- rule1_ingest.rs 从 pre_chunks 读取

**修复**: fetch_face_frames() 改为从 face_detections 读取

**验证**: 编译通过，数据源正确

**遗留**: YOLO/ASRX 数据缺失

---

## Processor 状态 (384b0ff44aaaa1f14cb2cd63b3fea966)

| Processor | processor_results | chunks_produced | 数据源状态 |
|-----------|-------------------|-----------------|------------|
| **ASR** | completed | 3664 | pre_chunks ✅ |
| **CUT** | completed | 1332 | pre_chunks ✅ |
| **Face** | failed | 0 | face_detections 有 78 条 ⚠️ |
| **YOLO** | failed | 0 | pre_chunks 缺失 ❌ |
| **OCR** | failed | 0 | pre_chunks 缺失 ❌ |
| **ASRX** | 未运行 | - | pre_chunks 缺失 ❌ |

---

## Rule 1 数据可用性

| 数据类型 | 可用 | Rule 1 可用 |
|----------|------|-------------|
| **ASR segments** | ✅ 3664 | ✅ |
| **CUT segments** | ✅ 1332 | ✅ |
| **Face frames** | ✅ 78 (修复后) | ✅ |
| **YOLO frames** | ❌ 0 | ❌ → metadata.yolo_objects = [] |
| **ASRX segments** | ❌ 0 | ❌ → metadata.speaker_id = "UNKNOWN" |

---

## 待解决问题

### 高优先级

| 问题 | 影响 | 解决方案 |
|------|------|----------|
| **YOLO processor failed** | YOLO objects 缺失 | 检查错误日志，修复 processor |
| **ASRX processor 未运行** | Speaker ID 缺失 | 启动 ASRX processor |
| **2 个 Rule1 jobs QUEUED** | Rule 1 未执行 | 启动 Job Worker |

### 中优先级

| 问题 | 影响 | 解决方案 |
|------|------|----------|
| **Face processor failed** | processor_results 记录错误 | 检查错误原因 |
| **chunks metadata 空** | Face/Speaker 未绑定 | 重新运行 Rule 1 |

### 低优先级

| 问题 | 影响 | 解决方案 |
|------|------|----------|
| **20 个 16-char UUID** | Birth UUID 功能受限 | 长期迁移计划 |
| **videos 表命名** | 术语不一致 | 长期重命名计划 |

---

## Jobs 状态

```sql
SELECT id, status, rule, created_at 
FROM dev.jobs 
WHERE asset_uuid = '384b0ff44aaaa1f14cb2cd63b3fea966';

-- Result:
id: 9e5df703... status: QUEUED, rule: rule1, created: 2026-04-21 19:04
id: 751d90b5... status: QUEUED, rule: rule1, created: 2026-04-21 16:54
```

**问题**: Job Worker 可能未运行

---

## 下一步计划

### Phase 1: Processor 启动

1. 检查 YOLO processor 错误日志
2. 启动 ASRX processor
3. 等待 processor_results 完成

### Phase 2: Rule 1 测试

1. 启动 Job Worker
2. 执行 Rule 1 处理
3. 验证 chunks metadata:
   - speaker_id (来自 ASRX)
   - yolo_objects (来自 YOLO)
   - face_ids (来自 face_detections)

### Phase 3: Identity 绑定

1. 创建 identity_binding_v4.rs
2. Face → Identity 直接绑定
3. Chunk 自动绑定

---

## 相关文档

| 文档 | 说明 |
|------|------|
| `docs_v1.0/UUID_LENGTH_ISSUE.md` | UUID 长度问题分析 |
| `docs_v1.0/VIDEOS_TABLE_NAMING_ISSUE.md` | 表命名问题分析 |
| `docs_v1.0/RULE1_FACE_DATA_SOURCE_FIX.md` | Face 数据源修复 |
| `docs_v1.0/RULE1_CHUNK_INGESTION_CHECK.md` | Rule 1 问题分析 |
| `docs_v1.0/RULE1_TRIGGER_MECHANISM.md` | Rule 1 启动机制 |
| `docs_v1.0/V4_MIGRATION_COMPLETE.md` | Migration 完成报告 |

---

## 统计数据

### 数据库记录

| 表 | 记录数 | 备注 |
|-----|--------|------|
| **videos** | 7499 | 20 个 16-char UUID |
| **face_detections** | 78 (384b0ff44...) | 通用数据 |
| **chunks** | 3664 | sentence 类型 |
| **pre_chunks** | 4996 | ASR + CUT |

### Migration 文件

| 文件 | 说明 | 状态 |
|------|------|------|
| `025_rename_video_uuid_to_file_uuid.sql` | 列重命名 | ✅ |
| `026_create_file_identities_table.sql` | file_identities 表 | ✅ |
| `027_add_identity_id_to_identities.sql` | identity_id 列 | ✅ |
| `028_drop_person_identities_table.sql` | 删除旧表 | ✅ |

---

## 代码质量

### 编译验证

```bash
cargo check --lib   # ✅ Passed (warnings only)
cargo test --lib    # ✅ 178 tests passed
cargo clippy --lib  # ✅ Passed
```

### 未修改文件

- identity_binding_v4.rs（已删除，待重写）
- Job Worker（待检查运行状态）

---

## 结论

**已完成**:
- ✅ V4.0 Migration Phase 1 + Phase 2
- ✅ UUID 长度问题分析（决策：保持兼容）
- ✅ Videos 表命名问题分析（决策：保持现状）
- ✅ Rule 1 Face 数据源修复

**待处理**:
- 🔧 YOLO/ASRX processor 启动
- 🔧 Job Worker 启动
- 🔧 Rule 1 测试验证

**建议**: 先解决 Processor 问题，再测试 Rule 1 完整流程。