dramaling-vocab-learning/docs/03_development/dotnet-completion-plan.md

# .NET Core 後端完成計劃

## 📊 專案現狀分析

### ✅ **已完成項目 (約30%)**

#### 基礎架構
- **Entity Framework 模型**:
  - 檔案位置: `backend/DramaLing.Api/Models/Entities/`
  - 已實作: `User.cs`, `Flashcard.cs`, `CardSet.cs`, `StudySession.cs`, `Tag.cs`
  - 狀態: ✅ 完成

- **資料庫上下文**:
  - 檔案位置: `backend/DramaLing.Api/Data/DramaLingDbContext.cs`
  - 功能: Entity Framework 配置、關聯設定、欄位映射
  - 狀態: ✅ 完成

- **SM-2 學習算法**:
  - 檔案位置: `backend/DramaLing.Api/Services/SM2Algorithm.cs`
  - 功能: 間隔重複算法、掌握度計算、優先級排序
  - 狀態: ✅ 完成

#### 部分 API 控制器
- **CardSetsController**: `backend/DramaLing.Api/Controllers/CardSetsController.cs`
  - 實作端點: GET, POST, PUT, DELETE `/api/cardsets`
  - 支援功能: 卡組 CRUD 操作
  - 狀態: ✅ 完成

- **FlashcardsController**: `backend/DramaLing.Api/Controllers/FlashcardsController.cs`
  - 實作端點: GET, POST, PUT, DELETE `/api/flashcards`
  - 支援功能: 詞卡 CRUD、搜尋篩選
  - 狀態: ✅ 完成

- **StatsController**: `backend/DramaLing.Api/Controllers/StatsController.cs`
  - 實作端點: GET `/api/stats/dashboard`, GET `/api/stats/trends`, GET `/api/stats/detailed`
  - 支援功能: 基礎統計分析
  - 狀態: ✅ 完成

#### 專案配置
- **啟動配置**: `backend/DramaLing.Api/Program.cs`
  - 功能: 依賴注入、中介軟體配置、Swagger 設定
  - 狀態: ✅ 完成

- **應用設定**: `backend/DramaLing.Api/appsettings.json`, `appsettings.Development.json`
  - 功能: 資料庫連接、AI 服務配置
  - 狀態: ✅ 完成 (需要填入實際金鑰)

### ⚠️ **缺失項目 (約70%)**

根據前端需求分析 (參考: [前端實作程式碼](/frontend/app/)) 和 [功能需求規格書](/docs/01_requirement/functional-requirements.md)，以下功能仍需實作：

## 🔐 需要實作：AuthController (優先級: 🔥 最高)

### 功能需求
**支援前端頁面**:
- `/frontend/app/login/page.tsx` - 登入頁面
- `/frontend/app/register/page.tsx` - 註冊頁面
- `/frontend/app/dashboard/page.tsx` - 用戶資料顯示

### API 端點需求
```csharp
[Route("api/[controller]")]
public class AuthController : ControllerBase
{
    [HttpGet("profile")]           // 獲取用戶資料
    [HttpPut("profile")]           // 更新用戶資料
    [HttpGet("settings")]          // 獲取用戶設定
    [HttpPut("settings")]          // 更新用戶設定
}
```

### 技術實作需求
- **JWT 令牌驗證**: 與 Supabase Auth 兼容
- **用戶資料管理**: user_profiles 表 CRUD
- **設定管理**: user_settings 表 CRUD
- **錯誤處理**: 401 未授權、404 用戶不存在

### 相關檔案參考
- 資料模型: `backend/DramaLing.Api/Models/Entities/User.cs` ✅ 已完成
- 前端需求: `frontend/app/dashboard/page.tsx:87-94` (統計卡片)

## 🧠 需要實作：StudyController (優先級: 🔥 高)

### 功能需求
**支援前端頁面**:
- `/frontend/app/learn/page.tsx` - 學習頁面 (五種學習模式)
- `/frontend/app/dashboard/page.tsx` - 學習進度顯示

### API 端點需求
```csharp
[Route("api/[controller]")]
public class StudyController : ControllerBase
{
    [HttpGet("due-cards")]                          // 獲取待複習詞卡
    [HttpGet("schedule")]                           // 複習排程
    [HttpPost("sessions")]                          // 開始學習會話
    [HttpPost("sessions/{sessionId}/record")]       // 記錄學習結果
    [HttpPost("sessions/{sessionId}/complete")]     // 完成學習會話
}
```

### 技術實作需求
- **SM-2 算法整合**: 使用 `Services/SM2Algorithm.cs` ✅ 已完成
- **學習記錄追蹤**: study_sessions, study_records 表操作
- **複習排程**: 基於 SM-2 的智能排程
- **統計更新**: 自動更新每日統計

### 相關檔案參考
- 算法實作: `backend/DramaLing.Api/Services/SM2Algorithm.cs` ✅ 已完成
- 資料模型: `backend/DramaLing.Api/Models/Entities/StudySession.cs` ✅ 已完成
- 前端需求: `frontend/app/learn/page.tsx:77-117` (學習模式和記錄)

## 🤖 需要實作：AIController (優先級: 🔥 高)

### 功能需求
**支援前端頁面**:
- `/frontend/app/generate/page.tsx` - AI 生成頁面
- `/frontend/app/flashcards/page.tsx` - 智能檢測功能

### API 端點需求
```csharp
[Route("api/[controller]")]
public class AIController : ControllerBase
{
    [HttpPost("generate")]                    // AI 生成詞卡
    [HttpGet("generate/{taskId}")]           // 查詢生成進度
    [HttpPost("generate/{taskId}/save")]     // 保存生成結果
    [HttpPost("validate-card")]              // 智能檢測單一詞卡
    [HttpPost("validate-cards")]             // 批量智能檢測
    [HttpPost("apply-corrections")]          // 自動應用修正
}
```

### 技術實作需求
- **Google Gemini AI 整合**: 安裝 `Google.AI.GenerativeAI` NuGet 套件
- **Prompt 模板設計**: 詞彙萃取、智能萃取、內容檢測
- **非同步處理**: AI 生成任務的狀態管理
- **配額管理**: 每日生成限制 (免費用戶vs付費用戶)

### 相關檔案參考
- 前端生成流程: `frontend/app/generate/page.tsx:87-95` (AI 生成邏輯)
- 前端檢測功能: `frontend/app/flashcards/page.tsx:731-770` (智能檢測modal)

## 🏷️ 需要實作：TagsController (優先級: 🟡 中)

### 功能需求
**支援前端頁面**:
- `/frontend/app/flashcards/page.tsx` - 標籤篩選和管理

### API 端點需求
```csharp
[Route("api/[controller]")]
public class TagsController : ControllerBase
{
    [HttpGet]                    // 標籤列表
    [HttpPost]                   // 創建標籤
    [HttpPut("{id}")]           // 更新標籤
    [HttpDelete("{id}")]        // 刪除標籤
}
```

### 相關檔案參考
- 資料模型: `backend/DramaLing.Api/Models/Entities/Tag.cs` ✅ 已完成
- 前端需求: `frontend/app/flashcards/page.tsx:162` (標籤陣列)

## ⚠️ 需要實作：ErrorReportsController (優先級: 🟡 中)

### 功能需求
**支援前端頁面**:
- `/frontend/app/learn/page.tsx` - 各學習模式的錯誤回報
- `/frontend/app/flashcards/page.tsx` - 錯誤回報管理

### API 端點需求
```csharp
[Route("api/[controller]")]
public class ErrorReportsController : ControllerBase
{
    [HttpGet]                    // 錯誤回報列表
    [HttpPost]                   // 提交錯誤回報
    [HttpPut("{id}")]           // 處理回報狀態
    [HttpDelete("{id}")]        // 刪除回報
    [HttpPost("batch-process")]  // 批量處理
}
```

### 相關檔案參考
- 前端回報功能: `frontend/app/learn/page.tsx:775-851` (錯誤回報modal)
- 前端管理界面: `frontend/app/flashcards/page.tsx:15-43` (錯誤回報清單)

## 🗄️ 資料庫連接和遷移

### 需要完成的設定

#### 1. **Supabase 連接配置**
- **檔案位置**: `backend/DramaLing.Api/appsettings.Development.json`
- **需要填入**: 實際的 Supabase 連接資訊
- **參考文檔**: [環境設定指南](/docs/03_development/setup/env-setup.md)

#### 2. **Entity Framework 遷移**
```bash
cd backend/DramaLing.Api
dotnet ef migrations add InitialCreate
dotnet ef database update
```

#### 3. **測試資料播種**
- 建立初始測試用戶
- 新增範例詞卡和卡組
- 設定預設標籤

## 🌐 前端 API 整合

### 需要修改的檔案

#### 1. **API 基礎設定**
**檔案**: `frontend/app/` 下所有頁面
**修改**: API 調用基礎 URL
```typescript
// 原本
const response = await fetch('/api/flashcards')

// 修改為
const response = await fetch('http://localhost:5000/api/flashcards')
```

#### 2. **認證令牌處理**
**檔案**: 所有需要認證的 API 調用
**修改**: 附加 JWT 令牌
```typescript
const response = await fetch(url, {
    headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
    }
})
```

#### 3. **錯誤處理更新**
**檔案**: 前端錯誤處理邏輯
**修改**: 適配 .NET Core 的錯誤回應格式

## 📋 實作順序建議

### Week 1: 核心功能
1. **AuthController** (2-3天)
   - 實作用戶認證相關 API
   - 整合 JWT 驗證

2. **資料庫連接設定** (1天)
   - 配置 Supabase 連接
   - 執行 Entity Framework 遷移

3. **基礎測試** (1天)
   - 測試 API 端點
   - 驗證資料庫連接

### Week 2: 學習和 AI 系統
1. **StudyController** (3-4天)
   - 學習會話管理
   - SM-2 算法整合
   - 複習排程

2. **AIController** (2-3天)
   - Google Gemini AI 整合
   - 詞卡生成和檢測

### Week 3: 進階功能和整合
1. **TagsController & ErrorReportsController** (2天)
   - 標籤管理
   - 錯誤回報系統

2. **前端 API 整合** (3-4天)
   - 更新前端 API 調用
   - 認證流程整合
   - 端到端測試

3. **效能優化** (1天)
   - 快取機制
   - 查詢優化

## 📚 相關文檔引用

### 需求文檔
- **[功能需求規格書](/docs/01_requirement/functional-requirements.md)** - 了解完整功能需求
- **[技術需求規格書](/docs/01_requirement/technical-requirements.md)** - 技術實作標準

### 設計文檔
- **[後端開發計劃](/docs/03_development/api/backend-development-plan.md)** - 整體架構和 API 設計
- **[專案結構指南](/docs/03_development/setup/folder-structure.md)** - 檔案組織原則

### 前端實作參考
- **[Dashboard 頁面](/frontend/app/dashboard/page.tsx)** - 統計 API 需求
- **[學習頁面](/frontend/app/learn/page.tsx)** - 學習系統 API 需求
- **[詞卡管理](/frontend/app/flashcards/page.tsx)** - 詞卡管理 API 需求
- **[AI 生成](/frontend/app/generate/page.tsx)** - AI 生成 API 需求

### 技術實作文檔
- **[.NET 重寫計劃](/docs/03_development/dotnet-rewrite-plan.md)** - 重寫決策和架構說明
- **[環境設定指南](/docs/03_development/setup/env-setup.md)** - 環境變數配置

## 🎯 成功標準

### 功能完整性檢查清單

#### 🔐 認證系統
- [x] 用戶可以檢視個人資料 (`/api/auth/profile`) - AuthController 已實作
- [x] 用戶可以更新設定 (`/api/auth/settings`) - AuthController 已實作
- [x] JWT 令牌驗證正常運作 - 支援環境變數配置
- [ ] 前端登入狀態同步 - 需要前端 API 整合

#### 📚 詞卡管理
- [x] 卡組 CRUD 操作正常
- [x] 詞卡 CRUD 操作正常
- [ ] 標籤系統完整運作
- [ ] 批量操作功能

#### 🧠 學習系統
- [x] 五種學習模式支援 (翻卡、選擇題、填空、聽力、口說) - StudyController 已實作
- [x] SM-2 算法正確計算複習間隔 - SM2Algorithm 服務已完成
- [x] 學習進度正確追蹤和統計 - 學習記錄和統計更新
- [x] 複習排程智能推薦 - 複習排程 API 已實作

#### 🤖 AI 功能
- [x] 詞卡生成功能正常 (詞彙萃取、智能萃取) - AIController 已實作 (Mock 模式)
- [x] 智能檢測可以發現詞卡錯誤 - 驗證 API 已實作
- [x] 批量檢測和自動修正 - GeminiService 已完成
- [x] 生成任務狀態管理 - 生成和保存流程已實作

#### 📊 統計分析
- [x] 儀表板基礎統計 - StatsController 已實作
- [x] 學習趨勢分析 - 趨勢 API 已完成
- [x] 詳細統計報告 - 詳細統計 API 已實作
- [x] 進度預測功能 - 預測算法已實作

#### ⚠️ 錯誤管理
- [ ] 錯誤回報提交和管理
- [ ] 錯誤回報狀態追蹤
- [ ] 批量處理功能

### 技術品質檢查

#### 🏗️ 程式碼品質
- [ ] 移除所有編譯警告 (目前14個 `unused variable` 警告)
- [ ] 統一錯誤處理格式
- [ ] API 回應格式標準化
- [ ] 輸入驗證完整性

#### 🔒 安全性
- [ ] 所有 API 端點都有適當的認證保護
- [ ] 用戶只能存取自己的資料 (資料隔離)
- [ ] 輸入驗證防止注入攻擊
- [ ] Rate Limiting 實作

#### 📈 效能
- [ ] 資料庫查詢優化
- [ ] API 回應時間 < 200ms
- [ ] 快取機制實作 (可選)

## 🛠️ 詳細實作指南

### 第一步：AuthController 實作

#### 建立檔案
**檔案位置**: `backend/DramaLing.Api/Controllers/AuthController.cs`

#### 實作重點
1. **JWT 令牌解析**: 從 Supabase 令牌中提取用戶 ID
2. **用戶資料管理**: 操作 user_profiles 表
3. **設定管理**: 操作 user_settings 表，提供預設值
4. **錯誤處理**: 統一的錯誤回應格式

#### 相依服務
- **DbContext**: 已完成 `Data/DramaLingDbContext.cs`
- **User 模型**: 已完成 `Models/Entities/User.cs`

### 第二步：StudyController 實作

#### 建立檔案
**檔案位置**: `backend/DramaLing.Api/Controllers/StudyController.cs`

#### 實作重點
1. **複習排程**: 使用 SM-2 算法計算待複習詞卡
2. **學習會話**: 管理學習狀態和進度
3. **學習記錄**: 記錄用戶回答和更新 SM-2 參數
4. **統計更新**: 自動更新每日學習統計

#### 相依服務
- **SM2Algorithm**: 已完成 `Services/SM2Algorithm.cs`
- **StudySession 模型**: 已完成 `Models/Entities/StudySession.cs`

### 第三步：AIController 實作

#### 建立檔案
**檔案位置**: `backend/DramaLing.Api/Controllers/AIController.cs`
**服務檔案**: `backend/DramaLing.Api/Services/GeminiService.cs`

#### 實作重點
1. **Google Gemini API 整合**: 使用官方 .NET SDK
2. **Prompt 模板**: 詞彙萃取和智能萃取的提示詞
3. **非同步處理**: AI 生成任務的狀態管理
4. **智能檢測**: 詞卡內容品質分析和修正建議

#### 需要的 NuGet 套件
```xml
<PackageReference Include="Google.AI.GenerativeAI" Version="1.0.0-beta" />
```

### 第四步：TagsController 和 ErrorReportsController

#### 實作重點
1. **標籤管理**: 標籤 CRUD 和使用統計
2. **錯誤回報**: 回報提交、狀態管理、批量處理
3. **關聯管理**: 詞卡與標籤的多對多關係

## 📊 完成度追蹤

### 當前進度: 30% → 目標: 100%

| 功能模組 | 進度 | 預估完成時間 |
|---------|------|-------------|
| 基礎架構 | ✅ 100% | 已完成 |
| 詞卡管理 | ✅ 100% | 已完成 |
| 卡組管理 | ✅ 100% | 已完成 |
| 統計分析 | ✅ 70% | 已完成基礎版 |
| 用戶認證 | ❌ 0% | 2-3天 |
| 學習系統 | ❌ 0% | 3-4天 |
| AI 服務 | ❌ 0% | 2-3天 |
| 標籤管理 | ❌ 0% | 1-2天 |
| 錯誤回報 | ❌ 0% | 1-2天 |
| 前端整合 | ❌ 0% | 2-3天 |

### 里程碑時間表

- **Week 1 結束**: AuthController + 資料庫連接 (50% 完成)
- **Week 2 結束**: StudyController + AIController (80% 完成)
- **Week 3 結束**: 前端整合 + 測試 (100% 完成)

## 🚀 下一步行動

### 立即可執行
1. **訪問 Swagger**: http://localhost:5000/swagger (查看當前 API)
2. **測試健康檢查**: http://localhost:5000/health
3. **查看前端**: http://localhost:3001 (確認 UI 功能)

### 開發建議
1. **先實作 AuthController**: 讓前端可以模擬登入
2. **配置資料庫連接**: 連接真實的 Supabase
3. **逐步實作其他控制器**: 按優先級順序進行

---

**參考文檔更新時間**: 2025-09-16
**專案狀態**: .NET Core 重寫進行中 (30% 完成)
**預計完成**: 2-3 週