# Implementation Compatibility Analysis Report

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

---

## 版本歷史

| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-04-25 | 分析新架構與現有文件的相容性 | OpenCode | OpenCode |

---

## 概述

本文檔比對了「全新 File/Identity/Candidate 架構」與 `docs_v1.0` 現有文件的相容性，提出過時文件合併、刪除或重構的建議，並分析衝突內容。

---

## 1. 核心架構變更比對

### 1.1 資料庫變更
| 項目 | 舊設計 (Current) | 新設計 (Proposed) | 影響層級 |
|------|------------------|-------------------|----------|
| **主要媒體表** | `videos` (Video 專屬) | `files` (所有檔案: video/pdf/png...) | 高 (核心實體變更) |
| **身份表** | `face_identities` (僅限臉部) | `identities` (全域所有實體) | 高 (擴充型變更) |
| **人物表** | `person_identities` (影片級) | `file_identities` (關聯表) | 高 (結構變更) |
| **檢測表** | `face_detections`, `face_clusters` | `faces`, `candidates` | 中 (重構與合併) |

### 1.2 流程變更
| 項目 | 舊設計 (Current) | 新設計 (Proposed) |
|------|------------------|-------------------|
| **註冊** | `register` API 直接處理 | `probe` Processor 自動判斷與分類 |
| **身份歸屬** | 手動或 TMDB 觸發 | Candidate 狀態轉換與 Agent 建議 |
| **Face 處理** | `face_processor` 獨立運行 | 視為 Resource 指派的一環 |

---

## 2. 衝突文件分析

### 2.1 高衝突文件 (需大幅修改或刪除)

| 文件路徑 | 衝突內容 | 建議動作 | 原因 |
|----------|----------|----------|------|
| **ARCHITECTURE/TMDB_CHARACTER_INTEGRATION.md** | 詳細定義了 `global_person_identities` 和 `person_identities` 結構，與新架構完全不符。 | **刪除** | 新設計已在 `FILE_IDENTITY_API_DESIGN.md` 中定義了全新的 Identity 邏輯，此文檔已失效。 |
| **ARCHITECTURE/SPEAKER_INTEGRATION.md** | 依賴舊版 `global_person_identities` 表結構，提及 `voice_print`。 | **合併** | 將核心概念（聲紋匹配）整合至新的 Design Doc 中，並刪除本文檔。 |
| **ARCHITECTURE/IDENTITY_SYSTEM_DESIGN.md** | 定義了 `face_identities` 為檔案層級定妝表。 | **刪除** | 被 `FILE_IDENTITY_API_DESIGN.md` 取代。 |

### 2.2 中衝突文件 (需重構更新)

| 文件路徑 | 衝突內容 | 建議動作 | 原因 |
|----------|----------|----------|------|
| **ARCHITECTURE/PLAYGROUND_ARCHITECTURE.md** | 描述了 Playground 使用的舊表結構。 | **重構** | 更新為新的 `files`, `faces`, `identities` 結構。 |
| **ARCHITECTURE/chunking/CHUNKING_ENRICHMENT_PIPELINE.md** | 提到 `face_id_01` 查詢 `face_identities`。 | **重構** | 更新查詢邏輯，改為查詢 `identities` 表。 |

### 2.3 低衝突文件 (需更新名詞)

| 文件路徑 | 衝突內容 | 建議動作 | 原因 |
|----------|----------|----------|------|
| **OPERATIONS/PRODUCTION_DEPLOYMENT_GUIDE.md** | 包含 `videos` 表的索引指令和 `video_register` 資料庫備份。 | **更新** | 將 `videos` 改為 `files`，更新備份名稱。 |
| **OPERATIONS/BACKUP_VERSIONING.md** | 提及 `video_register` 資料庫。 | **更新** | 更新為 `files` 表相關的備份策略。 |

---

## 3. 執行建議

### 3.1 立即刪除 (已失效)
以下文件因架構被完全推翻，建議直接刪除：
1. `docs_v1.0/ARCHITECTURE/TMDB_CHARACTER_INTEGRATION.md`
2. `docs_v1.0/ARCHITECTURE/SPEAKER_INTEGRATION.md`
3. `docs_v1.0/ARCHITECTURE/IDENTITY_SYSTEM_DESIGN.md`

### 3.2 建立新文件 (Design Phase 2)
1. 將上述刪除文件中有價值的業務邏輯 (如: 聲紋提取邏輯、TMDB 角色映射邏輯) 遷移至 `FILE_IDENTITY_API_DESIGN.md` 或新的 `PROCESSOR_DESIGN.md`。

### 3.3 批量名詞替換
在 `docs_v1.0` 中執行全局替換 (需謹慎)：
- `person_identities` -> `file_identities` (僅限指代「人物在檔案中的出現」時)
- `face_identities` -> `identities` (僅限指代「全域身份」時)

---

## 4. 結論

目前的文檔庫 (`docs_v1.0`) 中，約有 **10%** 的架構設計文件與新系統不相容。在進入 Implementation 階段前，清理這些「殭屍文件」對於避免 AI Agent 檢索錯誤資訊至關重要。

---

## 版本資訊

- 版本: V1.0
- 分析日期: 2026-04-25
- 文件更新: 2026-04-25
