# Rule Specification & Data Flow (規則規範與數據流)

| 項目 | 內容 |
|------|------|
| 建立者 | OpenCode |
| 建立時間 | 2026-04-25 |
| 文件版本 | V1.0 |

---

## 版本歷史

| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|------|------|------|--------|-----------|
| V1.0 | 2026-04-25 | 定義 Rule 的 Input/Logic/Output 及依賴關係 (DAG) | OpenCode | OpenCode |

---

## 1. 核心概念

**Rule (規則)** 負責將 **Processor** 產出的原始數據 (`pre_chunks`) 聚合、過濾、推論為有意義的 **Chunks**。

### 1.1 數據流向

```mermaid
graph LR
    Video((Video File)) -->|Process| P1[Processor: YOLO/Face/OCR]
    Video -->|Process| P2[Processor: ASR/CUT]
    
    P1 -->|JSON/JSONL| DB[(pre_chunks)]
    P2 -->|JSON/JSONL| DB
    
    DB -->|Read| R1[Rule 1: Sentence]
    DB -->|Read| R2[Rule 2: Visual]
    DB -->|Read| R3[Rule 3: Scene]
    
    R1 -->|Write| Chunks[(chunks)]
    R2 -->|Write| Chunks
    R3 -->|Write| Chunks
    
    Chunks -->|Read| Agent[AI Agent: 5W1H/Summary]
    Agent -->|Update| Chunks
```

---

## 2. 依賴管理 (DAG)

為了解決依賴關係糾結的問題，系統採用 **顯式依賴宣告 (Explicit Dependency Declaration)**。
Job Worker 根據此配置決定何時觸發 Rule。

```json
{
  "rules": [
    {
      "rule_id": "rule_1_sentence",
      "description": "語句級聚合 (基於 ASR)",
      "dependencies": ["processor_asr"], 
      "agent_involved": false
    },
    {
      "rule_id": "rule_2_visual",
      "description": "視覺片段聚合 (基於 YOLO/Face)",
      "dependencies": ["processor_yolo", "processor_face"],
      "agent_involved": false
    },
    {
      "rule_id": "rule_3_scene",
      "description": "場景級聚合 (基於 CUT + ASR 對齊)",
      "dependencies": ["processor_cut", "processor_asr"],
      "agent_involved": false
    },
    {
      "rule_id": "rule_4_summary",
      "description": "生成段落摘要 (依賴所有 Rule 1-3 完成)",
      "dependencies": ["rule_1_sentence", "rule_3_scene"],
      "agent_involved": true 
    }
  ]
}
```

**觸發邏輯**:
* 當 `dependencies` 中列出的所有項目狀態變為 `completed` 時，觸發該 Rule。

---

## 3. Rule 詳細定義

### 3.1 Rule 1: Sentence (語句聚合)

* **用途**: 將 ASR 的逐字/逐句輸出聚合為可搜尋的文本 Chunk。
* **Input**: `pre_chunks` 表中 `processor_type = 'asr'` 的紀錄。
* **Logic**:
    1. 按時間順序讀取 ASR segments。
    2. (可選) 結合物件標籤 (YOLO) 豐富 metadata。
    3. 生成 `ChunkType::Sentence`。
* **Output**: 寫入 `chunks` 表。

### 3.2 Rule 2: Visual (視覺聚合)

* **用途**: 將零散的 Frame 聚合為有意義的視覺事件 (例如：「某人出現在畫面中 5 秒」)。
* **Input**:
  * `pre_chunks` 表中 `processor_type = 'yolo'` 的紀錄。
  * `pre_chunks` 表中 `processor_type = 'face'` 的紀錄。
* **Logic**:
    1. **滑動視窗**: 若連續 N 幀都偵測到同一 Identity，視為一個 Visual Chunk。
    2. **事件過濾**: 忽略低於信心度閾值的偵測。
    3. 生成 `ChunkType::Visual`。
* **Output**: 寫入 `chunks` 表。

### 3.3 Rule 3: Scene (場景聚合)

* **用途**: 基於鏡頭切換 (CUT) 與語音內容，定義場景邊界。
* **Input**:
  * `pre_chunks` 表中 `processor_type = 'cut'` 的紀錄。
  * `chunks` 表中 Rule 1 產生的 Sentence Chunks (用於填充場景內容)。
* **Logic**:
    1. 讀取 CUT 偵測到的 Scene 邊界。
    2. 將該時間段內的所有 Rule 1 Chunks 關聯到此 Scene。
    3. 生成 `ChunkType::Scene`。
* **Output**: 寫入 `chunks` 表。

### 3.4 Rule 4: Summary / Agent (AI 摘要)

* **用途**: 利用 LLM 生成場景或影片的摘要、5W1H 標籤。
* **Input**: `chunks` 表中已完成的 Scene/Sentence Chunks。
* **Logic**:
    1. 收集 Chunk 的文本、視覺標籤。
    2. 調用 **Translation/Summary Agent**。
    3. 將生成的摘要與標籤更新回 `chunks` 表的 `metadata` 欄位。
* **Output**: 更新 `chunks` 表 (In-place Update)。

---

## 4. Agent 在 Rule 中的角色

AI Agent 不再是獨立的「黑盒子」，而是作為 Rule 的執行引擎之一。

* **Prompt Injection**: Rule 負責組裝 Context (Input Chunks)，注入預定義的 Prompt Template。
* **Structured Output**: Agent 必須輸出符合 Schema 的 JSON，以便 Rust 寫入資料庫。

**範例 (Rule 4 摘要)**:
> "You are a movie analyst. Based on the following dialogue and visual tags, summarize the scene in 50 words and extract the 5W1H entities."

---

## 版本資訊

* 版本: V1.0
* 建立日期: 2026-04-25
