# Videos 表命名不一致分析

> Date: 2026-04-28 20:20
> Issue: 表名 `videos` 与术语 `file_uuid` 不一致

---

## 问题发现

### 术语定义 vs 实际表名

| 术语 | AGENTS.md 定义 | 实际数据库 | 不一致 |
|------|---------------|-----------|--------|
| **file_uuid** | Video file identifier | `videos.uuid` | ✅ 列名是 `uuid` 不是 `file_uuid` |
| **表名** | 未定义 | `videos` | ❌ 应为 `files` |

### 相关表命名

| 表名 | 列名 | FK引用 | 一致性 |
|------|------|--------|--------|
| **videos** | uuid | - | ❌ 应为 `files` |
| **face_detections** | file_uuid | videos.uuid | ✅ 使用 file_uuid |
| **chunks** | uuid | videos.uuid | ❌ 应为 file_uuid |
| **jobs** | asset_uuid | videos.uuid | ⚠️ 使用 asset_uuid |

---

## 迁移计划缺失

### Phase 1 计划 vs 实际执行

| 计划项 | 执行状态 | 缺失 |
|--------|---------|------|
| 列名: video_uuid → file_uuid | ✅ 完成 | - |
| 表名: videos → files | ❌ 未执行 | **缺失** |
| FK引用更新 | ⚠️ 部分 | 未完全更新 |

### Migration 025 内容

```sql
-- 025_rename_video_uuid_to_file_uuid.sql

-- 1. 列重命名
ALTER TABLE face_detections RENAME COLUMN video_uuid TO file_uuid;
ALTER TABLE face_clusters RENAME COLUMN video_uuid TO file_uuid;
ALTER TABLE person_identities RENAME COLUMN video_uuid TO file_uuid;

-- 2. 表名重命名 ❌ 缺失
-- ALTER TABLE videos RENAME TO files;  <-- 应有但无

-- 3. 主表列重命名 ❌ 缺失
-- ALTER TABLE videos RENAME COLUMN uuid TO file_uuid; <-- 应有但无
```

---

## 影响范围

### SQL 引用统计

| 类别 | 数量 | 需修改 |
|------|------|--------|
| SQL 语句引用 videos | 50 处 | ✅ 需改 |
| Rust VideoRecord | 50 处 | ✅ 需改 |
| FK 定义 | 5 处 | ✅ 需改 |
| Rust 方法名 | 5 处 | ⚠️ 可选 |

### FK 关系图

```
videos (主表)
  ↓
├── face_detections.file_uuid → videos.uuid
├── face_clusters.file_uuid → videos.uuid
├── chunks.uuid → videos.uuid
├── jobs.asset_uuid → videos.uuid
├── file_identities.file_uuid → videos.uuid
└── processor_results.video_id → videos.id
```

---

## 不一致原因分析

### 可能原因

1. **Phase 1 计划不完整**
   - 仅计划列重命名，未规划表重命名
   - Migration 025 缺少表重命名语句

2. **FK 依赖复杂**
   - 多表引用 videos.uuid/videos.id
   - 重命名需更新所有 FK

3. **Rust 代码耦合**
   - VideoRecord struct
   - get_video_by_uuid() 方法名
   - 50 处代码引用

---

## 解决方案

### 方案 A: 保持现状（最小改动）

**策略**:
- 表名保持 `videos`
- 术语使用 `file_uuid`（仅在文档/API层）
- 数据库层保持 `videos.uuid`

**优点**:
- 无破坏性更改
- FK 无需更新
- Rust 代码无需改

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

**适用**: 当前阶段（已大量数据）

---

### 方案 B: 完整重命名（推荐长期）

**策略**:
- 表名: `videos` → `files`
- 主列: `uuid` → `file_uuid`
- 所有 FK 引用更新

**迁移脚本**:

```sql
-- Migration: 029_rename_videos_to_files.sql

BEGIN;

-- 1. 重命名表
ALTER TABLE videos RENAME TO files;

-- 2. 重命名主列
ALTER TABLE files RENAME COLUMN uuid TO file_uuid;

-- 3. 更新 FK 引用（需重建 FK）
-- face_detections
ALTER TABLE face_detections 
DROP CONSTRAINT fk_face_detections_file,
ADD CONSTRAINT fk_face_detections_file 
    FOREIGN KEY (file_uuid) REFERENCES files(file_uuid) ON DELETE CASCADE;

-- chunks
ALTER TABLE chunks 
DROP CONSTRAINT IF EXISTS chunks_uuid_fkey,
ADD CONSTRAINT chunks_file_uuid_fkey 
    FOREIGN KEY (uuid) REFERENCES files(file_uuid) ON DELETE CASCADE;

-- ... 其他表

COMMIT;
```

**Rust 代码更新**:

```rust
// postgres_db.rs
pub struct FileRecord {  // 原 VideoRecord
    pub file_uuid: String,  // 原 uuid
    // ...
}

pub async fn get_file_by_uuid(&self, uuid: &str) -> Result<Option<FileRecord>>

// schema.rs
assert_eq!(table_name("files"), "files");  // 原 videos
```

**优点**:
- 完全一致
- 术语统一
- 新代码清晰

**缺点**:
- 破坏性更改
- 大量代码修改
- FK 需重建

---

### 方案 C: 混合方案（渐进）

**策略**:
- 保持表名 `videos`
- 添加别名层

```sql
-- 创建视图别名
CREATE VIEW files AS SELECT * FROM videos;

-- 或添加注释
COMMENT ON TABLE videos IS 'File records (also referred to as videos)';
```

**优点**:
- 无破坏性
- 新代码可用 `files`
- 旧代码兼容

**缺点**:
- 视图性能开销
- 仍有两套名称

---

## 建议

### 短期：方案 A（现状）

**理由**:
- 已有大量数据（7479 videos + 78 face_detections）
- FK 关系复杂
- Phase 1 已完成列重命名

### 中期：方案 C（别名）

**理由**:
- 为新代码提供一致性
- 保持旧代码兼容

### 长期：方案 B（重命名）

**时机**: 下一次大版本升级

---

## 当前状态

### 表命名现状

```
videos.uuid (VARCHAR(32))
  ├── face_detections.file_uuid (VARCHAR(255)) ✅ 已改
  ├── face_clusters.file_uuid ✅ 已改
  ├── chunks.uuid ❌ 未改（应为 file_uuid）
  ├── jobs.asset_uuid ⚠️ 未改（asset_uuid != file_uuid）
  └── file_identities.file_uuid ✅ 新表已用 file_uuid
```

### 已完成的迁移

| 表 | 列迁移 | 状态 |
|-----|--------|------|
| face_detections | video_uuid → file_uuid | ✅ |
| face_clusters | video_uuid → file_uuid | ✅ |
| person_identities | video_uuid → file_uuid | ✅ (已删除) |
| person_appearances | video_uuid → file_uuid | ✅ (已删除) |

### 未完成的迁移

| 表 | 列 | 应改名 | 状态 |
|-----|-----|--------|------|
| videos | uuid | file_uuid | ❌ |
| videos | 表名 | files | ❌ |
| chunks | uuid | file_uuid | ❌ |
| jobs | asset_uuid | file_uuid | ⚠️ 可选 |

---

## 相关文件

| 文件 | 需修改 |
|------|--------|
| `migrations/025_rename_video_uuid_to_file_uuid.sql` | ❌ 缺表重命名 |
| `src/core/db/postgres_db.rs:160` | VideoRecord struct |
| `src/core/db/schema.rs:28` | table_name("videos") |
| `src/core/db/postgres_db.rs:762` | get_video_by_uuid() |

---

## 结论

**问题**: Phase 1 迁移计划不完整，仅做了列重命名，未做表重命名

**建议**: 当前保持现状，中期添加别名，长期完整重命名

**优先级**: 低（不影响功能，仅命名一致性）
