dramaling-vocab-learning/backend/DramaLing.Api

DramaLing API

版本: 1.0 框架: ASP.NET Core 8.0 架構: Clean Architecture + Domain-Driven Design

🚀 專案概述

DramaLing API 是一個英語學習平台的後端服務，提供 AI 驅動的句子分析、圖片生成、語音合成等功能。採用現代化的 .NET 8 架構，遵循 Clean Architecture 和 Domain-Driven Design 原則。

核心功能

• 🤖 AI 語言分析: 基於 Gemini AI 的句子語意分析
• 🎨 智能圖片生成: 結合 Replicate AI 的插畫生成
• 🎵 語音合成: Azure Speech Services 整合
• 📚 詞彙管理: 智能單字卡系統
• 🔐 用戶認證: Supabase JWT 認證
• 💾 混合快取: 記憶體 + 分散式快取策略

---

📁 專案架構

DramaLing.Api/
├── Controllers/           # API 控制器
├── Services/             # 業務服務層
│   ├── AI/              # AI 相關服務
│   ├── Core/            # 核心業務服務
│   ├── Infrastructure/  # 基礎設施服務
│   ├── Media/           # 多媒體服務
│   ├── Storage/         # 儲存服務
│   └── Vocabulary/      # 詞彙服務
├── Repositories/         # 數據訪問層
├── Data/                # Entity Framework 配置
├── Models/              # 數據模型
│   ├── Entities/        # 實體模型
│   ├── DTOs/            # 數據傳輸物件
│   └── Configuration/   # 配置類別
├── Extensions/          # 擴展方法
├── Middleware/          # 中間件
├── Configuration/       # 配置說明
└── Tests/              # 測試專案

---

🔧 技術棧

核心框架

• .NET 8: 最新 LTS 版本
• ASP.NET Core 8: Web API 框架
• Entity Framework Core: ORM 數據訪問
• SQLite: 輕量級資料庫

外部服務整合

• Gemini AI: 語言理解和分析
• Replicate AI: 圖片生成服務
• Azure Speech Services: 語音合成
• Supabase: 用戶認證和資料庫

架構模式

• Clean Architecture: 分層架構設計
• Repository Pattern: 數據訪問抽象
• Facade Pattern: 服務組合簡化
• Strategy Pattern: 快取策略管理

---

🚀 快速開始

系統需求

• .NET 8 SDK
• SQLite (或 SQL Server for production)

安裝步驟

1. Clone 專案

   git clone <repository-url>
   cd dramaling-vocab-learning/backend/DramaLing.Api
   

2. 安裝依賴

   dotnet restore
   

3. 配置環境變數

   export DRAMALING_GEMINI_API_KEY="your-gemini-api-key"
   export DRAMALING_SUPABASE_URL="your-supabase-url"
   export DRAMALING_SUPABASE_JWT_SECRET="your-jwt-secret"
   

4. 執行資料庫遷移

   dotnet ef database update
   

5. 啟動開發伺服器

   dotnet run
   

6. 訪問 Swagger UI

   https://localhost:7001/swagger
   

---

📚 文檔索引

架構文檔

• Services 層索引 - 服務層完整說明
• Repository 層說明 - 數據訪問層文檔
• 測試架構指南 - 測試框架和策略
• 配置管理說明 - 配置和環境管理

API 文檔

• Swagger UI: /swagger - 交互式 API 文檔
• OpenAPI 規範: /swagger/v1/swagger.json - API 規範檔案

---

🏗️ 服務架構概覽

AI 服務群組

• GeminiService (Facade) → 統一 AI 功能入口
  • SentenceAnalyzer → 句子語意分析
  • ImageDescriptionGenerator → 圖片描述生成
  • GeminiClient → API 通訊客戶端

圖片生成服務群組

• ImageGenerationOrchestrator (Facade) → 圖片生成協調器
  • ImageGenerationWorkflow → 主要生成流程
  • GenerationStateManager → 狀態管理
  • ImageSaveManager → 圖片儲存管理

快取服務群組

• HybridCacheService (Facade) → 混合快取服務
  • MemoryCacheProvider → 記憶體快取
  • DistributedCacheProvider → 分散式快取
  • CacheStrategyManager → 快取策略管理

---

🔒 認證與授權

JWT 認證流程

1. 用戶透過 Supabase 登入
2. 取得 JWT Token
3. API 請求時在 Header 攜帶 Token
4. 中間件驗證 Token 有效性

API 使用範例

# 設定認證 Token
export TOKEN="your-jwt-token"

# 呼叫受保護的 API
curl -H "Authorization: Bearer $TOKEN" \
     https://localhost:7001/api/analysis/sentence

---

📊 效能特色

快取策略

• 記憶體快取: 熱點資料快速存取
• 分散式快取: 跨實例資料共享
• 資料庫快取: 查詢結果暫存

異步處理

• 所有 I/O 操作都採用異步模式
• AI API 呼叫採用非阻塞設計
• 圖片生成支援背景處理

架構優勢

• 模組化設計: 服務間低耦合
• 可測試性: 完整的依賴注入支援
• 可擴展性: 新功能易於集成

---

🧪 測試

執行測試

# 執行所有測試
dotnet test

# 執行特定類型測試
dotnet test --filter "Category=Unit"

# 產生覆蓋率報告
dotnet test --collect:"XPlat Code Coverage"

測試覆蓋範圍

• 單元測試: 服務層邏輯測試
• 整合測試: API 端點測試
• 效能測試: 關鍵路徑基準測試

---

🔄 CI/CD

GitHub Actions

自動化構建、測試、部署流程：

• 程式碼品質檢查
• 單元測試執行
• 安全性掃描
• Docker 映像構建

部署環境

• 開發環境: 自動部署到測試伺服器
• 生產環境: 手動審核後部署

---

📈 監控與日誌

日誌等級

• Debug: 開發除錯資訊
• Information: 正常業務流程
• Warning: 潛在問題警告
• Error: 錯誤和例外

效能監控

• API 回應時間監控
• 資料庫查詢性能追蹤
• 快取命中率統計

---

🔧 開發指南

新增功能步驟

1. 在適當的 Services 子目錄建立服務
2. 實作介面和具體類別
3. 在 ServiceCollectionExtensions 註冊服務
4. 撰寫單元測試
5. 更新相關文檔

程式碼規範

• 遵循 C# 編程慣例
• 使用 async/await 進行異步操作
• 適當的錯誤處理和日誌記錄
• 完整的 XML 文檔註解

---

🤝 貢獻指南

提交流程

1. Fork 專案並建立功能分支
2. 遵循程式碼規範撰寫代碼
3. 確保所有測試通過
4. 提交 Pull Request

問題回報

請使用 GitHub Issues 回報問題，包含：

• 問題描述
• 重現步驟
• 預期行為
• 實際結果

---

📄 授權

本專案採用 MIT 授權協議。

---

👥 開發團隊

維護者: DramaLing 開發團隊 架構重構: 2025-09-29 ~ 2025-09-30 最後更新: 2025-09-30

---

🔗 相關連結

• 前端專案 - React + Next.js 前端應用
• 部署文檔 - 部署指南
• API 文檔 - 線上 API 文檔

---

🎯 專案狀態: 生產就緒 📊 測試覆蓋率: 目標 80%+ 🚀 架構版本: Clean Architecture 2.0