---
document_type: "architecture_design"
service: "MOMENTRY_CORE"
title: "架構決策卡片"
date: "2026-04-22"
version: "V1.0"
status: "active"
owner: "Warren"
created_by: "OpenCode"
tags:
  - "架構決策卡片"
ai_query_hints:
  - "查詢 架構決策卡片 的內容"
  - "架構決策卡片 的主要目的是什麼？"
  - "如何操作或實施 架構決策卡片？"
---

# 架構決策卡片

## 卡片 1: 分片類型設計

| 項目 | 內容 |
|------|------|
| **決策編號** | AD-2026-001 |
| **決策名稱** | ChunkType 枚舉設計 |
| **決策時間** | 2026-04-22 |
| **決策狀態** | ✅ 已實施 |
| **相關代碼** | `src/core/chunk/types.rs:6-12` |

### 問題描述
設計文檔中定義的分片類型 (`sentence|visual|scene|summary`) 與實際代碼實現不一致，導致設計與實現脫節。

### 決策選項
1. **選項 A**: 修改代碼適應設計文檔
   - 優點：保持設計一致性
   - 缺點：需要大量代碼修改，可能影響現有功能
2. **選項 B**: 更新設計文檔反映實際實現
   - 優點：反映真實系統狀態，維護成本低
   - 缺點：設計文檔與原始設計偏離

### 最終決策
選擇 **選項 B**，以實際代碼實現為準，更新設計文檔。

### 實施方案
1. 更新所有架構文檔使用實際的 `ChunkType` 枚舉值
2. 創建術語對照表
3. 更新代碼註釋

### 影響評估
- **正面影響**: 設計與實現一致，減少團隊困惑
- **負面影響**: 需要更新大量文檔
- **風險**: 術語混亂過渡期

---

## 卡片 2: 數據結構類型安全

| 項目 | 內容 |
|------|------|
| **決策編號** | AD-2026-002 |
| **決策名稱** | 分片內容類型安全設計 |
| **決策時間** | 2026-04-22 |
| **決策狀態** | ⚠️ 待實施 |
| **相關代碼** | `src/core/chunk/types.rs:43-65` |

### 問題描述
當前 `Chunk` 結構使用 `serde_json::Value` 存儲動態內容，缺乏類型安全，容易導致運行時錯誤。

### 決策選項
1. **選項 A**: 保持動態 JSON 結構
   - 優點：靈活性高，易於擴展
   - 缺點：缺乏類型安全，編譯時無法檢測錯誤
2. **選項 B**: 實現類型安全結構
   - 優點：編譯時類型檢查，代碼更安全
   - 缺點：靈活性降低，需要為每個分片類型定義專用結構

### 最終決策
選擇 **選項 B**，分階段實現類型安全重構。

### 實施方案
1. Phase 1: 為每個 `ChunkType` 定義專用內容結構
2. Phase 2: 實現自動化遷移工具
3. Phase 3: 保持向後兼容性，逐步遷移

### 影響評估
- **正面影響**: 提高代碼安全性，減少運行時錯誤
- **負面影響**: 開發複雜度增加，需要遷移現有數據
- **風險**: 遷移過程中可能出現兼容性問題

---

## 卡片 3: 處理管道設計

| 項目 | 內容 |
|------|------|
| **決策編號** | AD-2026-003 |
| **決策名稱** | 統一處理器執行框架 |
| **決策時間** | 2026-04-22 |
| **決策狀態** | ✅ 已實施 |
| **相關代碼** | `src/core/processor/executor.rs` |

### 問題描述
不同的 AI 處理器使用不同的執行方式，缺乏統一的錯誤處理和超時控制。

### 決策選項
1. **選項 A**: 每個處理器獨立實現執行邏輯
   - 優點：各處理器可以優化自身執行
   - 缺點：代碼重複，錯誤處理不一致
2. **選項 B**: 創建統一執行器框架
   - 優點：代碼復用，統一的錯誤處理和超時控制
   - 缺點：可能需要適配現有處理器

### 最終決策
選擇 **選項 B**，實現 `PythonExecutor` 統一框架。

### 實施方案
1. 創建 `PythonExecutor` 結構，提供統一的腳本執行接口
2. 支持超時控制、錯誤恢復和結果解析
3. 所有 Python 腳本處理器使用統一的執行器

### 影響評估
- **正面影響**: 代碼復用，統一的錯誤處理，易於維護
- **負面影響**: 需要修改現有處理器適配新框架
- **風險**: 過渡期可能出現執行問題

---

## 卡片 4: 多數據庫架構

| 項目 | 內容 |
|------|------|
| **決策編號** | AD-2026-004 |
| **決策名稱** | 多數據庫系統設計 |
| **決策時間** | 2026-04-22 |
| **決策狀態** | ✅ 已實施 |
| **相關代碼** | `src/core/db/` 目錄 |

### 問題描述
系統需要處理不同類型的數據：結構化數據、向量數據、緩存數據和文檔數據。

### 決策選項
1. **選項 A**: 單一數據庫系統
   - 優點：架構簡單，維護成本低
   - 缺點：性能可能受限，不適合所有數據類型
2. **選項 B**: 多數據庫系統
   - 優點：每種數據類型使用最適合的數據庫，性能最佳
   - 缺點：架構複雜，維護成本高

### 最終決策
選擇 **選項 B**，實現多數據庫系統。

### 實施方案
1. **PostgreSQL**: 存儲結構化數據（視訊、分片、任務）
2. **Redis**: 緩存和隊列管理
3. **Qdrant**: 向量數據存儲和檢索
4. **MongoDB**: 文檔數據存儲

### 影響評估
- **正面影響**: 每種數據類型性能最優，系統擴展性好
- **負面影響**: 架構複雜，需要管理多個數據庫連接
- **風險**: 數據一致性維護複雜

---

## 卡片 5: 環境隔離設計

| 項目 | 內容 |
|------|------|
| **決策編號** | AD-2026-005 |
| **決策名稱** | 開發與生產環境隔離 |
| **決策時間** | 2026-04-22 |
| **決策狀態** | ✅ 已實施 |
| **相關代碼** | `src/bin/momentry_playground.rs` |

### 問題描述
開發環境和生產環境需要隔離，避免開發測試影響生產數據。

### 決策選項
1. **選項 A**: 單一環境，通過配置切換
   - 優點：架構簡單，部署方便
   - 缺點：開發測試可能污染生產數據
2. **選項 B**: 完全隔離的多環境
   - 優點：環境完全隔離，安全可靠
   - 缺點：需要維護多套環境

### 最終決策
選擇 **選項 B**，實現完全環境隔離。

### 實施方案
1. **生產環境**: `momentry` 二進制，使用 `momentry:` Redis 網址
2. **開發環境**: `momentry_playground` 二進制，使用 `momentry_dev:` Redis 網址
3. **環境配置**: 通過環境變數和配置文件區分

### 影響評估
- **正面影響**: 環境完全隔離，開發測試不影響生產
- **負面影響**: 需要維護多套部署配置
- **風險**: 配置錯誤可能導致環境混亂

---

## 如何使用決策卡片

### 新增決策
1. 創建新的決策卡片
2. 填寫決策編號 (AD-YYYY-NNN)
3. 記錄決策過程和結果
4. 更新到本文檔

### 決策審查
1. 每季度審查所有決策卡片
2. 評估決策實施效果
3. 必要時調整或撤銷決策

### 決策歸檔
1. 已完成的決策歸檔到歷史記錄
2. 失敗的決策記錄失敗原因和學習點
3. 成功的決策作為最佳實踐參考

---

**最後更新**: 2026-04-22  
**卡片數量**: 5  
**狀態分布**: ✅ 已實施 4，⚠️ 待實施 1
