feat: Initial v0.9 release with API Key authentication

## v0.9.20260325_144654 ### Features - API Key Authentication System - Job Worker System - V2 Backup Versioning ### Bug Fixes - get_processor_results_by_job column mapping Co-authored-by: OpenCode
2026-03-25 14:52:51 +08:00
parent 47e86b696f
commit 383201cacd
193 changed files with 40268 additions and 422 deletions
--- a/docs/ARCHITECTURE_EVALUATION.md
+++ b/docs/ARCHITECTURE_EVALUATION.md
@@ -0,0 +1,331 @@
+# 架構優化待評估事項
+
+| 項目 | 內容 |
+|------|------|
+| 建立者 | 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 的一部分)