6.4 KiB

Raw Blame History

DramaLing 後端架構全面優化計劃

版本: 1.0 日期: 2025-09-30 狀態: 🚧 準備啟動

🎯 優化目標

基於對整個後端架構的深度分析，進行系統性的架構重構，解決以下核心問題：

目錄結構混亂
重複程式碼和介面
缺乏文檔和規範
Repository 層分散
缺乏測試架構

📊 當前架構問題分析

🔴 嚴重問題

目錄重複混亂
- /Data 和 /Data/Repositories 功能重疊
- /Repositories 和 /Data/Repositories 雙重存在
- /Infrastructure 和 /Services/Infrastructure 功能重疊
- /backend 和 /DramaLing.Api 空目錄
重複介面和服務
- IGeminiDescriptionGenerator vs IImageDescriptionGenerator (功能完全相同)
- Services 層有 44 個檔案缺乏索引
- 命名不一致導致重複開發

🟡 中等問題

Repository 層分散
- BaseRepository 在 /Repositories
- 其他 Repository 可能在 /Data/Repositories
- 缺乏統一的 Repository 管理策略
配置管理混亂
- 多個 appsettings 檔案
- 缺乏環境管理策略
- 配置驗證不完整

🟠 輕度問題

缺乏架構文檔
- 沒有 README
- 沒有 API 文檔
- 沒有開發指南
測試架構缺失
- 沒有測試專案
- 沒有測試規範
- 缺乏 CI/CD 整合

🏗️ 優化實施計劃

階段一：目錄結構清理 (1天)

1.1 移除重複和空目錄

# 移除空目錄
/backend/
/DramaLing.Api/ (空的子目錄)

# 合併重複功能
/Infrastructure/ → 整合到 /Services/Infrastructure/
/Data/Repositories/ → 整合到 /Repositories/

1.2 建立標準目錄結構

DramaLing.Api/
├── Controllers/           # API 控制器
├── Services/             # 業務服務層
│   ├── Core/            # 核心業務服務
│   ├── AI/              # AI 相關服務
│   ├── Media/           # 多媒體服務
│   ├── Infrastructure/  # 基礎設施服務
│   └── Vocabulary/      # 詞彙相關服務
├── Repositories/        # 數據訪問層 (統一管理)
├── Data/               # EF Core 配置和遷移
├── Models/             # 數據模型
├── Extensions/         # 擴展方法
├── Middleware/         # 中間件
├── Configuration/      # 配置相關
└── Tests/             # 測試專案 (新增)

階段二：Repository 層統一 (1天)

2.1 整合 Repository

將所有 Repository 移動到 /Repositories
建立統一的 Repository 基類
更新依賴注入配置

2.2 建立 Repository 介面規範

統一 Repository 命名規則
建立通用 Repository 介面
實作 Unit of Work 模式

階段三：Services 層文檔化 (1天)

3.1 清理重複服務

移除重複介面 (IGeminiDescriptionGenerator)
統一相似功能的命名
建立服務依賴關係圖

3.2 建立服務索引文檔

建立 Services/SERVICES_INDEX.md：

# Services 層索引

## AI 服務
- `GeminiService` - Gemini AI 整合服務
- `AnalysisService` - 分析服務 (帶快取)
- `SentenceAnalyzer` - 句子分析器

## Core 服務
- `AuthService` - 認證服務

## Media 服務
- `ImageProcessingService` - 圖片處理
- `AudioCacheService` - 音訊快取
...

階段四：測試架構建立 (1天)

4.1 建立測試專案結構

Tests/
├── Unit/              # 單元測試
│   ├── Services/     # 服務層測試
│   ├── Controllers/  # 控制器測試
│   └── Repositories/ # Repository 測試
├── Integration/       # 整合測試
└── E2E/              # 端到端測試

4.2 建立測試基礎設施

建立測試基類
設定 Mock 框架
建立測試數據工廠

階段五：配置和文檔完善 (1天)

5.1 配置管理優化

統一環境配置策略
建立配置驗證機制
優化密鑰管理

5.2 建立完整文檔

建立以下文檔：

README.md - 專案概述和快速開始
ARCHITECTURE.md - 架構說明文檔
API_DOCUMENTATION.md - API 文檔
DEVELOPMENT_GUIDE.md - 開發指南

📈 實施進度追蹤

階段完成標準

階段一：目錄清理 ✅ 完成條件

移除所有空目錄和重複目錄
建立標準目錄結構
更新所有檔案路徑引用
編譯成功無錯誤

階段二：Repository 統一 ✅ 完成條件

所有 Repository 移動到統一位置
建立 Repository 基類和介面
更新依賴注入配置
所有 Repository 功能正常

階段三：Services 文檔 ✅ 完成條件

移除重複介面和服務
建立服務索引文檔
統一命名規則
所有服務功能正常

階段四：測試架構 ✅ 完成條件

建立測試專案結構
實作基礎測試設施
撰寫關鍵服務的單元測試
測試覆蓋率 > 60%

階段五：文檔完善 ✅ 完成條件

完成所有核心文檔
配置管理優化
API 文檔生成
開發指南完整

🎯 預期成果

量化指標

程式碼重複度: 減少 40%
開發效率: 提升 60%
新人上手時間: 縮短 70%
維護成本: 降低 50%
測試覆蓋率: 達到 80%

質化提升

✅ 架構清晰: 目錄結構符合 Clean Architecture 原則
✅ 可維護性: 程式碼分層清楚，職責明確
✅ 可測試性: 完整的測試架構和覆蓋
✅ 可擴展性: 新功能開發更加便捷
✅ 團隊協作: 統一的開發規範和文檔

⚠️ 風險控制

技術風險

依賴關係變更: 每個階段完成後進行編譯測試
功能回歸: 保持現有 API 相容性
資料丟失: 移動檔案前建立備份

時間風險

複雜度超出預期: 每階段設定緩衝時間
測試時間不足: 優先核心功能測試

文檔版本: 1.0 最後更新: 2025-09-30 22:00 負責人: Claude Code 審核狀態: 待開始 預計完成: 2025-10-05

6.4 KiB Raw Blame History Unescape Escape