---
document_type: "design"
service: "MOMENTRY_CORE"
title: "Class 分類系統設計 V1.0"
date: "2026-05-05"
version: "V1.0"
status: "design"
owner: "Warren"
created_by: "OpenCode"
tags:
  - "momentry"
  - "core"
  - "class"
  - "taxonomy"
  - "design"
  - "v1.0"
ai_query_hints:
  - "Class 分層分類系統設計"
  - "參照 IPC (國際專利分類) 及 HS (海關稅則)"
  - "編碼格式: {section}-{NNNN}"
  - "用於 identity 多層分類、快速定位"
related_documents:
  - "../DATA_SCHEMA_FILE_IDENTITY_V1.0.0.md"
  - "../UUID_ENCODING_RULES_V1.0.0.md"
---

# Class 分類系統設計 V1.0

> 狀態：設計階段，尚未實施

## 設計參考

IPC（國際專利分類）與 HS（海關稅則）。

共通原則：**層級碼**、**數字越長越精細**、**全球通用**、**可無限擴展**。

## 設計目標

- IPC/HS 式的 hierarchical code → **快速定位**
- Tag 式的 multi-label 使用 → **靈活分類**
- 同一 entity 可擁有多條 class path
- 新增分類只需 INSERT，無 migration

```
Cary Grant
  → P-0201 (演員/主角)
  → T-0102 (1960s)
  → S-0200 (場景/戶外 — 他在片中出現的場景)

Ferrari 250 GT
  → O-0101 (汽車)
  → B-0300 (汽車品牌/Ferrari)
  → T-0102 (1960s)

## 編碼格式

```
{section}-{NNNN}
   │      └── 4 digits，每 2 digits 一層
   └───────── 1 char section prefix
```

| 層級 | 範例 | 意義 |
|------|------|------|
| `P-0000` | top section | 人物 |
| `P-0200` | subclass | 人物 → 演員 |
| `P-0201` | group | 人物 → 演員 → 主角 |
| `P-0202` | group | 人物 → 演員 → 配角 |

層級判斷：`code.length`。`P-` = section，`P-02` = subclass，`P-0201` = group。

### Section 定義

| Section | 名稱 | 範疇 | 預留 |
|---------|------|------|------|
| `P` | 人物 | 演員、導演、公眾人物、虛構角色、運動員... | 01-99 |
| `O` | 物件 | 交通工具、家具、武器、工具、電子產品... | 01-99 |
| `B` | 品牌/組織 | 時尚、科技、汽車品牌、政府機構、NGO... | 01-99 |
| `C` | 概念/抽象 | 情感、思想、事件、主題、風格... | 01-99 |
| `A` | 生物 | 動物、植物、真菌... | 01-99 |
| `S` | 場景/地點 | 室內、戶外、城市、自然地標、建築內部... | 01-99 |
| `E` | 環境/自然 | 天氣、地形、天象、自然災害... | 01-99 |
| `M` | 音樂/聲音 | 樂器、音樂類型、自然聲音、人工聲音... | 01-99 |
| `L` | 語言/文字 | 語言、方言、書寫系統、符號... | 01-99 |
| `T` | 時間/時期 | 年代、季節、節日、歷史時期... | 01-99 |
| `F` | 檔案類型 | 影片格式、文件類型、圖片格式... | 01-99 |
| `D` | 領域/學科 | 科學、藝術、體育、政治、經濟... | 01-99 |

12 個 Section，各 99 subclass × 99 group = ~117K 分類槽位。可隨時新增 Section。

## 初始 Class Tree

```
P-0000  人物
├── P-0100  公眾人物
├── P-0200  演員
│   ├── P-0201  主角
│   └── P-0202  配角
├── P-0300  導演
├── P-0400  虛構角色
└── P-9900  其他人物

O-0000  物件
├── O-0100  交通工具
│   ├── O-0101  汽車
│   ├── O-0102  船
│   └── O-0103  飛機
├── O-0200  建築
├── O-0300  家具
└── O-9900  其他物件

B-0000  品牌
├── B-0100  時尚
├── B-0200  科技
└── B-9900  其他品牌

C-0000  概念
├── C-0100  情感
├── C-0200  思想
└── C-9900  其他概念
```

## Table

```sql
CREATE TABLE classes (
    code        VARCHAR(8) PRIMARY KEY,     -- P-0201
    name        TEXT NOT NULL,               -- 主角
    description TEXT,
    created_at  TIMESTAMPTZ DEFAULT now()
);

-- 多對多：同一 identity 可有多個 class code（如 tag 使用）
CREATE TABLE identity_classes (
    identity_id INTEGER REFERENCES identities(id),
    class_code  VARCHAR(8) REFERENCES classes(code),
    confidence  REAL DEFAULT 1.0,
    source      VARCHAR(20),                 -- which agent classified
    PRIMARY KEY (identity_id, class_code)
);
```

## Query 範例

```sql
-- 查某 identity 的所有 class
SELECT c.code, c.name
FROM identity_classes ic
JOIN classes c ON ic.class_code = c.code
WHERE ic.identity_id = 8;

-- 查所有屬於 "演員" (P-0200) 的 identity
SELECT i.name
FROM identity_classes ic
JOIN identities i ON ic.identity_id = i.id
WHERE ic.class_code LIKE 'P-02%';

-- 查某 section 下的所有 identity
SELECT DISTINCT i.name
FROM identity_classes ic
JOIN identities i ON ic.identity_id = i.id
WHERE ic.class_code LIKE 'P-%';
```

## 擴展方式

1. 新增 leaf class：`INSERT INTO classes VALUES ('P-0203', '配音員')` — P-02 底下的新 group
2. 新增 subclass：`INSERT INTO classes VALUES ('P-0500', '製作團隊')` — P 底下的新 subclass
3. 新增 section：`INSERT INTO classes VALUES ('X-0000', '新分類')` — 全新 top-level

無需 migration，insert 即可。

## 版本歷史

| 版本 | 日期 | 狀態 |
|------|------|------|
| V1.0 | 2026-05-05 | 設計階段 |

## Future: Class-Based Search

實施 class 系統後，search API 可加入 class filter 提升命中率：

```
GET /api/v1/search?q=car&class=O-0101
  → 只搜被分類為「汽車」的內容，過濾 "care", "car accident", "car wash"

GET /api/v1/search/hybrid?q=divorce&class=P-0200
  → 只搜演員說出的 "divorce"，排除旁白、字幕

GET /api/v1/search/universal?class=T-0102
  → 搜所有 1960s 相關內容
```
