# 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 專案**
   ```bash
   git clone <repository-url>
   cd dramaling-vocab-learning/backend/DramaLing.Api
   ```

2. **安裝依賴**
   ```bash
   dotnet restore
   ```

3. **配置環境變數**
   ```bash
   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. **執行資料庫遷移**
   ```bash
   dotnet ef database update
   ```

5. **啟動開發伺服器**
   ```bash
   dotnet run
   ```

6. **訪問 Swagger UI**
   ```
   https://localhost:7001/swagger
   ```

---

## 📚 文檔索引

### 架構文檔
- **[Services 層索引](./Services/README.md)** - 服務層完整說明
- **[Repository 層說明](./Repositories/README.md)** - 數據訪問層文檔
- **[測試架構指南](./Tests/README.md)** - 測試框架和策略
- **[配置管理說明](./Configuration/README.md)** - 配置和環境管理

### 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 使用範例
```bash
# 設定認證 Token
export TOKEN="your-jwt-token"

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

---

## 📊 效能特色

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

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

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

---

## 🧪 測試

### 執行測試
```bash
# 執行所有測試
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

---

## 🔗 相關連結

- [前端專案](../frontend/) - React + Next.js 前端應用
- [部署文檔](./docs/deployment.md) - 部署指南
- [API 文檔](https://localhost:7001/swagger) - 線上 API 文檔

---

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