# Services 層架構索引

## 概述
Services 層實作業務邏輯，採用領域驅動設計 (DDD) 原則，按功能領域組織服務。所有服務都已重構為符合單一職責原則 (SRP) 和組合模式 (Composition Pattern)。

## 目錄結構

```
Services/
├── README.md                    # 本文檔 - Services 層總覽
├── AI/                         # AI 相關服務
│   ├── Analysis/              # AI 分析服務
│   ├── Gemini/                # Gemini AI 服務
│   └── Generation/            # 圖片生成服務
├── Core/                      # 核心業務服務
│   └── Auth/                  # 認證服務
├── Infrastructure/            # 基礎設施服務
│   ├── Caching/              # 快取服務
│   └── Monitoring/           # 監控服務
├── Media/                     # 多媒體服務
│   ├── Audio/                # 音訊處理服務
│   ├── Image/                # 圖片處理服務
│   └── Storage/              # 多媒體儲存服務
└── Vocabulary/                # 詞彙相關服務
    └── Options/              # 選項詞彙服務
```

---

## 🤖 AI 服務 (Services/AI/)

### AI 分析服務組 (AI/Analysis/)
| 服務名稱 | 功能說明 | 檔案位置 |
|---------|---------|----------|
| `AnalysisService` | 綜合分析服務 (帶快取) | `AnalysisService.cs` |
| `IGeminiAnalyzer` | Gemini 分析器介面 | `IGeminiAnalyzer.cs` |

### Gemini 服務組 (AI/Gemini/)
**主要 Facade 服務**: `GeminiService` - 統一的 Gemini AI 功能入口

| 服務名稱 | 功能說明 | 檔案位置 |
|---------|---------|----------|
| `GeminiClient` | Gemini API HTTP 通訊客戶端 | `GeminiClient.cs` |
| `SentenceAnalyzer` | 句子語意分析服務 | `SentenceAnalyzer.cs` |
| `ImageDescriptionGenerator` | 圖片描述生成服務 | `ImageDescriptionGenerator.cs` |

**使用範例**:
```csharp
// 注入主要服務
private readonly IGeminiService _geminiService;

// 分析句子
var analysis = await _geminiService.AnalyzeSentenceAsync(text, options);

// 生成圖片描述
var description = await _geminiService.GenerateImageDescriptionAsync(flashcard, options);
```

### 圖片生成服務組 (AI/Generation/)
**主要 Facade 服務**: `ImageGenerationOrchestrator` - 圖片生成工作流程協調器

| 服務名稱 | 功能說明 | 檔案位置 |
|---------|---------|----------|
| `ImageGenerationWorkflow` | 主要圖片生成工作流程 | `ImageGenerationWorkflow.cs` |
| `GenerationStateManager` | 生成狀態管理 | `GenerationStateManager.cs` |
| `ImageSaveManager` | 圖片儲存管理 | `ImageSaveManager.cs` |
| `GenerationPipelineService` | 生成管道服務 | `GenerationPipelineService.cs` |

---

## 🔧 核心服務 (Services/Core/)

### 認證服務 (Core/Auth/)
| 服務名稱 | 功能說明 | 檔案位置 |
|---------|---------|----------|
| `AuthService` | 用戶認證和授權服務 | `AuthService.cs` |

---

## 🏗️ 基礎設施服務 (Services/Infrastructure/)

### 快取服務組 (Infrastructure/Caching/)
**主要 Facade 服務**: `HybridCacheService` - 混合快取服務

| 服務名稱 | 功能說明 | 檔案位置 |
|---------|---------|----------|
| `MemoryCacheProvider` | 記憶體快取提供者 | `MemoryCacheProvider.cs` |
| `DistributedCacheProvider` | 分散式快取提供者 | `DistributedCacheProvider.cs` |
| `JsonCacheSerializer` | JSON 快取序列化器 | `JsonCacheSerializer.cs` |
| `CacheStrategyManager` | 快取策略管理器 | `CacheStrategyManager.cs` |
| `DatabaseCacheManager` | 資料庫快取管理器 | `DatabaseCacheManager.cs` |

**快取架構特色**:
- **混合快取**: 結合記憶體和分散式快取
- **策略模式**: 可動態切換快取策略
- **序列化支援**: JSON 格式序列化
- **資料庫整合**: 支援資料庫層快取

### 監控服務組 (Infrastructure/Monitoring/)
| 服務名稱 | 功能說明 | 檔案位置 |
|---------|---------|----------|
| `UsageTrackingService` | 使用追蹤服務 | `UsageTrackingService.cs` |
| `OptionsVocabularyMetrics` | 選項詞彙指標服務 | `OptionsVocabularyMetrics.cs` |

---

## 📁 媒體服務 (Services/Media/)

### 音訊服務 (Media/Audio/)
| 服務名稱 | 功能說明 | 檔案位置 |
|---------|---------|----------|
| `AudioCacheService` | 音訊快取服務 | `AudioCacheService.cs` |
| `AzureSpeechService` | Azure 語音服務 | `AzureSpeechService.cs` |

### 圖片服務 (Media/Image/)
| 服務名稱 | 功能說明 | 檔案位置 |
|---------|---------|----------|
| `ImageProcessingService` | 圖片處理服務 | `ImageProcessingService.cs` |

### 儲存服務 (Media/Storage/)
| 服務名稱 | 功能說明 | 檔案位置 |
|---------|---------|----------|
| `LocalImageStorageService` | 本地圖片儲存服務 | `LocalImageStorageService.cs` |

---

## 📚 詞彙服務 (Services/Vocabulary/)

### 選項詞彙服務 (Vocabulary/Options/)
| 服務名稱 | 功能說明 | 檔案位置 |
|---------|---------|----------|
| `OptionsVocabularyService` | 選項型詞彙服務 | `OptionsVocabularyService.cs` |

---

## 🌐 外部服務整合

### Replicate 服務
| 服務名稱 | 功能說明 | 檔案位置 |
|---------|---------|----------|
| `ReplicateService` | Replicate AI 平台整合服務 | `ReplicateService.cs` |

---

## 🔄 服務註冊與依賴注入

所有服務都在 `Extensions/ServiceCollectionExtensions.cs` 中統一註冊：

```csharp
// AI 服務
services.AddAIServices(configuration);

// 業務服務
services.AddBusinessServices();

// 快取服務
services.AddCachingServices();

// Repository 服務
services.AddRepositoryServices();
```

## ⚡ 效能優化特色

1. **Facade Pattern**: 每個服務群組都有統一入口，簡化使用
2. **組合模式**: 複雜服務由多個小型服務組合而成
3. **異步優先**: 所有 I/O 操作都使用異步方法
4. **快取支援**: 關鍵服務集成智能快取機制
5. **依賴注入**: 完全支援 DI 容器，便於測試和維護

## 🧪 重構成果

### 重構前 vs 重構後對比

| 服務 | 重構前行數 | 重構後服務數 | 改善程度 |
|------|-----------|-------------|----------|
| `ImageGenerationOrchestrator` | 425 行 | 6 個服務 | 職責明確化 |
| `HybridCacheService` | 538 行 | 8 個服務 | 策略模式 |
| `GeminiService` | 584 行 | 4 個服務 | Facade 簡化 |

### 架構優勢
- ✅ **可測試性**: 每個服務職責單一，易於單元測試
- ✅ **可維護性**: 程式碼模組化，修改影響範圍小
- ✅ **可擴展性**: 新功能開發更便捷
- ✅ **可讀性**: 服務命名清晰，職責明確

---

## 📖 開發指南

### 新增服務步驟
1. 選擇適當的領域目錄 (AI/Core/Infrastructure/Media 等)
2. 建立介面檔案 `I{ServiceName}.cs`
3. 建立實作檔案 `{ServiceName}.cs`
4. 在 `ServiceCollectionExtensions.cs` 註冊服務
5. 更新本索引文檔

### 命名規範
- **介面**: `I{ServiceName}` (例: `IGeminiService`)
- **實作**: `{ServiceName}` (例: `GeminiService`)
- **Facade 服務**: 保持原有名稱，作為主要入口點

---

**版本**: 1.1
**最後更新**: 2025-09-30
**維護者**: DramaLing 開發團隊
**重構日期**: 2025-09-29 ~ 2025-09-30
**索引完善**: 2025-09-30 (階段三完成)