296 lines
7.2 KiB
Markdown
296 lines
7.2 KiB
Markdown
# 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 |