History

鄭沛軒 e8ab42dfd7 feat: 實現 /api/flashcards/due API 完整功能 ✨ 新增功能 - 建立 FlashcardReview 實體與資料庫表格 - 實現間隔重複算法 (2^n 天公式) - 支援信心度評估系統 (0=答錯, 1-2=答對) - 完整的複習統計與進度追蹤 🔧 技術實作 - FlashcardReviewRepository: 優化查詢避免 SQLite APPLY 限制 - ReviewService: 業務邏輯與算法實現 - FlashcardsController: 新增 GET /due 和 POST /{id}/review 端點 - 資料庫遷移與索引優化 📊 API 功能 - 支援查詢參數: limit, includeToday, includeOverdue, favoritesOnly - 返回格式完全兼容前端 api_seeds.json 結構 - 包含完整 reviewInfo 複習狀態信息 - API 已測試確認在 http://localhost:5000 正常運作 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>		2025-10-06 20:49:40 +08:00
..
AI	feat: 修復圖片生成服務 + 統一播放按鈕設計 + API 完善	2025-10-02 03:58:03 +08:00
Core/Auth	refactor: 完成 Services 層架構重組，實施功能域分層設計	2025-09-30 01:49:42 +08:00
Infrastructure	feat: 階段三 Services 文檔化完成 - 統一命名與完整索引	2025-09-30 03:53:53 +08:00
Media	refactor: 完成 Services 層架構重組，實施功能域分層設計	2025-09-30 01:49:42 +08:00
Review	feat: 實現 /api/flashcards/due API 完整功能	2025-10-06 20:49:40 +08:00
Vocabulary/Options	feat: 完成AI詞彙保存功能修復與前端架構優化	2025-10-01 02:29:09 +08:00
README.md	feat: 階段三 Services 文檔化完成 - 統一命名與完整索引	2025-09-30 03:53:53 +08:00

README.md

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`

使用範例:

// 注入主要服務
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 中統一註冊：

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

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

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

// Repository 服務
services.AddRepositoryServices();

⚡ 效能優化特色

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

🧪 重構成果

重構前 vs 重構後對比

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

架構優勢

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

📖 開發指南

新增服務步驟

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

命名規範

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

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