feat: backup architecture docs, source code, and scripts

docs_v1.0/ARCHITECTURE/_deprecated/IDENTITY_SYSTEM_DESIGN.md

@@ -0,0 +1,498 @@
+---
+document_type: "architecture_design"
+service: "MOMENTRY_CORE"
+title: "Identity 系統設計規範"
+date: "2026-04-24"
+version: "V1.0"
+status: "deprecated"
+owner: "Warren"
+created_by: "OpenCode"
+tags:
+  - "deprecated"
+  - "identity"
+  - "系統設計規範"
+ai_query_hints:
+  - "查詢 Identity 系統設計規範 的內容"
+  - "Identity 系統設計規範 的主要目的是什麼？"
+  - "如何操作或實施 Identity 系統設計規範？"
+---
+
+> [!WARNING] **檔案已過時 (Deprecated)**
+> 
+> **原因**: 此文件定義的 `face_identities` 和舊版 `file_identities` 結構已被新的 `FILE_IDENTITY_API_DESIGN.md` 取代。新設計統一了 File、Identity 和 Candidate 的概念，並移除了複雜的 IPC 分類系統。
+> 
+> **狀態**: 僅供歷史參考，不應用於新功能的開發。
+> 
+> **搬移日期**: 2026-04-25
+
+# Identity 系統設計規範
+
+| 項目 | 內容 |
+|------|------|
+| 建立者 | OpenCode |
+| 建立時間 | 2026-04-24 |
+| 文件版本 | V1.0 |
+| 目的 | 定義全域身份 (Identity) 與泛型檔案 (File) 雙核心架構 |
+
+---
+
+## 版本歷史
+
+| 版本 | 日期 | 目的 | 操作人 |
+|------|------|------|--------|
+| V1.0 | 2026-04-24 | 初始設計規範，定義全域 Identity 與 File 雙核心架構、IPC 分類系統、關係分類 | OpenCode |
+
+---
+
+## 1. 核心概念
+
+### 1.1 全域操作物件
+
+| 物件 | 唯一識別碼 | 說明 |
+|------|-----------|------|
+| **File** | `file_uuid` | 泛型檔案（影片、圖片、PDF、PPT、Logo 圖檔等任何媒體類型） |
+| **Identity** | `identities_id` | 全域唯一實體，涵蓋所有可被識別、命名、追蹤的對象 |
+
+### 1.2 Identity 的涵蓋範圍
+
+Identity 不限於人類，任何可被系統識別且擁有意義的實體皆屬於此範疇：
+
+| 類別 | 範例 |
+|------|------|
+| **人物 (Person)** | 演員、導演、真實人物 |
+| **角色 (Character)** | 虛構角色（如《無間道》的劉建明） |
+| **吉祥物 (Mascot)** | Hello Kitty、皮卡丘 |
+| **品牌 (Brand/Logo)** | 公司商標、產品 Logo |
+| **物件 (Object)** | 特定道具、車輛 |
+| **動物 (Animal)** | 寵物、野生動物 |
+
+### 1.3 設計原則
+
+1. **Identity 全域唯一性**：`identities_id` 在全域範圍內唯一，同一個 Identity 可出現在多個不同檔案中。
+2. **File 泛型性**：`file_uuid` 不限於影片類型，支援任何媒體格式。
+3. **多特徵支援 (Multi-Face/Feature)**：一個 Identity 可擁有多個 **Face Identity (定妝/特徵群集)**。Face 明確屬於特定檔案（如：同一演員在不同影片中的不同造型）。
+4. **槽狀關聯結構 (Slot-based Association)**：檔案與身份的關係透過槽位表管理，紀錄檔案層級的專屬資訊（角色名稱、時間軸、位置等）。
+5. **關係分類支援**：支援人物間的親屬、社交、專業關係，應用於社交親屬關係圖譜。
+
+---
+
+## 2. IPC 風格分類系統
+
+### 2.1 分類碼結構
+
+採用 **IPC (International Patent Classification)** 標準格式：
+
+```
+[小類 Subclass] [主組 Main Group]/[分組 Subgroup]
+
+範例:  A61B 17/02
+        ↑    ↑  ↑
+        |    |  └─ 分組 (Subgroup) - 點號數量表示層級深度
+        |    └──── 主組 (Main Group)
+        └───────── 小類 (Subclass)
+```
+
+### 2.2 部分類定義 (Section)
+
+| 部代碼 | 名稱 | 說明 |
+|--------|------|------|
+| **A** | PERSONS (人物) | 真實人物、演員、導演、公眾人物 |
+| **B** | CHARACTERS (角色) | 虛構角色、動漫角色、戲劇人物 |
+| **C** | BRANDING (品牌) | 公司 Logo、產品商標、品牌識別 |
+| **D** | MASCOTS (吉祥物) | 商業吉祥物、活動吉祥物、IP 角色 |
+| **E** | OBJECTS (物件) | 車輛、武器、特定道具、建築物 |
+| **F** | ANIMALS (動物) | 寵物、野生動物、神話生物 |
+| **G** | LOCATIONS (場景) | 特定地點、地標、場景元素 |
+| **H** | AUDIO-VISUAL (視聽) | 特定音樂、音效、視覺效果模式 |
+
+### 2.3 關係分類系統 (R-Section)
+
+採用相同 IPC 格式，以 **R** 開頭表示「Relationship」：
+
+| 關係碼 | 關係名稱 | 說明 |
+|--------|---------|------|
+| **R01** | 親屬關係 (Kinship) | 血親、姻親 |
+| **R01 01/02** | . 父母/子女 | 血親關係 |
+| **R01 02/02** | . 配偶 | 姻親關係 |
+| **R02** | 社交關係 (Social) | 朋友、同事、師生 |
+| **R02 01/04** | . 摯友 | 深度友誼 |
+| **R02 02/04** | . 上下屬關係 | 職場關係 |
+| **R03** | 專業關係 (Professional) | 導演/演員、製片/演員、經紀人/藝人 |
+| **R04** | 創作關係 (Creative) | 作者/角色、原型人物/虛構角色 |
+
+### 2.4 多重分類
+
+一個 Identity 可擁有多個分類碼：
+
+**範例：劉德華**
+| 分類碼 | 分類名稱 | 主要/次要 |
+|--------|---------|----------|
+| `A61B 17/02` | 電影演員 | 主要 |
+| `B61A 17/04` | 電影主角 | 次要 |
+
+**範例：Hello Kitty**
+| 分類碼 | 分類名稱 | 主要/次要 |
+|--------|---------|----------|
+| `D01A 13/02` | 商業吉祥物 | 主要 |
+| `B61A 17/10` | 動漫角色 | 次要 |
+
+---
+
+## 3. API 路由設計
+
+### 3.1 全域身份管理 (`/api/v1/identities`)
+
+| 方法 | 路徑 | 說明 |
+|------|------|------|
+| GET | `/api/v1/identities` | 全域查找身份（搜尋名稱、別名、類型） |
+| GET | `/api/v1/identities/:id` | 獲取身份詳情（包含所有特徵群集、出現檔案軌跡） |
+| GET | `/api/v1/identities/:id/files` | 查找該身份出現過的所有檔案（跨類型） |
+| GET | `/api/v1/identities/:id/relationships` | 獲取該身份的社會關係網絡 |
+| POST | `/api/v1/identities` | 建立新身份 |
+| PATCH | `/api/v1/identities/:id` | 更新身份資訊（名稱、類型、描述、別名） |
+| DELETE | `/api/v1/identities/:id` | 刪除身份 |
+
+### 3.2 檔案層級身份槽位 (`/api/v1/files/{file_uuid}/identities`)
+
+| 方法 | 路徑 | 說明 |
+|------|------|------|
+| GET | `/api/v1/files/{file_uuid}` | 獲取檔案詳情與元數據 |
+| GET | `/api/v1/files/{file_uuid}/identities` | 列出此檔案中所有出現的身份 |
+| GET | `/api/v1/files/{file_uuid}/identities/:id` | 獲取該身份在此檔案中的詳細資訊 |
+| POST | `/api/v1/files/{file_uuid}/identities/:id/bind` | 綁定訊號（Face/Speaker/Text）到身份 |
+| DELETE | `/api/v1/files/{file_uuid}/identities/:id` | 移除檔案中的身份關聯 |
+
+### 3.3 檔案管理 (`/api/v1/files`)
+
+| 方法 | 路徑 | 說明 |
+|------|------|------|
+| GET | `/api/v1/files` | 列出所有檔案（支援類型篩選） |
+| POST | `/api/v1/files/register` | 註冊新檔案 |
+| GET | `/api/v1/files/{file_uuid}` | 獲取檔案詳情 |
+| PATCH | `/api/v1/files/{file_uuid}` | 更新檔案元數據 |
+
+### 3.4 分類辭典 API
+
+| 方法 | 路徑 | 說明 |
+|------|------|------|
+| GET | `/api/v1/classifications/ipc` | 獲取 IPC 分類辭典 |
+| GET | `/api/v1/classifications/ipc/{ipc_code}/children` | 獲取子分類 |
+| GET | `/api/v1/identities?ipc_code=A61B 17/02` | 按分類碼查找身份 |
+| GET | `/api/v1/identities?ipc_code=A61B 17&include_children=true` | 包含子分類查找 |
+
+---
+
+## 4. API 回應結構範例
+
+### 4.1 全域身份詳情
+```
+GET /api/v1/identities/101
+```
+
+```json
+{
+  "success": true,
+  "data": {
+    "identities_id": 101,
+    "name": "劉德華",
+    "type": "person",
+    "aliases": ["Andy Lau", "華仔"],
+    "ipc_classifications": [
+      {
+        "ipc_code": "A61B 17/02",
+        "title": "電影演員",
+        "is_primary": true,
+        "confidence": 0.95,
+        "assigned_by": "manual"
+      }
+    ],
+    "files": [
+      {
+        "file_uuid": "abc123",
+        "file_type": "video",
+        "file_name": "無間道.mp4",
+        "role_name": "劉建明",
+        "appearance_count": 45,
+        "faces": [
+          {
+            "face_id": "face_001",
+            "description": "古裝造型",
+            "thumbnail_url": "..."
+          },
+          {
+            "face_id": "face_002",
+            "description": "現代造型",
+            "thumbnail_url": "..."
+          }
+        ]
+      }
+    ],
+    "relationships": [
+      {
+        "target_id": 202,
+        "target_name": "朱麗倩",
+        "ipc_code": "R01 02/02",
+        "title": "配偶",
+        "description": "妻子",
+        "is_bidirectional": true,
+        "metadata": { "marriage_year": 2008 }
+      }
+    ]
+  }
+}
+```
+
+### 4.2 檔案內身份列表
+```
+GET /api/v1/files/{file_uuid}/identities
+```
+
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "identities_id": 101,
+      "name": "劉德華",
+      "role_name": "劉建明",
+      "type": "person",
+      "appearance_count": 45,
+      "total_duration": 3600,
+      "thumbnail_url": "..."
+    }
+  ]
+}
+```
+
+---
+
+## 5. 資料庫設計
+
+### 5.1 核心表格
+
+#### `identities` (全域身份表)
+```sql
+CREATE TABLE identities (
+    identities_id SERIAL PRIMARY KEY,
+    name VARCHAR(255) NOT NULL,
+    type VARCHAR(50),
+    aliases JSONB,
+    metadata JSONB,
+    created_at TIMESTAMPTZ DEFAULT NOW(),
+    updated_at TIMESTAMPTZ DEFAULT NOW()
+);
+```
+
+#### `ipc_taxonomy` (IPC 分類辭典表)
+```sql
+CREATE TABLE ipc_taxonomy (
+    ipc_code VARCHAR(20) PRIMARY KEY,
+    parent_code VARCHAR(20),
+    section CHAR(1),
+    class VARCHAR(3),
+    subclass CHAR(1),
+    main_group VARCHAR(10),
+    subgroup VARCHAR(10),
+    indent_level INTEGER,
+    title_en VARCHAR(255),
+    title_zh VARCHAR(255),
+    definition TEXT,
+    is_active BOOLEAN DEFAULT TRUE,
+    created_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+CREATE INDEX idx_ipc_parent ON ipc_taxonomy(parent_code);
+CREATE INDEX idx_ipc_section ON ipc_taxonomy(section);
+```
+
+#### `identity_ipc_classifications` (身份-IPC 關聯表)
+```sql
+CREATE TABLE identity_ipc_classifications (
+    identities_id INTEGER REFERENCES identities(identities_id),
+    ipc_code VARCHAR(20) REFERENCES ipc_taxonomy(ipc_code),
+    is_primary BOOLEAN DEFAULT FALSE,
+    confidence NUMERIC(3,2),
+    assigned_by VARCHAR(50),
+    metadata JSONB,
+    created_at TIMESTAMPTZ DEFAULT NOW(),
+    PRIMARY KEY (identities_id, ipc_code)
+);
+```
+
+#### `identity_relationships` (關係圖譜表)
+```sql
+CREATE TABLE identity_relationships (
+    relationship_id BIGSERIAL PRIMARY KEY,
+    source_id INTEGER REFERENCES identities(identities_id),
+    target_id INTEGER REFERENCES identities(identities_id),
+    ipc_code VARCHAR(20) REFERENCES ipc_taxonomy(ipc_code),
+    description TEXT,
+    context_file_uuid VARCHAR(64),
+    confidence NUMERIC(3,2),
+    is_bidirectional BOOLEAN DEFAULT FALSE,
+    start_date DATE,
+    end_date DATE,
+    metadata JSONB,
+    created_at TIMESTAMPTZ DEFAULT NOW(),
+    UNIQUE(source_id, target_id, ipc_code)
+);
+
+CREATE INDEX idx_rel_source ON identity_relationships(source_id);
+CREATE INDEX idx_rel_target ON identity_relationships(target_id);
+CREATE INDEX idx_rel_ipc ON identity_relationships(ipc_code);
+```
+
+#### `file_registry` (檔案註冊表)
+```sql
+CREATE TABLE file_registry (
+    file_uuid VARCHAR(64) PRIMARY KEY,
+    file_path TEXT NOT NULL,
+    file_type VARCHAR(50),
+    mime_type VARCHAR(100),
+    file_size BIGINT,
+    duration_seconds NUMERIC,
+    metadata JSONB,
+    created_at TIMESTAMPTZ DEFAULT NOW()
+);
+```
+
+#### `face_identities` (檔案層級定妝表)
+```sql
+CREATE TABLE face_identities (
+    face_id VARCHAR(64) PRIMARY KEY,
+    file_uuid VARCHAR(64) REFERENCES file_registry(file_uuid),
+    identities_id INTEGER REFERENCES identities(identities_id),
+    embedding VECTOR(512),
+    description TEXT,
+    thumbnail_path TEXT,
+    cluster_metadata JSONB,
+    created_at TIMESTAMPTZ DEFAULT NOW()
+);
+```
+
+#### `file_identities` (檔案-身份關聯槽位表)
+```sql
+CREATE TABLE file_identities (
+    file_uuid VARCHAR(64) REFERENCES file_registry(file_uuid),
+    identities_id INTEGER REFERENCES identities(identities_id),
+    role_name VARCHAR(255),
+    appearance_count INTEGER DEFAULT 0,
+    total_duration_seconds NUMERIC,
+    first_appearance NUMERIC,
+    last_appearance NUMERIC,
+    metadata JSONB,
+    PRIMARY KEY (file_uuid, identities_id),
+    created_at TIMESTAMPTZ DEFAULT NOW(),
+    updated_at TIMESTAMPTZ DEFAULT NOW()
+);
+```
+
+---
+
+## 6. 關係圖
+
+```
+identities (全域身份表)
+├── identities_id (PK)
+├── name
+├── type
+├── aliases
+└── metadata
+
+ipc_taxonomy (分類辭典表)
+├── ipc_code (PK)
+├── parent_code (FK → code)
+├── title_en/zh
+├── indent_level
+└── is_active
+
+identity_ipc_classifications (身份-IPC 關聯表)
+├── identities_id (FK → identities)
+├── ipc_code (FK → taxonomy)
+├── is_primary
+└── metadata
+
+identity_relationships (關係圖譜表)
+├── relationship_id (PK)
+├── source_id (FK → identities)
+├── target_id (FK → identities)
+├── ipc_code (FK → taxonomy)
+├── is_bidirectional
+└── metadata
+
+file_registry (檔案表)
+├── file_uuid (PK)
+├── file_type
+└── metadata
+
+face_identities (檔案層級定妝表)
+├── face_id (PK)
+├── file_uuid (FK → file_registry)
+├── identities_id (FK → identities)
+├── embedding
+└── thumbnail_path
+
+file_identities (檔案-身份槽位表)
+├── file_uuid (FK)
+├── identities_id (FK)
+├── role_name
+└── metadata
+```
+
+---
+
+## 7. 應用場景
+
+### 7.1 電影角色關係圖
+當用戶觀看《無間道》時，系統可呈現：
+- 劉德華 (角色：劉建明) → 曾志偉 (角色：韓琛)：`R02 04/00` (敵人/競爭對手)
+- 劉德華 (角色：劉建明) → 陳慧琳 (角色：心理醫生)：`R02 03/00` (醫患關係)
+
+### 7.2 演員現實關係
+- 劉德華 → 朱麗倩：`R01 02/02` (配偶)
+- 周星馳 → 吳孟達：`R02 01/04` (摯友) + `R03 01/02` (長期合作演員)
+
+### 7.3 品牌與代言人關係
+- Nike (品牌) → 劉德華 (代言人)：`R03 04/00` (品牌/代言人)
+
+---
+
+## 8. 前端影響範圍
+
+| 檔案 | 變更內容 |
+|------|---------|
+| `portal/src/api/client.ts` | API URL 路徑更新為 `/api/v1/files/...` 與 `/api/v1/identities/...` |
+| `portal/src/router.ts` | 路由路徑更新 (`/persons` → `/identities`) |
+| `portal/src/App.vue` | 導航連結與文案更新 (`人物管理` → `身份管理`) |
+| `portal/src/views/HomeView.vue` | 連結與文案更新 |
+| `portal/src/views/PersonsView.vue` | 更名為 `IdentitiesView.vue` 或整合 |
+| `portal/src/components/PersonThumbnail.vue` | 更名為 `IdentityThumbnail.vue` |
+
+### UI 文案變更
+
+| 舊文案 | 新文案 |
+|--------|--------|
+| 人物管理 | 身份管理 |
+| Person | Identity |
+| 人物 | 身份/實體 |
+
+---
+
+## 9. 待評估項目
+
+1. **IPC 編碼格式**：空格分隔 (`A61B 17/02`) 還是緊湊格式 (`A61B17/02`)？
+2. **部的數量**：目前設計 A-H + R 共 9 個部，是否需要增減？
+3. **分類深度**：IPC 通常支援到 3-4 層分組，系統是否需要限制最大深度？
+4. **自訂擴展**：是否允許用戶在標準 IPC 之外新增自訂分類碼？
+5. **關係時間軸**：是否需要記錄關係的開始/結束時間？
+6. **關係方向性**：除 `is_bidirectional` 外，是否需要支援更複雜的關係方向表達？
+
+---
+
+## 相關文件
+
+| 文件 | 說明 |
+|------|------|
+| `ARCHITECTURE_OVERVIEW.md` | 架構總覽 |
+| `PROCESSING_PIPELINE.md` | 處理流程 |
+| `DESIGN_IMPLEMENTATION_GAP.md` | 設計與實現差異分析 |

docs_v1.0/ARCHITECTURE/_deprecated/SPEAKER_INTEGRATION.md

@@ -0,0 +1,195 @@
+---
+document_type: "architecture_design"
+service: "MOMENTRY_CORE"
+title: "Momentry Core 語音特徵與人物識別整合架構 (Speaker-AudioVisual Integration) (v1.0)"
+date: "2026-04-21"
+version: "V1.0"
+status: "deprecated"
+owner: "Warren"
+created_by: "OpenCode"
+tags:
+  - "deprecated"
+  - "momentry"
+  - "core"
+  - "語音特徵與人物識別整合架構"
+ai_query_hints:
+  - "查詢 Momentry Core 語音特徵與人物識別整合架構 (Speaker-AudioVisual Integration) (v1.0) 的內容"
+  - "Momentry Core 語音特徵與人物識別整合架構 (Speaker-AudioVisual Integration) (v1.0) 的主要目的是什麼？"
+  - "如何操作或實施 Momentry Core 語音特徵與人物識別整合架構 (Speaker-AudioVisual Integration) (v1.0)？"
+---
+
+> [!WARNING] **檔案已過時 (Deprecated)**
+> 
+> **原因**: 此文件依賴舊版 `global_person_identities` 和 `person_identities` 表結構。新的 `FILE_IDENTITY_API_DESIGN.md` 已將聲紋、臉部等所有特徵統一歸納至 `identities` 表中，不再區分全域/本地人物表。
+> 
+> **狀態**: 僅供歷史參考，不應用於新功能的開發。
+> 
+> **搬移日期**: 2026-04-25
+
+# Momentry Core 語音特徵與人物識別整合架構 (Speaker-AudioVisual Integration) (v1.0)
+
+| 項目 | 內容 |
+|------|------|
+| 建立者 | OpenCode |
+| 建立時間 | 2026-04-21 |
+| 文件版本 | V1.0 |
+
+---
+
+## 版本歷史
+
+| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
+|------|------|------|--------|-----------|
+| V1.0 | 2026-04-21 | 定義語音特徵 (Speaker Diarization & Embedding) 與視覺識別的融合邏輯 | OpenCode | OpenCode / Qwen3.6-Plus |
+
+---
+
+## 0. 設計目標
+
+單純依賴臉部識別 (Face Recognition) 在側臉、遮擋、遠景或黑暗環境下容易失敗。**語音特徵整合** 提供了強大的互補邏輯，透過「誰在說話」與「誰在畫面中」的時空關聯，實現 **多模態人物身分決議 (Multimodal Person Identity Resolution)**。
+
+- **核心目標**: 利用 ASRX (說話者日誌化) 產出的時間軸與聲紋特徵，自動綁定臉部聚類 (Face Clusters)。
+- **資料豐富**: 建立 `voice_print` (語音特徵向量) 與 `speaker_id` 關聯，支援跨影片聲音重識別 (Speaker Re-Identification)。
+- **魯棒性**: 當臉部識別置信度低時，以語音時間重疊率 (Temporal Overlap) 作為主要判斷依據。
+
+---
+
+## 1. 核心關聯邏輯 (Association Logic)
+
+系統採用 **「時空共現 (Spatio-Temporal Co-occurrence)」 + 「特徵交叉驗證 (Cross-Modal Verification)」** 雙重機制。
+
+### 1.1 時空共現原理
+在大多數影視內容中，當一個人說話時，鏡頭通常會聚焦於該人。
+- **假設**: 若 `SPEAKER_00` 說話的 80% 時間內，`FACE_01` 都出現在畫面中心，則 `SPEAKER_00` 與 `FACE_01` 極可能為同一人。
+
+### 1.2 語音特徵向量 (Speaker Embedding)
+ASRX 處理時，同時提取每個 `speaker_id` 的 **ECAPA-TDNN x-vector** (通常為 192 或 256 維)。
+- **用途**: 用於跨影片聲音比對 (例如：同一配音員在不同影片中出現)。
+- **儲存**: 寫入 `global_person_identities.voice_print`。
+
+---
+
+## 2. 資料庫結構擴展 (Schema Extension)
+
+為支援語音整合，需對全域人物表與本地關聯表進行欄位擴展。
+
+### 2.1 全域人物身分表 (`global_person_identities`)
+```sql
+ALTER TABLE global_person_identities 
+ADD COLUMN voice_print vector(256),      -- 聲紋特徵向量 (ECAPA-TDNN)
+ADD COLUMN primary_speaker_id VARCHAR(50), -- 主要關聯的 Speaker ID
+ADD COLUMN match_strategy VARCHAR(30);   -- 'tmdb_face', 'audio_visual_overlap', 'manual'
+```
+
+### 2.2 本地人物出現表 (`person_identities`)
+```sql
+ALTER TABLE person_identities 
+ADD COLUMN speaker_id VARCHAR(50),        -- 關聯的 ASRX Speaker ID
+ADD COLUMN temporal_overlap_score FLOAT,  -- 時間重疊率 (0.0 - 1.0)
+ADD COLUMN audio_visual_confidence FLOAT; -- 融合置信度
+```
+
+---
+
+## 3. 時空對齊演算法 (Temporal Alignment Algorithm)
+
+系統如何精確計算「說話者」與「臉部」的關聯？
+
+### 3.1 演算法步驟
+1.  **時間切片**: 將影片以 `1秒` 為單位劃分時間窗。
+2.  **標籤映射**: 
+    - 若該秒有 ASRX 輸出，標記為 `ActiveSpeaker = SPEAKER_XX`。
+    - 若該秒 Face Processor 偵測到臉部，標記為 `ActiveFace = FACE_YY` (取信心值最高且面積最大者)。
+3.  **共現矩陣 (Co-occurrence Matrix)**: 統計每對 `(SPEAKER_XX, FACE_YY)` 同時出現的秒數。
+4.  **計算重疊率**:
+   ```math
+   Overlap(S_x, F_y) = \frac{\text{Count}(S_x \cap F_y)}{\text{Count}(S_x)}
+   ```
+5.  **決策**:
+   - 若 `Overlap > 0.60` → 建立強關聯 (High Confidence)。
+   - 若 `0.30 <= Overlap <= 0.60` → 建立建議關聯 (Medium Confidence)。
+   - 若 `Overlap < 0.30` → 忽略 (可能是畫外音或群體場景)。
+
+### 3.2 偽代碼範例
+```python
+# 輸入: speaker_timeline, face_timeline
+co_occurrence = defaultdict(int)
+speaker_duration = defaultdict(int)
+
+for sec in range(total_seconds):
+    if speaker_timeline[sec]:
+        s_id = speaker_timeline[sec]
+        speaker_duration[s_id] += 1
+        if face_timeline[sec]:
+            f_id = face_timeline[sec] # 取最大臉
+            co_occurrence[(s_id, f_id)] += 1
+
+# 計算關聯強度
+for (s_id, f_id), overlap_count in co_occurrence.items():
+    score = overlap_count / speaker_duration[s_id]
+    if score > 0.6:
+        link_speaker_to_face(s_id, f_id, score)
+```
+
+---
+
+## 4. 融合識別流程 (Integration Pipeline)
+
+此流程與 TMDB 臉部比對並行執行，最終匯入同一個 `Global Identity Resolver`。
+
+```mermaid
+graph TD
+    A[ASRX Processor] -->|Speaker IDs + x-vectors| B(Speaker-Face Aligner)
+    C[Face Processor] -->|Face Clusters + BBoxes| B
+    D[TMDB Service] -->|Actor Names + Photos| E[Identity Resolver]
+    
+    B -->|Audio-Visual Pairs| E
+    E -->|Merge & Deduplicate| F[(Global Person DB)]
+    F -->|Enrich Chunks| G[Rule 3/4 Chunking]
+```
+
+### 4.1 執行時機
+1.  `ASRX` 與 `Face` 處理器均完成。
+2.  觸發 `audio_visual_binding_worker`。
+3.  產出 `speaker_face_mapping.json`。
+4.  寫入資料庫，並更新 `person_identities` 表。
+
+---
+
+## 5. 衝突處理與置信度評分 (Conflict & Confidence)
+
+### 5.1 常見衝突情境
+| 情境 | 現象 | 處理策略 |
+|:---|:---|:---|
+| **畫外音 (Voice-Over)** | Speaker 出現時間長，但對應 Face 為空或 constantly changing | 降低權重，標記為 `narration`，不強制綁定單一 Face |
+| **多人對話重疊** | 畫面有 3 張臉，但只有 1 個 Speaker | 優先綁定畫面中心/最大臉，其餘標記為 `audience/background` |
+| **TMDB 與 Speaker 衝突** | TMDB 匹配為 A，但 Speaker 重疊指向 B | 以 **高置信度 Speaker 重疊** 為優先 (因為是動態實測)，TMDB 降為候補參考 |
+
+### 5.2 融合置信度計算
+```math
+FinalConfidence = (W_{face} \times FaceScore) + (W_{voice} \times OverlapScore) + (W_{tmdb} \times TMDBScore)
+```
+預設權重：`Face: 0.4`, `Voice: 0.4`, `TMDB: 0.2` (可依影片類型動態調整)。
+
+---
+
+## 6. 與 TMDB 的協同效應 (Synergy)
+
+| 維度 | TMDB 整合 | 語音特徵整合 | 綜合效益 |
+|:---|:---|:---|:---|
+| **資料來源** | 外部資料庫 (靜態) | 影片內容本身 (動態) | 靜態+動態互補 |
+| **解決問題** | "這部片有誰？" | "現在說話的是誰？" | 精準定位時間軸 |
+| **失敗情境** | 電影元資料錯誤/小眾片 | 畫外音/環境音干擾 | 一方失敗時另一方補位 |
+| **輸出結果** | 演員名單與照片 | 說話者時間軸與聲紋 | 完整多模態人物畫像 |
+
+---
+
+## 7. 總結
+
+引入 **Speaker 特徵整合** 後，Momentry Core 的人物識別從「單點視覺比對」升級為 **「聽視覺時空融合」**。
+
+- **召回率提升**: 解決側臉、背光、遠景下的臉部識別失敗問題。
+- **時間軸精準**: 不僅知道「誰在片中」，更知道「誰在何時說了什麼」。
+- **聲紋累積**: 跨影片建立 `voice_print` 庫，未來可實現「聽聲辨人」的檢索能力。
+
+此架構確保了人物資料的完整性與高可用性，為後續的 Chunk Rule 3/4 (場景與劇情分析) 提供了堅實的實體基礎。

docs_v1.0/ARCHITECTURE/_deprecated/TMDB_CHARACTER_INTEGRATION.md

@@ -0,0 +1,212 @@
+---
+document_type: "architecture_design"
+service: "MOMENTRY_CORE"
+title: "Momentry Core TMDB 人物識別整合架構 (TMDB Character Integration) (v1.0)"
+date: "2026-04-21"
+version: "V1.0"
+status: "deprecated"
+owner: "Warren"
+created_by: "OpenCode"
+tags:
+  - "deprecated"
+  - "character"
+  - "tmdb"
+  - "momentry"
+  - "core"
+ai_query_hints:
+  - "查詢 Momentry Core TMDB 人物識別整合架構 (TMDB Character Integration) (v1.0) 的內容"
+  - "Momentry Core TMDB 人物識別整合架構 (TMDB Character Integration) (v1.0) 的主要目的是什麼？"
+  - "如何操作或實施 Momentry Core TMDB 人物識別整合架構 (TMDB Character Integration) (v1.0)？"
+---
+
+> [!WARNING] **檔案已過時 (Deprecated)**
+> 
+> **原因**: 此文件定義了舊版 `person_identities` 和 `global_person_identities` 表結構。新的架構設計已採用 `identities` (全域實體) 和 `file_identities` (出現紀錄) 的通用模型，詳見 `FILE_IDENTITY_API_DESIGN.md`。
+> 
+> **狀態**: 僅供歷史參考，不應用於新功能的開發。
+> 
+> **搬移日期**: 2026-04-25
+
+# Momentry Core TMDB 人物識別整合架構 (TMDB Character Integration) (v1.0)
+
+| 項目 | 內容 |
+|------|------|
+| 建立者 | OpenCode |
+| 建立時間 | 2026-04-21 |
+| 文件版本 | V1.0 |
+
+---
+
+## 版本歷史
+
+| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
+|------|------|------|--------|-----------|
+| V1.0 | 2026-04-21 | 定義基於 TMDB API 的自動化全域人物識別與資料建檔流程 | OpenCode | OpenCode / Qwen3.6-Plus |
+
+---
+
+## 0. 設計目標
+
+本規範旨在透過整合 **TMDB (The Movie Database) API**，解決影片處理中「臉部聚類 (Face Clustering)」後無法得知真實身分的問題。
+
+- **核心目標**: 實現電影類型檔案的 **零人工干預 (Zero-Touch)** 人物識別。
+- **資料豐富**: 自動獲取 **演員本名 (Actor Name)**、**角色名 (Character Name)** 及 **大頭照 (Profile Photo)**。
+- **全域身分**: 建立跨影片的全域人物庫 (`global_person_identities`)，而非僅限於單一影片的標籤。
+
+---
+
+## 1. 整體架構流程 (Workflow)
+
+整合流程發生在影片處理管線的 **「臉部處理 (Face Processing)」** 階段之後，**「內容聚合 (Chunking)」** 階段之前。
+
+```mermaid
+graph LR
+    A[影片資產] -->|Metadata (Title/Year)| B(TMDB Query Service)
+    B -->|Cast List + Photos| C[Cast Local DB]
+    D[Face Processor] -->|Face Clusters + Embeddings| E(Face Matcher)
+    C -->|Actor Profile Embeddings| E
+    E -->|Match Result| F[Identity Resolver]
+    F -->|Create/Update| G[(Global Person Identity)]
+    G -->|Link| H[Local Person Appearance]
+```
+
+### 1.1 關鍵步驟
+1.  **Metadata 解析**: 從檔名或 `ffprobe` 資訊中提取電影名稱與年份。
+2.  **TMDB 查詢**: 呼叫 API 獲取 Top Cast (通常前 10-15 名) 及其照片 URL。
+3.  **照片下載與特徵提取**: 下載演員照片並生成 Face Embedding (512-dim)。
+4.  **向量比對**: 將演員照片向量與影片內偵測到的 **Face Cluster Centroids** 進行相似度比對 (Cosine Similarity)。
+5.  **身分決議**: 若相似度超過閾值 (如 0.6)，則自動建立全域身分並標記。
+
+---
+
+## 2. 資料結構設計 (Schema Design)
+
+為了支持此流程，需擴展資料庫以儲存外部資料來源與比對結果。
+
+### 2.1 全域人物身分表 (Global Person Identities)
+
+此表用於存放已確認的真實演員資料，跨影片共享。
+
+```sql
+CREATE TABLE global_person_identities (
+    id UUID PRIMARY KEY,
+    tmdb_id INT,                        -- TMDB Actor ID (唯一索引)
+    name VARCHAR(255) NOT NULL,         -- 演員姓名 (e.g., "Cary Grant")
+    profile_path VARCHAR(255),          -- 照片路徑 (本地或 URL)
+    embedding vector(512),              -- 照片的人臉特徵向量
+    source VARCHAR(20) DEFAULT 'tmdb',  -- 來源標記
+    created_at TIMESTAMPTZ DEFAULT NOW(),
+    
+    UNIQUE(tmdb_id)
+);
+```
+
+### 2.2 本地人物出現紀錄 (Local Person Appearances)
+
+此表記錄特定人物在特定影片中的具體表現 (角色名)。
+
+```sql
+CREATE TABLE person_identities (
+    id UUID PRIMARY KEY,
+    asset_uuid UUID NOT NULL,           -- 所屬影片
+    global_person_id UUID REFERENCES global_person_identities(id), -- 關聯全域身分
+    
+    character_name VARCHAR(255),        -- 角色名 (e.g., "Peter Joshua")
+    face_cluster_id VARCHAR(50),        -- 對應的臉部聚類 ID
+    match_score FLOAT,                  -- 匹配信心度 (0.0 - 1.0)
+    
+    appearance_count INT DEFAULT 0,     -- 出現次數
+    created_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+CREATE INDEX idx_person_asset ON person_identities(asset_uuid);
+CREATE INDEX idx_person_global ON person_identities(global_person_id);
+```
+
+---
+
+## 3. 處理邏輯細節 (Implementation Details)
+
+### 3.1 TMDB 服務註冊 (Service Registry)
+
+根據 `SERVICE_REGISTRY_ARCHITECTURE.md`，TMDB 服務定義如下：
+
+```json
+{
+  "name": "tmdb-cast-api",
+  "type": "external_api",
+  "endpoint": "https://api.themoviedb.org/3",
+  "metadata": {
+    "api_key_env": "TMDB_API_KEY",
+    "language": "zh-TW",
+    "image_base_url": "https://image.tmdb.org/t/p/w185"
+  }
+}
+```
+
+### 3.2 臉部比對策略 (Face Matching Strategy)
+
+系統如何決定「畫面中的臉」就是「Cary Grant」？
+
+1.  **參考集準備 (Reference Set)**:
+    *   從 TMDB 獲取演員照片 URL。
+    *   下載並使用 InsightFace 提取向量 $V_{actor}$。
+2.  **目標集 (Target Set)**:
+    *   從影片 Face Processor 獲取每個 Cluster 的中心向量 $V_{cluster}$。
+3.  **計算相似度**:
+    *   $Score = 1 - \text{CosineDistance}(V_{actor}, V_{cluster})$
+4.  **決策閾值**:
+    *   **High Confidence (> 0.70)**: 自動確認身分 (Auto-Confirm)。
+    *   **Medium Confidence (0.55 - 0.70)**: 標記為 "Suggestion" (建議)，需人工確認。
+    *   **Low Confidence (< 0.55)**: 忽略，保持為 "Unknown Cluster"。
+
+### 3.3 角色名關聯 (Role Mapping)
+
+TMDB 返回的結構包含 `character` 字段：
+```json
+{
+  "id": 389, // Actor ID
+  "name": "Cary Grant",
+  "character": "Peter Joshua", // 角色名
+  "profile_path": "/path/to/image.jpg"
+}
+```
+當比對成功時，系統將 **"Peter Joshua"** 寫入 `person_identities.character_name`，並將 **"Cary Grant"** 寫入 `global_person_identities.name`。
+
+---
+
+## 4. 自動化流程腳本 (Automation Pipeline)
+
+此流程被打包為一個獨立的 **Post-Face-Processing Job**。
+
+1.  **Trigger**: `face_processor` 完成，產生 `face_clusters`。
+2.  **Action**: 系統檢查 `asset_type == 'movie'` 且 `title` 存在。
+3.  **Execution**: 執行 `tmdb_cast_ingestion.py`。
+    *   查詢 TMDB。
+    *   下載圖片 -> 計算向量 -> 存入 `global_person_identities` (若不存在)。
+    *   執行比對 -> 更新 `person_identities`。
+4.  **Output**: 資料庫中充滿了真實姓名與角色名的紀錄，供 Rule 3/4 Chunking 使用。
+
+---
+
+## 5. 容錯與異常處理 (Error Handling)
+
+-   **找不到電影**: 若檔名模糊導致 TMDB 無結果，則跳過此步驟，保留原始 Face Cluster ID。
+-   **無演員照片**: 若某演員在 TMDB 無照片，無法進行向量比對，僅記錄名字 (若 ASR 有提及)。
+-   **多人飾演一角**: 若臉部特徵同時匹配多個演員 (極罕見)，取 Confidence 最高者，其餘列入候補。
+
+---
+
+## 6. 總結
+
+透過引入 **TMDB API**，Momentry Core 將具備**好萊塢級別的自動標記能力**。
+
+| 特性 | 實作方式 |
+|------|----------|
+| **資料來源** | TMDB API (Cast Endpoint) |
+| **識別方式** | Face Embedding Similarity (Vector Match) |
+| **儲存活用** | 建立 `global_person_identities` 實現跨片共享 |
+| **元數據豐富** | 同時獲取演員名、角色名、大頭照 |
+| **自動化** | 處理管線自動觸發，無需人工介入 |
+
+此機制確保了用戶在搜尋 "Cary Grant" 或 "Peter Joshua" 時，系統都能精確返回對應的影片片段。