---
document_type: "architecture_design"
service: "MOMENTRY_CORE"
title: "術語對照表 (Terminology Mapping)"
date: "2026-04-22"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
  - "術語對照表"
ai_query_hints:
  - "查詢 術語對照表 (Terminology Mapping) 的內容"
  - "術語對照表 (Terminology Mapping) 的主要目的是什麼？"
  - "如何操作或實施 術語對照表 (Terminology Mapping)？"
---

# 術語對照表 (Terminology Mapping)

| 項目 | 內容 |
|------|------|
| 建立者 | OpenCode |
| 建立時間 | 2026-04-22 |
| 文件版本 | V1.0 |
| 相關文件 | [DESIGN_IMPLEMENTATION_GAP.md](./DESIGN_IMPLEMENTATION_GAP.md)<br>[ARCHITECTURE_OVERVIEW.md](./ARCHITECTURE_OVERVIEW.md)<br>[CHUNKING_ARCHITECTURE.md](./CHUNKING_ARCHITECTURE.md) |

---

## 版本歷史

| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-04-22 | 創建術語對照表 | OpenCode | OpenCode / deepseek-v3.2 |

---

## 1. 核心原則

**當設計與實現出現矛盾時，以實際的 Rust 代碼實現為最高權威。**

本文檔提供設計文檔中的術語與實際 Rust 代碼實現之間的對照關係，用於：
1. 統一所有架構文檔的術語使用
2. 指導新文檔的撰寫
3. 作為代碼審查的參考標準

---

## 2. 分片類型 (Chunk Type) 對照

### 2.1 設計與實現對照表

| 設計概念 | 設計值 | 實現值 | 實現狀態 | 說明 |
|----------|--------|--------|----------|------|
| **時間基準分片** | `time` | `TimeBased` | ✅ 已實現 | 基於固定時間間隔的分片 |
| **句子級分片** | `sentence` | `Sentence` | ✅ 已實現 | 基於 ASR 轉錄的句子邊界 |
| **場景級分片** | `scene` | `Cut` | ⚠️ 部分實現 | 基於 CUT 算法的場景邊界檢測 |
| **視覺物件級分片** | `visual` | (未實現) | ❌ 未實現 | 基於 YOLO 的物件檢測分片 |
| **摘要級分片** | `summary` | `Story` | ⚠️ 概念調整 | 基於分片聚合的敘事重建 |
| **軌跡追蹤分片** | (未定義) | `Trace` | ✅ 已實現 | 人物/物件軌跡追蹤分片 |

### 2.2 實際 Rust 代碼定義

```rust
// src/core/chunk/mod.rs 中的 ChunkType 枚舉
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq)]
#[serde(rename_all = "snake_case")]
pub enum ChunkType {
    TimeBased,    // 時間基準分片
    Sentence,     // 句子級分片
    Cut,          // 場景級分片 (基於 CUT 算法)
    Trace,        // 軌跡追蹤分片
    Story,        // 敘事分片 (原設計的摘要分片)
}
```

### 2.3 文檔撰寫指南

1. **新文檔撰寫**：一律使用實現值 (`TimeBased`, `Sentence`, `Cut`, `Trace`, `Story`)
2. **舊文檔更新**：將設計值替換為實現值，並添加註釋說明
3. **狀態標記**：對於未實現或部分實現的功能，使用狀態標記 (✅, ⚠️, ❌)

---

## 3. 分片規則 (Chunk Rule) 對照

### 3.1 設計與實現對照表

| 規則編號 | 設計名稱 | 實現名稱 | 實現狀態 | 對應 ChunkType |
|----------|----------|----------|----------|----------------|
| **Rule 1** | 句子級分片 | Rule 1 (句子分片) | ✅ 已實現 | `Sentence` |
| **Rule 2** | 視覺物件級分片 | (未實現) | ❌ 未實現 | (未實現) |
| **Rule 3** | 場景級分片 | Rule 3 (場景分片) | ⚠️ 部分實現 | `Cut` |
| **Rule 4** | 摘要級分片 | Rule 4 (敘事分片) | ⚠️ 概念調整 | `Story` |

### 3.2 實際實現狀態

1. **Rule 1**: 完整實現於 `src/core/chunk/rule1_ingest.rs`
2. **Rule 2**: 未實現，僅有設計概念
3. **Rule 3**: 部分實現，使用 CUT 算法檢測場景邊界
4. **Rule 4**: 概念調整，實現為基於分片聚合的敘事重建

---

## 4. 數據模型對照

### 4.1 設計中的數據模型

```json
{
  "chunk_type": "sentence|visual|scene|summary",  // 設計值
  "content": {
    "text": "轉錄文本",
    "visual_objects": ["person", "car", "dog"],
    "scene_context": "辦公室會議",
    "summary": "會議討論項目進度"
  }
}
```

### 4.2 實際實現的數據模型

```rust
// src/core/chunk/mod.rs 中的 Chunk 結構
pub struct Chunk {
    pub id: i64,
    pub uuid: String,
    pub video_record_id: i64,
    pub chunk_type: ChunkType,  // 實現值: TimeBased|Sentence|Cut|Trace|Story
    pub start_time: f64,
    pub end_time: f64,
    pub content: serde_json::Value,  // 動態 JSON 內容
    pub embedding: Option<Vec<f32>>,
    pub created_at: DateTime<Utc>,
}
```

### 4.3 關鍵差異

1. **類型系統**：設計使用字符串枚舉，實現使用 Rust 枚舉
2. **內容結構**：設計有固定字段，實現使用動態 JSON
3. **時間表示**：設計使用時間戳+時長，實現使用開始/結束時間

---

## 5. 處理管道對照

### 5.1 設計管道

```
ASR → OCR → YOLO → CUT → LLM → 分片生成
```

### 5.2 實際管道

```
ASR → OCR → YOLO → CUT → 分片生成
                    ↓
                LLM（尚未集成）
```

### 5.3 關鍵差異點

1. **LLM 集成**：設計中有完整 LLM 階段，實際尚未集成
2. **處理順序**：實際實現根據技術依賴關係調整了順序
3. **並行處理**：實際實現有更多並行處理優化

---

## 6. 文檔更新指南

### 6.1 更新原則

1. **優先級**：以實際 Rust 代碼實現為準
2. **一致性**：所有文檔使用相同的術語
3. **狀態標記**：明確標記功能實現狀態
4. **版本控制**：記錄術語變更歷史

### 6.2 具體更新操作

#### 6.2.1 分片類型更新

| 舊術語 | 新術語 | 更新說明 |
|--------|--------|----------|
| `chunk_type: "sentence"` | `chunk_type: "Sentence"` | 保持 PascalCase |
| `chunk_type: "visual"` | `chunk_type: (未實現)` | 標記為未實現 |
| `chunk_type: "scene"` | `chunk_type: "Cut"` | 使用實際實現值 |
| `chunk_type: "summary"` | `chunk_type: "Story"` | 使用實際實現值 |

#### 6.2.2 規則名稱更新

| 舊術語 | 新術語 | 更新說明 |
|--------|--------|----------|
| `Rule 2 (visual)` | `Rule 2 (未實現)` | 標記為未實現 |
| `Rule 3 (scene)` | `Rule 3 (場景分片)` | 使用中文描述 |
| `Rule 4 (summary)` | `Rule 4 (敘事分片)` | 使用中文描述 |

### 6.3 狀態標記系統

| 標記 | 含義 | 使用場景 |
|------|------|----------|
| ✅ | 已完整實現 | 功能完全按照設計實現 |
| ⚠️ | 部分實現 | 功能部分實現，有差異 |
| ❌ | 未實現 | 功能尚未實現 |
| 🔄 | 概念調整 | 設計概念在實現中調整 |

---

## 7. 使用示例

### 7.1 正確示例

```markdown
## 分片類型

Momentry Core 支持以下分片類型：

1. **TimeBased** (時間基準分片) ✅ 已實現
2. **Sentence** (句子級分片) ✅ 已實現  
3. **Cut** (場景級分片) ⚠️ 部分實現
4. **Trace** (軌跡追蹤分片) ✅ 已實現
5. **Story** (敘事分片) ⚠️ 概念調整

**注意**：設計中的 `visual` 分片尚未實現，設計中的 `summary` 分片已調整為 `Story` 分片。
```

### 7.2 錯誤示例

```markdown
## 分片類型

Momentry Core 支持以下分片類型：

1. sentence (句子級分片)
2. visual (視覺物件級分片)
3. scene (場景級分片) 
4. summary (摘要級分片)
```

---

## 8. 維護與更新

### 8.1 更新流程

1. **代碼變更**：當 Rust 代碼中的類型定義變更時
2. **文檔更新**：根據本文檔更新所有相關文檔
3. **一致性檢查**：運行 `scripts/check_architecture_docs.py` 驗證
4. **版本更新**：更新本文檔的版本歷史

### 8.2 審查要點

1. **術語一致性**：所有文檔是否使用相同的術語
2. **狀態準確性**：功能實現狀態是否準確標記
3. **文檔完整性**：所有重要概念是否都有對照說明

### 8.3 自動化檢查

```bash
# 運行架構文檔一致性檢查
python3 scripts/check_architecture_docs.py --check-terminology
```

---

## 9. 結論

本文檔作為 Momentry Core 架構文檔的術語標準，確保：
1. **設計與實現一致性**：文檔準確反映實際代碼狀態
2. **文檔統一性**：所有文檔使用相同的術語體系
3. **可維護性**：提供明確的更新和維護指南

**核心原則重申**：在出現矛盾時，實際的 Rust 代碼實現是最高權威，設計文檔應反映實際實現狀態並指導未來改進方向。

---

## 附錄 A：快速參考

### A.1 分片類型快速參考

| 使用場景 | 推薦術語 | 狀態 |
|----------|----------|------|
| 時間基準分片 | `TimeBased` | ✅ |
| 句子級分片 | `Sentence` | ✅ |
| 場景級分片 | `Cut` | ⚠️ |
| 軌跡追蹤分片 | `Trace` | ✅ |
| 敘事分片 | `Story` | ⚠️ |
| 視覺物件分片 | (標記為未實現) | ❌ |

### A.2 規則名稱快速參考

| 規則 | 推薦名稱 | 狀態 |
|------|----------|------|
| Rule 1 | 句子分片規則 | ✅ |
| Rule 2 | (標記為未實現) | ❌ |
| Rule 3 | 場景分片規則 | ⚠️ |
| Rule 4 | 敘事分片規則 | ⚠️ |

### A.3 狀態標記快速參考

- ✅：使用 `chunk_type: "Sentence"` (已實現)
- ⚠️：使用 `chunk_type: "Cut"` ⚠️ 部分實現 (部分實現)
- ❌：標記為 "未實現" 或 "設計概念" (未實現)
- 🔄：說明概念調整原因 (概念調整)

---

**文件版本**: V1.0  
**最後更新**: 2026-04-22  
**維護者**: OpenCode