---
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` | 設計與實現差異分析 |
