# Momentry Core 搜尋能力驗收標準 (Search Acceptance Criteria)

本文檔記錄了系統必須能夠支援的複雜搜尋場景。這些問句將作為我們開發與測試的**最高指導原則**，用於驗證每個模組的可行性與系統整合度。

> **更新日期**: 2026-04-12
> **狀態**: 草稿 (待實測驗證)

---

## 🎯 驗收維度與測試用例 (Test Cases)

### 1. 🕰️ WHEN (時間與劇情序列)
**挑戰點**: 系統需具備「劇情連貫性理解」與「相對時間/事件計數」的能力。

| 測試問句 | 所需技術/數據來源 | 當前狀態 | 備註 |
| :--- | :--- | :--- | :--- |
| **「男女主角第二次見面那段」** | `face_id` 匹配 + **Interaction Counter (同框次數統計)** | ⚠️ 待開發 | 需建立場景聚合邏輯 (Scene Grouping) |
| **「第一個壞人死後, 男女主角討論 who did it 的場景」** | **Event Timeline** (Gunshot/Death 事件) + **Contextual Search** (討論兇手) | ⚠️ 待開發 | 需結合事件偵測與對話語義分析 |
| **「被捕之前最後見的人場景」** | **Causal Reasoning** (被捕事件前的最後互動) | 🔴 高難度 | 需 LLM 深度理解劇情因果 |

### 2. 😡 EMOTION (情緒氛圍)
**挑戰點**: 從音頻能量、面部表情或對話內容推導出「氛圍」。

| 測試問句 | 所需技術/數據來源 | 當前狀態 | 備註 |
| :--- | :--- | :--- | :--- |
| **「很緊張的場景」** | Audio Energy (高能量無對話/配樂變奏) + Sentiment Analysis | ✅ 部分可用 | 需結合配樂切分與打鬥偵測 |
| **「很感動的場景」** | Music Segment (抒情樂段) + Positive Sentiment | 🔴 高難度 | 需 LLM 分析劇情語義 |
| **「很憤怒的場景」** | Conflict Detection (爭吵) + Angry Sentiment | ✅ 可用 | 已有 Argument 偵測機制 |
| **「很尷尬的場景」** | Silence/Long Pause + Awkward Sentiment | ⚠️ 待開發 | 需 LLM 辨識潛台詞 |

### 3. 🗣️ INTENT (對話意圖)
**挑戰點**: 僅靠關鍵字無法區分「質問」與「詢問」，需依賴 LLM 語義分類。

| 測試問句 | 所需技術/數據來源 | 當前狀態 | 備註 |
| :--- | :--- | :--- | :--- |
| **「在說服的場景」** | Dialogue Intent Classification (Persuasion) | 🔴 需 LLM | 需建立語義索引 (Semantic Index) |
| **「在質問的場景」** | Interrogation Keywords + Aggressive Sentiment | ✅ 可用 | 已有 Conflict/Argument 數據 |
| **「在解釋的場景」** | Dialogue Intent (Explanation) | 🔴 需 LLM | 需語義索引支援 |
| **「在談判的場景」** | Dialogue Intent (Negotiation) | 🔴 需 LLM | 需語義索引支援 |

### 4. 📦 OBJECT (視覺物件)
**挑戰點**: 依賴 YOLO 的物件辨識準確度與標籤對應。

| 測試問句 | 所需技術/數據來源 | 當前狀態 | 備註 |
| :--- | :--- | :--- | :--- |
| **「畫面有手機的場景」** | YOLO Object Detection (`cell phone`) | ✅ 可用 | 已有 YOLO JSON 數據 |
| **「畫面有車子的場景」** | YOLO Object Detection (`car`, `truck`) | ✅ 可用 | 已有 YOLO JSON 數據 |
| **「畫面有麥克風的場景」** | YOLO Object Detection (`microphone`) | ⚠️ 依賴模型 | 小物件可能遺漏 |
| **「畫面有文件的場景」** | YOLO (`book`, `paper`) + OCR (Text on Paper) | ⚠️ 混合技術 | 需結合 OCR 關鍵字 |

### 5. 🔊 AUDIO (聽覺事件)
**挑戰點**: 區分背景音與前景音。

| 測試問句 | 所需技術/數據來源 | 當前狀態 | 備註 |
| :--- | :--- | :--- | :--- |
| **「聽到背景有音樂的場景」** | Audio Taxonomy (`music`) + Segmentation | ✅ 可用 | 已有 Music Segmentation 數據 |
| **「聽到掌聲的場景」** | Audio Taxonomy (`applause`) | ✅ 可用 | AST 模型支援 |
| **「聽到爆炸聲的場景」** | Audio Energy (High) + Taxonomy (`explosion`) | ✅ 可用 | 已有 Sound Event 偵測 |
| **「聽到笑聲的場景」** | Audio Taxonomy (`laughter`) | ✅ 可用 | AST 模型支援 |

### 6. 🤝 RELATION (人物關係與互動)
**挑戰點**: 識別特定角色組合，並分析他們之間的互動模式。

| 測試問句 | 所需技術/數據來源 | 當前狀態 | 備註 |
| :--- | :--- | :--- | :--- |
| **「奧黛麗赫本和 Cary Grant 對話場景」** | Face ID 匹配 (`Person_A` + `Person_B`) + **Co-occurrence** | ✅ 可用 | 已有 Face Clustering 數據 |
| **「兩人爭論場景」** | Face Co-occurrence + Argument Detection | ✅ 可用 | 結合 Face 與 Event 表 |
| **「主持人訪問來賓場景」** | Pose/Action (Sitting vs Standing) + Dialogue Flow | 🔴 需 LLM | 需視覺構圖分析 |

### 7. 📚 CONTENT (上下文與劇情連貫性)
**挑戰點**: 這是最高難度的「推理」層面，需理解事件的前因後果。

| 測試問句 | 所需技術/數據來源 | 當前狀態 | 備註 |
| :--- | :--- | :--- | :--- |
| **「衝突之後第一次會面場景」** | **Timeline Logic** (Find Conflict -> Search Next Co-occurrence) | 🔴 高難度 | 需事件序列邏輯運算 |
| **「女主角第一次開始懷疑男主角, 之後又決定信任男主角的場景」** | **Emotional Arc Analysis** (Sentiment Transition: Neutral -> Suspicion -> Trust) | 🔴 極高難度 | 需 LLM 長程語義分析 |

---

## 🛠️ 待實作功能清單 (To-Do for Full Compliance)

為了達成上述所有標準，我們必須完成以下開發：

1. [ ] **語義索引建置 (Semantic Indexing)**: 使用 Ollama (Gemma 4) 離線分析全片對話，填入 `chunk_semantics` 表。
2. [ ] **場景聚合邏輯 (Scene Aggregation)**: 將零碎的 ASR/CUT 聚合成有意義的「場景 (Scene)」。
3. [ ] **互動計數器 (Interaction Counter)**: 統計角色同框次數，支援「第 X 次見面」查詢。
4. [ ] **事件時間軸 (Event Timeline)**: 將 Gunshot, Death, Fight 等事件結構化，支援「...之後」查詢。
5. [ ] **關係圖譜 (Relationship Graph)**: 建立角色關係網，支援「主持人/來賓」等角色定義。

---

## 🔍 視覺分片搜索 API (Visual Chunk Search)

### 可用端點

| 端點 | 方法 | 描述 |
| :--- | :--- | :--- |
| `/api/v1/search/visual` | POST | 通用視覺搜索 |
| `/api/v1/search/visual/class` | POST | 按物件類別搜索 |
| `/api/v1/search/visual/density` | POST | 按空間密度搜索 |
| `/api/v1/search/visual/stats` | POST | 獲取視覺統計 |
| `/api/v1/search/visual/combination` | POST | 按物件組合搜索 |

### API 使用範例

#### 1. 通用視覺搜索

```bash
curl -X POST http://localhost:3002/api/v1/search/visual \
  -H "Content-Type: application/json" \
  -d '{
    "uuid": "abc123",
    "criteria": {
      "min_avg_confidence": 0.8,
      "required_classes": ["person", "car"],
      "min_spatial_density": 0.5
    }
  }'
```

#### 2. 按物件類別搜索

```bash
curl -X POST http://localhost:3002/api/v1/search/visual/class \
  -H "Content-Type: application/json" \
  -d '{
    "uuid": "abc123",
    "object_class": "person",
    "min_count": 5,
    "max_count": 20
  }'
```

#### 3. 按空間密度搜索

```bash
curl -X POST http://localhost:3002/api/v1/search/visual/density \
  -H "Content-Type: application/json" \
  -d '{
    "uuid": "abc123",
    "min_density": 0.6,
    "max_density": 0.9
  }'
```

#### 4. 獲取視覺統計

```bash
curl -X POST http://localhost:3002/api/v1/search/visual/stats \
  -H "Content-Type: application/json" \
  -d '{"uuid": "abc123"}'
```

#### 5. 按物件組合搜索

```bash
curl -X POST http://localhost:3002/api/v1/search/visual/combination \
  -H "Content-Type: application/json" \
  -d '{
    "uuid": "abc123",
    "combination": [
      ["person", 5],
      ["car", 2]
    ]
  }'
```

### 使用 UniversalSearch 整合

也可以通過 `/api/v1/search` 端點使用視覺過濾器：

```bash
curl -X POST http://localhost:3002/api/v1/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "",
    "uuid": "abc123",
    "filters": {
      "min_confidence": 0.8,
      "required_object_classes": ["person"]
    }
  }'
```

### 緩存說明

視覺搜索結果會被緩存以提高性能。緩存鍵格式：`search:visual:{uuid}:{hash}`

緩存過期時間：使用與普通搜索相同的 TTL（可通過 `MOMENTRY_CACHE_TTL_SEARCH` 環境變量配置）

---

**這份文檔已建立於 `docs/SEARCH_ACCEPTANCE_CRITERIA.md`，我們將以此為目標持續推進系統開發。**
