# V4.0 Migration Status

> Date: 2026-04-28

---

## Completed Tasks

### Phase 1: Terminology Migration (video_uuid → file_uuid)

| Task | Status | Details |
|------|--------|---------|
| **DB Migration 025** | ✅ | face_detections, face_clusters, person_identities renamed |
| **Rust API** | ✅ | 11 files batch replaced |
| **Portal** | ✅ | 6 Vue/Tauri files |
| **Documents** | ✅ | 117 MD files |

### Phase 2: Architecture Simplification

| Task | Status | Details |
|------|--------|---------|
| **DB Migration 026** | ✅ | file_identities table created |
| **DB Migration 027** | ✅ | identity_id FK added to face_detections |
| **DB Migration 028** | ✅ | person_identities + person_appearances dropped |
| **New Binding API** | ⏸ | identity_binding_v4.rs (SQLx compile error) |

---

## Current Issue

**SQLx Compile Error**: "invalid input syntax for type json"

Cause: identities.metadata column is JSONB, but SQLx requires exact type matching during compile-time checks.

---

## Database State

```sql
-- Tables Created
file_identities (N:N relationship)
  - file_uuid, identity_id, face_count, confidence

-- Tables Renamed
face_detections.video_uuid → file_uuid
face_clusters.video_uuid → file_uuid

-- Tables Deleted
person_identities ✅
person_appearances ✅
```

---

## Next Steps

### Option A: Fix SQLx (Recommended)

1. Remove identity_binding_v4.rs temporarily
2. Run `cargo sqlx prepare` to update cache
3. Fix SQL queries with proper JSONB binding
4. Re-add identity_binding_v4.rs

### Option B: Use SQLX_OFFLINE

```bash
SQLX_OFFLINE=true cargo build --lib
cargo sqlx prepare
```

### Option C: Skip for Now

Keep existing person_identity.rs API, migrate later when database is stable.

---

## Test Commands

```bash
# Verify tables
psql -U accusys -d momentry -c "\dt dev.*"

# Check columns
psql -U accusys -d momentry -c "
SELECT table_name, column_name 
FROM information_schema.columns 
WHERE table_schema = 'dev' 
AND column_name = 'file_uuid'
ORDER BY table_name;
"

# Build (if SQLx fixed)
cargo build --lib
cargo test --lib
```

---

## Files Modified

| File | Lines |
|------|-------|
| migrations/025_rename_video_uuid_to_file_uuid.sql | 42 |
| migrations/026_create_file_identities_table.sql | 39 |
| migrations/027_add_identity_id_to_face_detections.sql | 30 |
| migrations/028_drop_person_identities_table.sql | 29 |
| src/api/identity_binding_v4.rs | 310 |
| src/api/mod.rs | +1 line |
| src/api/server.rs | +1 line |

---

## Migration Summary

| Aspect | V3.x | V4.0 |
|--------|------|------|
| **video_uuid** | Used everywhere | **file_uuid** |
| **person_identities** | 303 records | **Removed** |
| **file_identities** | N/A | **Created** |
| **API Endpoints** | 33 | 15 (pending) |
| **Binding Logic** | 3-layer | 2-layer (pending) |
