# V4.0 Migration Phase 3 执行记录

> Date: 2026-04-28 21:10
> Action: 禁用旧 API (person_identity.rs)

---

## 执行内容

### 修改文件

| 文件 | 修改内容 | 行号 |
|------|----------|------|
| `src/api/server.rs` | 注释掉 person_identity_routes() | 2564 |
| `src/api/server.rs` | 删除 person_identity import | 32 |

### 代码变更

```rust
// Before
.merge(person_identity::person_identity_routes())

// After
// .merge(person_identity::person_identity_routes()) // V4.0: DISABLED (person_identities table removed)
```

---

## 影响范围

### 已禁用的 API

| API 类别 | 路径前缀 | 数量 | 状态 |
|----------|----------|------|------|
| **people APIs** | `/api/v1/people/*` | 16+ | ❌ 已禁用 |
| **persons APIs** | `/api/v1/persons/*` | 3 | ❌ 已禁用 |
| **chunks APIs** | `/api/v1/chunks/*` | 1 | ❌ 已禁用 |
| **identities APIs** | `/api/v1/identities/search` | 1 | ❌ 已禁用 |
| **videos APIs** | `/api/v1/videos/:uuid/faces` | 1 | ❌ 已禁用 |

**总计**: 24+ 个路由已禁用

---

## 禁用原因

所有 API 引用已删除的 `person_identities` 表：

```sql
-- V3.x 实现 (已失效)
FROM face_detections fd
JOIN person_identities pi ON fd.file_uuid = pi.file_uuid
WHERE pi.face_identity_id = $1

-- V4.0 架构
person_identities 表已删除 (Migration 028)
face_detections.identity_id 直接绑定
```

---

## 编译验证

```bash
cargo check --lib   # ✅ Passed (1 warning: unused import)
cargo build --release --bin momentry_playground  # ✅ Passed (53 warnings)
```

---

## Playground 重启

```
Version: 0.1.0 (build: 2026-04-28 21:06:11)
Port: 3003
Status: Running
```

---

## API 测试

### 已禁用 API

```bash
curl "http://localhost:3003/api/v1/people/list"

# Expected: 404 Not Found
```

### 可用 API

根据 IDENTITY_API_SPEC.md，V4.0 应提供：

| API | 状态 | 说明 |
|-----|------|------|
| **GET /api/v1/identities** | ✅ 可用 | identities.rs 已有 |
| **GET /api/v1/identities/:uuid/faces** | ❌ 需实现 | 新架构 |
| **GET /api/v1/identities/:uuid/files** | ✅ 可用 | identities.rs 已有 |
| **GET /api/v1/files/:uuid/identities** | ✅ 可用 | identities.rs 已有 |
| **POST /api/v1/identities/register** | ✅ 可用 | identities.rs 已有 |
| **POST /api/v1/identities/:uuid/bind** | ✅ 可用 | identities.rs 已有 |

---

## person_identity.rs 保留策略

**文件状态**: 保留（未删除）

**原因**:
- 3280 行代码可作为参考
- 部分 logic 可迁移到新 API
- 避免破坏其他依赖

**后续**: 
- 创建新的 identity_faces_api.rs
- 实现 V4.0 架构的 API
- 逐步迁移有用逻辑

---

## V4.0 架构对比

### V3.x (已禁用)

```
person_identities 表
  ↓
API: /api/v1/people/*
  ↓
JOIN person_identities
```

### V4.0 (新架构)

```
face_detections.identity_id (直接绑定)
  ↓
API: /api/v1/identities/:uuid/faces
  ↓
WHERE identity_id = $1
```

---

## 下一步

### 已完成

- ✅ 禁用旧 API (person_identity_routes)
- ✅ 修复 unused import
- ✅ Playground 重启
- ✅ 编译验证通过

### 待处理

- 🔧 测试已禁用 API 返回 404
- 🔧 实现 V4.0 `/api/v1/identities/:uuid/faces`
- 🔧 测试新 API 可用性
- 🔧 Portal 前端适配新 API

---

## 相关文件

| 文件 | 说明 |
|------|------|
| `src/api/person_identity.rs` | 保留（已禁用路由） |
| `src/api/server.rs:2564` | 路由注册已注释 |
| `docs_v1.0/IDENTITY_API_SPEC.md` | V4.0 API 规范 |
| `docs_v1.0/V4_MIGRATION_COMPLETE.md` | Migration 完成 |

---

## 注意事项

**Portal 前端影响**:
- 前端可能调用 `/api/v1/people/list`
- 需更新为 `/api/v1/identities`
- UI 组件需适配新 API

**数据库影响**:
- person_identities 表已删除
- face_detections.identity_id 已添加
- identities 表已更新

**建议**: 先测试后端 API，再更新前端
