---
document_type: "architecture_design"
service: "MOMENTRY_CORE"
title: "視覺分片設計文檔 (Phase 2.1)"
date: "2026-04-25"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
  - "視覺分片設計文檔"
ai_query_hints:
  - "查詢 視覺分片設計文檔 (Phase 2.1) 的內容"
  - "視覺分片設計文檔 (Phase 2.1) 的主要目的是什麼？"
  - "如何操作或實施 視覺分片設計文檔 (Phase 2.1)？"
---

# 視覺分片設計文檔 (Phase 2.1)

## 概述

視覺分片（Visual Chunk）是 Momentry Core 中基於 YOLO 物件檢測結果的視頻分片。它通過分析連續幀中的物件組成來創建有意義的視覺段落。

## 設計原則

1. **以實際實現為準**：當設計與代碼出現矛盾時，以實際的 Rust 代碼實現為最高權威
2. **漸進式開發**：先實現核心功能，後續逐步完善
3. **向後兼容**：不破壞現有系統的穩定性

## 數據結構

### 現有 Chunk 結構體
```rust
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Chunk {
    pub file_id: i32,
    pub uuid: String,
    pub chunk_id: String,
    pub chunk_index: u32,
    pub chunk_type: ChunkType,
    pub rule: ChunkRule,
    pub fps: f64,
    pub start_frame: i64,
    pub end_frame: i64,
    pub text_content: Option<String>,
    pub content: serde_json::Value,  // 存儲序列化的分片內容
    pub metadata: Option<serde_json::Value>,
    pub vector_id: Option<String>,
    pub frame_count: i32,
    pub pre_chunk_ids: Vec<i32>,
    pub parent_chunk_id: Option<String>,
    pub child_chunk_ids: Vec<String>,
    pub visual_stats: Option<serde_json::Value>,
}
```

### 新增 ChunkType::Visual
```rust
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq)]
#[serde(rename_all = "snake_case")]
pub enum ChunkType {
    TimeBased,
    Sentence,
    Cut,
    Trace,
    Story,
    Visual,  // 新增：視覺分片類型
}
```

### VisualChunkContent 結構體
```rust
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct VisualChunkContent {
    pub start_time: f64,
    pub end_time: f64,
    pub keyframe_objects: Vec<KeyframeObjects>,
    pub dominant_objects: Vec<String>,
    pub object_relationships: Vec<(String, String, String)>, // (object1, relationship, object2)
    pub scene_description: Option<String>,
    pub metadata: VisualMetadata,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct VisualMetadata {
    pub object_count: u32,
    pub unique_classes: Vec<String>,
    pub max_confidence: f32,
    pub avg_confidence: f32,
    pub spatial_density: f32, // objects per frame
}
```

## 功能設計

### 1. YOLO 結果轉換
- 從 `YoloResult` 轉換為 `VisualChunkContent`
- 支持幀範圍過濾
- 自動計算元數據

### 2. 分片生成策略
- **固定間隔**：每 N 幀創建一個分片
- **物件相似性**：基於幀間物件相似度進行分組
- **場景變化**：檢測場景變化點（需集成 CUT 算法）

### 3. 關係檢測
- **空間關係**：near, far, left, right, above, below
- **時間關係**：appear, disappear, move
- **語義關係**：人與物互動關係

## 集成方案

### 階段 1：概念驗證
1. 擴展 `ChunkType` 枚舉，添加 `Visual` 變體
2. 創建 `VisualChunkContent` 數據結構
3. 實現從 YOLO 結果到視覺分片的轉換邏輯

### 階段 2：處理管道集成
1. 擴展現有 YOLO 處理器，支持視覺分片生成
2. 集成到處理作業流程
3. 存儲到數據庫

### 階段 3：查詢優化
1. 構建視覺分片索引
2. 支持基於物件的視頻搜索
3. 集成到現有搜索 API

## 與現有系統的關係

### 現有分片類型
- **Sentence**：基於語音轉文字的分片（Rule 1）
- **Cut**：基於場景變化的分片（Rule 3）
- **Story**：基於敘事分析的分片（Rule 4）
- **Visual**：基於視覺物件的分片（Rule 2） - 本次實現

### 數據流
```
YOLO Processor
    ↓
YoloResult
    ↓
VisualChunkContent (本次新增)
    ↓
Chunk (chunk_type = Visual)
    ↓
Database Storage
    ↓
Search Index
```

## 測試策略

### 單元測試
1. `VisualChunkContent` 序列化/反序列化
2. 幀相似度計算
3. 從 YOLO 結果創建分片

### 集成測試
1. YOLO 處理器集成
2. 數據庫存儲
3. 搜索功能

## 已知問題與挑戰

### 問題 1：設計與實現不一致
- **現狀**：設計文檔中的 chunk_type 值與實際 Rust 代碼存在不匹配
- **解決方案**：以實際代碼為準，更新設計文檔

### 問題 2：YOLO 輸出格式複雜
- **現狀**：Python 腳本輸出與 Rust 結構體需要適配
- **解決方案**：使用 `YoloPythonResult` 適配器模式

### 問題 3：性能考慮
- **挑戰**：實時視覺分片生成可能消耗較多計算資源
- **優化**：批量處理、關鍵幀選擇、異步處理

## 下一步計劃

### 短期（Phase 2.1 - 已完成）
- [x] 設計視覺分片數據結構
- [x] 實現基本轉換邏輯
- [x] 創建概念驗證測試

### 中期（Phase 2.2）
- [ ] 集成到現有 YOLO 處理器
- [ ] 實現分片存儲功能
- [ ] 添加更多輔助方法

### 長期（Phase 2.3+）
- [ ] 高級關係檢測
- [ ] 智能場景描述生成
- [ ] 與其他分片類型的關聯

## 參考文檔

1. **AGENTS.md** - 項目開發規範
2. **TERMINOLOGY_MAPPING.md** - 術語對照表
3. **DESIGN_IMPLEMENTATION_GAP.md** - 設計與實現差異分析
4. **ARCHITECTURE_DECISION_EXECUTION_PLAN.md** - 執行計畫

## 版本歷史

| 版本 | 日期 | 修改內容 |
|------|------|----------|
| 1.0 | 2026-04-22 | 初始版本，Phase 2.1 設計完成 |
| 1.1 | 2026-04-22 | 添加測試策略和下一步計劃 |

---

**完成狀態**：✅ Phase 2.1 核心設計完成

**下一步**：修復現有 `types.rs` 文件的語法錯誤，然後進行 Phase 2.2 的處理器集成。
