209 lines
7.4 KiB
Markdown
209 lines
7.4 KiB
Markdown
# 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 (階段三完成) |