# 架構優化待評估事項

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

---

## 版本歷史

| 版本 | 日期 | 目的 | 操作人 |
|------|------|------|--------|
| V1.0 | 2026-03-21 | 創建文件 | OpenCode |
| V1.1 | 2026-03-22 | 新增 TigerGraph/GraphRAG 說故事評估 | OpenCode |

---

## 架構優化項目

### 1. PostgreSQL → Redis 故障轉移

**說明**: 當 PostgreSQL 不可用時，降級到 Redis 作為臨時存儲

**複雜度**: 中

**影響範圍**:
- `src/core/db/postgres_db.rs`
- `src/core/db/redis_client.rs`

**風險**:
- 數據一致性問題
- 需要定義轉移策略

**優先級**: 待評估

---

### 2. 連接池監控

**說明**: 添加 PostgreSQL 和 Redis 連接池指標到 Prometheus

**複雜度**: 低

**影響範圍**:
- `src/core/db/postgres_db.rs`
- `src/core/db/redis_client.rs`
- `src/api/` (新增 metrics endpoint)

**風險**: 低

**優先級**: 待評估

---

### 3. Processor 重試機制

**說明**: 當 processor 失敗時自動重試

**複雜度**: 中

**影響範圍**:
- `src/core/processor/executor.rs` (新增 `run_with_retry` 方法)
- `src/core/processor/mod.rs` (導出 `RetryConfig`)

**風險**:
- 無限重試風險 → 已通過 `max_attempts` 控制
- 需要指數退避 → 已實現

**優先級**: ✅ 已完成 (2026-03-21)

**實作內容**:
- `RetryConfig` 結構體 (可配置重試次數、初始延遲、最大延遲、退避倍數)
- `run_with_retry()` 方法 (自動重試 + 指數退避)
- 單元測試覆蓋

**使用範例**:
```rust
use crate::core::processor::{PythonExecutor, RetryConfig};

let executor = PythonExecutor::new()?;
let config = RetryConfig::new(3).with_delay(1000).with_max_delay(30000);

executor.run_with_retry(
    "asr_processor.py",
    &["--input", "/path/to/video"],
    Some(&uuid),
    "asr",
    Some(Duration::from_secs(3600)),
    Some(config),
).await?;
```

---

### 4. PyO3 整合

**說明**: Python/Rust 直接調用，移除子進程調用

**複雜度**: 高

**影響範圍**:
- `src/core/processor/executor.rs` (重寫)
- Python 模組 (修改為可直接 import)

**風險**:
- Python GIL 問題
- 依賴版本兼容性
- 需要大量重寫

**優先級**: 低 (長期目標)

---

### 5. HTTP 健康端點

**說明**: 添加 `/health` API 用於外部監控

**複雜度**: 低

**影響範圍**:
- `src/api/server.rs` (新增路由)

**風險**: 低

**優先級**: ✅ 已完成 (2026-03-21)

**實作內容**:
- `GET /health` - 基本健康檢查 (status, version, uptime)
- `GET /health/detailed` - 詳細健康檢查 (PostgreSQL, Redis, Qdrant 狀態和延遲)

---

### 6. Gitea Actions CI/CD

**說明**: 配置 Gitea Actions 自動化 CI/CD，在合併前執行檢查

**複雜度**: 中

**影響範圍**:
- `.gitea/workflows/` (新增 workflow 文件)

**優點**:
- 強制執行檢查，無法跳過
- 跨設備一致
- PR 審查前自動檢查

**風險**: 低

**優先級**: 待評估

---

### 7. Commit Message Lint

**說明**: 規範化提交訊息格式 (Conventional Commits)

**複雜度**: 低

**影響範圍**:
- `.git/hooks/commit-msg` (新增 hook)
- `~/dotfiles/hooks/commit-msg`

**風險**: 低

**優先級**: ✅ 已完成 (2026-03-21)

**實作內容**:
- 驗證格式: `<type>(<scope>): <description>`
- 有效類型: feat, fix, docs, style, refactor, test, chore, perf, ci, build, revert
- 警告: 第一行超過 72 字符

**範例**:
```
feat(api): add health check endpoint
fix(db): resolve connection pool issue
docs: update README
```

---

### 8. 自動化安裝腳本

**說明**: 創建腳本一次安裝所有開發工具

**複雜度**: 低

**影響範圍**:
- `scripts/install-dev-tools.sh` (新增)

**風險**: 低

**優先級**: 待評估

---

## 評估標準

| 標準 | 說明 |
|------|------|
| 業務價值 | 對用戶有何幫助 |
| 技術風險 | 實現難度和潛在問題 |
| 維護成本 | 未來維護負擔 |
| 依賴性 | 對其他系統的影響 |

---

## 評估記錄

| 項目 | 評估日期 | 決策 | 原因 |
|------|----------|------|------|
| PostgreSQL → Redis 故障轉移 | 待評估 | - | - |
| 連接池監控 | 待評估 | - | - |
| Processor 重試機制 | 2026-03-21 | 已完成 | - |
| PyO3 整合 | 待評估 | - | - |
| HTTP 健康端點 | 2026-03-21 | 已完成 | - |
| Gitea Actions CI/CD | 待評估 | - | - |
| Commit Message Lint | 2026-03-21 | 已完成 | - |
| 自動化安裝腳本 | 待評估 | - | - |

---

## 9. TigerGraph / Knowledge Graph 圖譜說故事

**說明**: 使用知識圖譜 (Knowledge Graph) 增強視頻敘事 (Storytelling) 和 RAG 檢索

**複雜度**: 高

**研究來源**:
- [TigerGraph Agentic GraphRAG](https://www.tigergraph.com/blog/agentic-graphrag-gives-ai-a-playbook-for-smarter-retrieval/) (2025-12-15)
- [TigerGraph GraphRAG GitHub](https://github.com/tigergraph/graphrag) (v1.2.0, 2026-03-11)
- [GraphRAG in 2026: Practitioner's Guide](https://medium.com/graph-praxis/graph-rag-in-2026-a-practitioners-guide-to-what-actually-works-dca4962e7517) (2026-02-22)
- [GraphRAG Complete Guide](https://medium.com/@brian-curry-research/graphrag-the-complete-guide-to-graph-powered-retrieval-augmented-generation-eeb58a6bb4d1) (2026-02-11)

### 核心概念

| 概念 | 說明 |
|------|------|
| **GraphRAG** | 結合知識圖譜與 RAG，比傳統向量檢索更智能 |
| **知識圖譜** | 實體 (Entity) + 關係 (Relationship) 的結構化表示 |
| **多跳推理** | Multi-hop traversal，可連接多個相關節點 |
| **混合檢索** | Graph traversal + Vector similarity 結合 |

### 對 Momentry 的潛在應用

```
視頻場景 → 實體識別 → 關係建立 → 故事圖譜
   ↓            ↓            ↓            ↓
  CUT        [人物, 物品, 動作]  [誰做了什麼, 什麼導致什麼]  [敘事鏈]
```

**1. 敘事圖譜構建 (Narrative Graph)**
- 從 Story/Chunks 模組提取實體
- 建立場景之間的因果關係
- 追蹤角色互動和情節發展

**2. 故事檢索增強**
```python
# 現有: Parent-child chunks
parent_chunk: "場景描述"
child_chunks: [詳細內容]

# 加入圖譜:
場景A --led_to--> 場景B
角色X --interacted_with--> 角色Y
主題Y --related_to--> 主題Z
```

**3. 查詢模式**

| 查詢類型 | 傳統 RAG | GraphRAG |
|----------|----------|----------|
| 事實查找 | ✅ "這個場景在說什麼" | ✅ |
| 主題推理 | ❌ "這個視頻的主要情節" | ✅ Global search |
| 多跳關係 | ❌ | ✅ "A導致B，B導致C" |
| 可解釋性 | ❌ | ✅ 關係路徑可追溯 |

### 實作方案

**方案 A: TigerGraph Cloud (推薦)**
- ✅ 原生 Graph + Vector 混合查詢
- ✅ GraphRAG 官方支援
- ✅ 200GB 免費額度
- ❌ 雲端依賴，延遲敏感場景需考慮

**方案 B: Neo4j + Qdrant**
- ✅ 成熟開源生態
- ✅ LangChain/LlamaIndex 整合
- ❌ 需要維護兩個系統

**方案 C: 自建混合架構**
- PostgreSQL + Neo4j (或Typesense)
- 利用現有 BM25 + 向量檢索基礎
- ❌ 開發成本高

### 技術棧整合建議

```rust
// 現有架構
Vector Search (Qdrant) ← BM25 (PostgreSQL)

// 加入 GraphRAG
Knowledge Graph (TigerGraph/Neo4j) 
       ↓
  混合檢索 ← Vector + Graph traversal
```

### 優先級: 待評估

**考慮因素**:
- 用戶是否需要複雜的故事情節查詢？
- 實體識別 (NER) 成本是否可以接受？
- 與現有 BM25 + Vector 混合搜索的比較優勢？

---

## 10. LazyGraphRAG / FastGraphRAG 成本優化

**說明**: GraphRAG 索引成本高昂，LazyGraphRAG 推遲圖譜構建到查詢時

**來源**: [GraphRAG in 2026](https://medium.com/graph-praxis/graph-rag-in-2026-a-practitioners-guide-to-what-actually-works-dca4962e7517)

**Microsoft GraphRAG 問題**: $33K 索引大型數據集

**替代方案**:
- **LazyGraphRAG**: 按需構建，查詢時再建立子圖
- **FastGraphRAG**: 優化索引管道，10-90% 成本節省
- **HippoRAG**: 使用 Personalised PageRank 優化遍歷

**優先級**: 待評估 (作為 GraphRAG 的一部分)