# Dev 3003 改造記錄

| 項目 | 內容 |
|------|------|
| 建立者 | Warren |
| 建立時間 | 2026-04-30 |
| 文件版本 | V1.0 |

---

## 版本歷史

| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-04-30 | Dev 3003 全面改造 | Warren | OpenCode |

---

## 1. 改造目標

- 將 Dev 3003 (Playground) 與 Public 3002 完全隔離
- 統一術語：`video_uuid` → `file_uuid`
- 修復資料庫結構問題（probe_json 類型、timestamp 類型）
- Python 腳本和 output 目錄隔離

---

## 2. PostgreSQL Schema 修復

### 2.1 probe_json 類型修復

**問題**: `dev.videos.probe_json` 類型為 `TEXT`，但 Rust 期望 `JSONB`

**修復**:
```sql
ALTER TABLE dev.videos ALTER COLUMN probe_json TYPE jsonb USING probe_json::jsonb;
```

### 2.2 video_uuid → file_uuid 重命名 (10 張表)

| 表 | 狀態 |
|----|------|
| `dev.backup_registry` | ✅ 已重命名 |
| `dev.castings` | ✅ 已重命名 |
| `dev.characters` | ✅ 已重命名 |
| `dev.face_identities` | ✅ 已重命名 |
| `dev.face_recognition_results` | ✅ 已重命名 |
| `dev.file_lifecycle` | ✅ 已重命名 |
| `dev.file_registry` | ✅ 已重命名 |
| `dev.processor_results` | ✅ 已重命名 |
| `dev.video_events` | ✅ 已重命名 |
| `dev.video_identities` | ✅ 已重命名 |

**修復 SQL**:
```sql
ALTER TABLE dev.backup_registry RENAME COLUMN video_uuid TO file_uuid;
ALTER TABLE dev.castings RENAME COLUMN video_uuid TO file_uuid;
ALTER TABLE dev.characters RENAME COLUMN video_uuid TO file_uuid;
ALTER TABLE dev.face_identities RENAME COLUMN video_uuid TO file_uuid;
ALTER TABLE dev.face_recognition_results RENAME COLUMN video_uuid TO file_uuid;
ALTER TABLE dev.file_lifecycle RENAME COLUMN video_uuid TO file_uuid;
ALTER TABLE dev.file_registry RENAME COLUMN video_uuid TO file_uuid;
ALTER TABLE dev.processor_results RENAME COLUMN video_uuid TO file_uuid;
ALTER TABLE dev.video_events RENAME COLUMN video_uuid TO file_uuid;
ALTER TABLE dev.video_identities RENAME COLUMN video_uuid TO file_uuid;

-- 重建 constraint
ALTER TABLE dev.face_recognition_results 
    DROP CONSTRAINT face_recognition_results_video_uuid_key;
ALTER TABLE dev.face_recognition_results 
    ADD CONSTRAINT face_recognition_results_file_uuid_key UNIQUE (file_uuid);
```

### 2.3 timestamp 類型修復

**問題**: `dev.videos.created_at`, `updated_at`, `registered_at` 為 `TIMESTAMP` (without time zone)，但 Rust 期望 `TIMESTAMPTZ`

**修復**:
```sql
ALTER TABLE dev.videos ALTER COLUMN created_at TYPE timestamptz USING created_at AT TIME ZONE 'UTC';
ALTER TABLE dev.videos ALTER COLUMN updated_at TYPE timestamptz USING updated_at AT TIME ZONE 'UTC';
ALTER TABLE dev.videos ALTER COLUMN registered_at TYPE timestamptz USING registered_at AT TIME ZONE 'UTC';
```

---

## 3. Rust 代碼修改

### 3.1 `src/api/server.rs`

| 行號 | 修改前 | 修改後 |
|------|--------|--------|
| 3982 | `DELETE FROM {} WHERE video_uuid = $1` | `DELETE FROM {} WHERE file_uuid = $1` |

### 3.2 `src/api/face_recognition.rs`

| 行號 | 修改前 | 修改後 |
|------|--------|--------|
| 721 | `WHERE video_uuid = $1` | `WHERE file_uuid = $1` |
| 764 | `"video_uuid": file_uuid` | `"file_uuid": file_uuid` |
| 786 | `video_uuid: &str` (參數) | `file_uuid: &str` (參數) |
| 807 | `ON CONFLICT (video_uuid)` | `ON CONFLICT (file_uuid)` |
| 818 | `.bind(video_uuid)` | `.bind(file_uuid)` |
| 877 | `.bind(video_uuid)` | `.bind(file_uuid)` |
| 926 | `.bind(video_uuid)` | `.bind(file_uuid)` |

### 3.3 測試修復

| 檔案 | 修改 |
|------|------|
| `src/core/db/postgres_db.rs:4550` | 添加 `file_type: None` 到 `VideoRecord` 測試 |

---

## 4. Python 腳本隔離

### 4.1 更新預設 DATABASE_URL (7 個腳本)

| 腳本 | 修改 |
|------|------|
| `scripts/clip_logo_integration.py` | `?options=-c%20search_path=dev` |
| `scripts/match_face_with_pose_filtering.py` | `?options=-c%20search_path=dev` |
| `scripts/select_face_reference_vectors_v2.py` | `?options=-c%20search_path=dev` |
| `scripts/match_face_identity.py` | `?options=-c%20search_path=dev` |
| `scripts/tmdb_identity_integration.py` | `?options=-c%20search_path=dev` |
| `scripts/select_face_reference_vectors.py` | `?options=-c%20search_path=dev` |
| `scripts/test_identity_db.py` | `?options=-c%20search_path=dev` |

### 4.2 output 目錄隔離

| 腳本 | 修改 |
|------|------|
| `scripts/identity_agent.py` | 預設 output 改為 `/Users/accusys/momentry/output_dev` |

### 4.3 環境變數配置

`.env.development` 已配置：
```bash
MOMENTRY_OUTPUT_DIR=/Users/accusys/momentry/output_dev
DATABASE_SCHEMA=dev
MONGODB_DATABASE=momentry_dev
QDRANT_COLLECTION=momentry_dev_rule1
REDIS_PREFIX=momentry_dev:
```

---

## 5. 隔離狀態總覽

| 資源 | 配置 | 狀態 |
|------|------|------|
| PostgreSQL | `DATABASE_SCHEMA=dev` | ✅ 隔離 |
| MongoDB | `momentry_dev` | ✅ 隔離 |
| Qdrant | `momentry_dev_rule1` | ✅ 隔離 |
| Redis | `momentry_dev:` | ✅ 隔離 |
| Output Dir | `/Users/accusys/momentry/output_dev` | ✅ 隔離 |

---

## 6. 驗證結果

### 6.1 Build 驗證
- `cargo build --bins`: ✅ 成功
- `cargo clippy --lib`: ✅ 通過 (119 warnings, 0 errors)
- `cargo test --lib`: ✅ 178 tests passed

### 6.2 API 驗證
- `GET /api/v1/files`: ✅ 返回 200 (之前返回 500)
- 測試數據: 6 個檔案已註冊

---

## 7. 待辦事項

| 任務 | 優先級 | 狀態 |
|------|--------|------|
| 設計 Dev 3003 API 結構 (v1.0 aligned) | Medium | ⬜ |
| 實作 `GET /api/v1/files/{uuid}/identities` | Medium | ⬜ |
| 實作 `GET /api/v1/identities/{uuid}` | Medium | ⬜ |
| 實作 `GET /api/v1/identities/{uuid}/files` | Medium | ⬜ |
| 實作 AI Agent API (clustering/merge suggestions) | Medium | ⬜ |

---

## 8. 注意事項

### 8.1 Public 3002 不受影響
- 所有修改僅限於 `dev` schema
- `public` schema 保持原狀
- Rust 代碼修改適用於兩者，但 SQL 中的 column name 已統一為 `file_uuid`

### 8.2 Python 腳本注意事項
- 仍有其他 Python 腳本使用 `DB_CONFIG`、`POSTGRES_CONFIG` 等模式
- 這些腳本需單獨檢查和更新
- 建議逐步遷移至使用環境變數

### 8.3 已知限制
- Player module 仍使用 `video_uuid` 變數名（內部使用，不影響 API）
- 部分 Python 腳本的 output 路徑仍需手動指定
