dramaling-vocab-learning/backend/DramaLing.Api/ARCHITECTURE.md

# DramaLing API 架構文檔

**版本**: 2.0
**架構模式**: Clean Architecture + Domain-Driven Design
**最後更新**: 2025-09-30

## 🏗️ 架構概覽

DramaLing API 採用 Clean Architecture 原則設計，實現高內聚、低耦合的現代化後端架構。遵循 Domain-Driven Design 理念，按業務領域組織代碼結構。

### 核心設計原則

1. **依賴反轉原則** - 高層模組不依賴於低層模組
2. **單一職責原則** - 每個類別只有一個改變的理由
3. **開放封閉原則** - 對擴展開放，對修改封閉
4. **介面隔離原則** - 不應該被迫依賴不使用的方法

---

## 📁 目錄架構

```
DramaLing.Api/
├── Controllers/           # 🎯 API 控制器層 - Web API 端點
├── Services/             # 💼 業務服務層 - 領域邏輯實現
│   ├── AI/              #   🤖 AI 相關服務 (Gemini, 圖片生成)
│   ├── Core/            #   🔧 核心業務服務 (認證)
│   ├── Infrastructure/  #   🏗️ 基礎設施服務 (快取, 監控)
│   ├── Media/           #   📁 多媒體服務 (音訊, 圖片, 儲存)
│   └── Vocabulary/      #   📚 詞彙相關服務
├── Repositories/         # 💾 資料訪問層 - 數據持久化
├── Data/                # 🗄️ EF Core 配置 - 資料庫上下文
├── Models/              # 📋 資料模型層
│   ├── Entities/        #   📊 實體模型 - 資料庫映射
│   ├── DTOs/            #   📦 數據傳輸物件 - API 交換
│   └── Configuration/   #   ⚙️ 配置類別 - 系統設定
├── Extensions/          # 🔧 擴展方法 - 依賴注入配置
├── Middleware/          # 🔗 中間件 - 請求處理管道
└── DramaLing.Api.Tests/ # 🧪 測試專案 - 完整測試覆蓋
```

---

## 🎯 Clean Architecture 分層

### 1. Presentation Layer (表示層)

**Controllers/** - Web API 控制器
- 處理 HTTP 請求和回應
- 路由和參數驗證
- 調用 Service 層執行業務邏輯
- **依賴**: Service Layer

**關鍵特色**:
- 遵循 RESTful API 設計原則
- 統一的錯誤處理和回應格式
- JWT 認證和授權控制
- Swagger/OpenAPI 文檔生成

### 2. Application/Service Layer (應用服務層)

**Services/** - 業務邏輯和應用服務

#### 2.1 領域服務組織

```
Services/
├── AI/                  # 🤖 AI 領域服務
│   ├── Analysis/       # 分析服務
│   ├── Gemini/         # Gemini AI 服務群組
│   └── Generation/     # 圖片生成服務群組
├── Core/               # 🔧 核心領域
├── Infrastructure/     # 🏗️ 基礎設施
├── Media/              # 📁 多媒體領域
└── Vocabulary/         # 📚 詞彙領域
```

#### 2.2 服務架構模式

**Facade Pattern**: 每個服務群組都有統一入口
```csharp
// 主要服務 - 統一入口
GeminiService (Facade)
├── SentenceAnalyzer
├── ImageDescriptionGenerator
└── GeminiClient
```

**Composition Pattern**: 複雜服務由多個小服務組合
```csharp
HybridCacheService (Facade)
├── MemoryCacheProvider
├── DistributedCacheProvider
├── CacheStrategyManager
└── DatabaseCacheManager
```

### 3. Domain Layer (領域層)

**Models/Entities/** - 領域實體和業務規則
- User, Flashcard, AnalysisCache 等核心實體
- 業務邏輯和驗證規則
- 實體間關係定義

**Models/DTOs/** - 數據傳輸物件
- API 請求和回應模型
- 層間數據傳輸規範
- 序列化和驗證屬性

### 4. Infrastructure Layer (基礎設施層)

**Repositories/** - 資料訪問抽象
- Repository Pattern 實現
- 資料庫查詢邏輯
- 資料持久化操作

**Data/** - 數據基礎設施
- Entity Framework DbContext
- 資料庫連接和配置
- 資料庫遷移

---

## 🔄 依賴注入架構

### 服務註冊策略

**Extensions/ServiceCollectionExtensions.cs** - 模組化 DI 配置

```csharp
// 依生命週期組織服務註冊
services.AddDatabaseServices(configuration);     // Scoped
services.AddRepositoryServices();               // Scoped
services.AddCachingServices();                  // Mixed
services.AddAIServices(configuration);          // Mixed
services.AddBusinessServices();                 // Scoped
services.AddAuthenticationServices();           // Singleton
```

### 生命週期管理

| 服務類型 | 生命週期 | 說明 |
|---------|---------|------|
| **Controllers** | Scoped | 每個請求一個實例 |
| **Services** | Scoped | 業務邏輯服務 |
| **Repositories** | Scoped | 資料訪問服務 |
| **Cache Providers** | Singleton/Scoped | 根據實現決定 |
| **HTTP Clients** | Singleton | HTTP 連接池管理 |

---

## 🗄️ 資料存取架構

### Repository Pattern 實現

```csharp
// 泛型基礎介面
IRepository<T> : 基本 CRUD 操作

// 特化介面
IFlashcardRepository : IRepository<Flashcard>
├── GetByUserIdAsync()
├── GetByUserIdAndFlashcardIdAsync()
├── GetCountByUserIdAsync()
└── GetPagedByUserIdAsync()
```

### Entity Framework Core 配置

- **Database Provider**: SQLite (開發/測試), SQL Server (生產)
- **Code First**: 資料庫遷移管理
- **Connection String**: 環境變數優先配置
- **LazyLoading**: 關閉，使用明確載入

---

## 🚀 快取架構

### 混合快取策略

**HybridCacheService** 實現多層快取:

```
L1: Memory Cache (熱點數據)
    ↓ (Miss)
L2: Distributed Cache (跨實例共享)
    ↓ (Miss)
L3: Database Cache (持久化快取)
    ↓ (Miss)
Original Data Source
```

### 快取策略管理

- **智能過期**: 根據數據類型動態設定 TTL
- **快取預熱**: 應用啟動時預載熱點數據
- **快取更新**: Write-Through 和 Write-Behind 策略
- **快取統計**: 命中率和效能監控

---

## 🤖 AI 服務架構

### Gemini AI 整合

**GeminiService (Facade Pattern)**:
```csharp
├── SentenceAnalyzer      # 句子語意分析
├── ImageDescriptionGenerator # 圖片描述生成
└── GeminiClient         # HTTP API 通訊
```

### 圖片生成工作流

**ImageGenerationOrchestrator**:
```csharp
├── ImageGenerationWorkflow   # 主要生成流程
├── GenerationStateManager    # 狀態追蹤
├── ImageSaveManager         # 圖片儲存
└── GenerationPipelineService # 管道協調
```

---

## 🔐 認證與安全架構

### JWT 認證流程

1. **Supabase 整合**: 用戶註冊和登入
2. **Token 驗證**: JWT 中間件驗證
3. **授權控制**: 基於 Claims 的授權
4. **CORS 配置**: 跨域請求安全控制

### 安全最佳實務

- 敏感資訊環境變數管理
- API Key 安全儲存
- 輸入驗證和 SQL 注入防護
- HTTPS 強制和安全標頭

---

## 🧪 測試架構

### 測試金字塔實現

```
E2E Tests (Integration)
    ↑
Unit Tests (Services, Repositories)
    ↑
Infrastructure Tests (Database, Cache)
```

### 測試基礎設施

- **TestBase**: 統一測試環境設定
- **TestDataFactory**: 測試數據建立工具
- **InMemory Database**: 快速單元測試
- **Mock Services**: 外部依賴模擬

---

## 📊 監控與日誌

### 結構化日誌

```csharp
// 分級日誌記錄
Logger.LogInformation("Business operation completed: {Operation}", operation);
Logger.LogWarning("Performance threshold exceeded: {ResponseTime}ms", time);
Logger.LogError(ex, "Error processing request: {RequestId}", requestId);
```

### 效能監控

- **API 回應時間**: 端點效能追蹤
- **資料庫查詢**: EF Core 查詢分析
- **快取效能**: 命中率和延遲監控
- **記憶體使用**: GC 和記憶體洩漏檢測

---

## 🔧 開發工作流

### 新功能開發流程

1. **領域分析**: 確定功能所屬領域
2. **介面設計**: 定義 Service 介面
3. **實現邏輯**: 實作業務邏輯
4. **資料訪問**: 建立或更新 Repository
5. **API 端點**: 建立 Controller 方法
6. **單元測試**: 撰寫測試覆蓋
7. **整合測試**: API 端點測試
8. **文檔更新**: 更新相關文檔

### 程式碼品質保證

- **靜態分析**: SonarQube/CodeQL 掃描
- **程式碼風格**: EditorConfig 統一格式
- **Git Hook**: Pre-commit 品質檢查
- **CI/CD**: 自動化構建和部署

---

## 📈 效能優化策略

### 1. 資料庫最佳化

- **索引優化**: 常用查詢欄位索引
- **查詢優化**: N+1 問題避免
- **連接池**: 資料庫連接管理
- **分頁查詢**: 大數據集分頁載入

### 2. 快取最佳化

- **快取分層**: 多層快取命中優化
- **快取預熱**: 應用啟動預載
- **過期策略**: 智能 TTL 管理
- **快取穿透**: 空值快取防護

### 3. 並發處理

- **異步操作**: async/await 模式
- **並行執行**: Task.WhenAll 批量處理
- **資源池**: HTTP Client 連接池
- **限流控制**: API 頻率限制

---

## 🚀 部署架構

### 環境配置

```
Development → Testing → Staging → Production
     ↓           ↓        ↓         ↓
   SQLite → SQL Server → Azure SQL → Azure SQL
   Memory → Redis Cache → Azure Cache → Azure Cache
```

### 容器化部署

```dockerfile
# 多階段構建
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
# ... 構建邏輯
FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS runtime
# ... 運行時配置
```

---

## 📋 架構決策記錄 (ADR)

### ADR-001: 選擇 Clean Architecture
- **日期**: 2025-09-29
- **狀態**: 已採用
- **決策**: 採用 Clean Architecture 架構模式
- **原因**: 提高可測試性、可維護性和可擴展性

### ADR-002: Repository Pattern 實現
- **日期**: 2025-09-30
- **狀態**: 已採用
- **決策**: 實現 Repository Pattern 進行資料訪問抽象
- **原因**: 分離業務邏輯和資料訪問，提升可測試性

### ADR-003: Facade Pattern 在服務層
- **日期**: 2025-09-30
- **狀態**: 已採用
- **決策**: 使用 Facade Pattern 簡化複雜服務調用
- **原因**: 降低客戶端複雜度，提供統一服務入口

---

## 🔮 未來架構演進

### 短期優化 (1-3個月)

- **微服務拆分**: 大型服務領域拆分
- **消息隊列**: 異步處理長時間任務
- **API 版本控制**: 向下兼容的版本管理
- **健康檢查**: 完整的應用健康監控

### 長期規劃 (3-12個月)

- **Event Sourcing**: 事件驅動架構演進
- **CQRS**: 讀寫分離模式實現
- **Kubernetes**: 容器編排和自動擴展
- **監控觀測**: APM 和分散式追蹤

---

**文檔維護者**: DramaLing 開發團隊
**架構版本**: Clean Architecture 2.0
**最後審核**: 2025-09-30
**下次審核**: 2025-12-30