docs: update docs_v1.0/ documentation
- Fix markdown lint issues (MD030, MD047, MD051, MD028, MD005) - Update AI agents, architecture, implementation docs - Add new identity, face recognition, and API documentation - Remove deprecated face/person API guides
This commit is contained in:
Warren
249
docs_v1.0/V4_ISSUES_TRACKING.md
Normal file
249
docs_v1.0/V4_ISSUES_TRACKING.md
Normal file
@@ -0,0 +1,249 @@
|
||||
# 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 完整流程。
|
||||
Reference in New Issue
Block a user