15 KiB

Raw Permalink Blame History

.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%)

根據前端需求分析 (參考: 前端實作程式碼) 和功能需求規格書，以下功能仍需實作：

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

功能需求

支援前端頁面:

/frontend/app/login/page.tsx - 登入頁面
/frontend/app/register/page.tsx - 註冊頁面
/frontend/app/dashboard/page.tsx - 用戶資料顯示

API 端點需求

[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 用戶不存在

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

功能需求

支援前端頁面:

/frontend/app/learn/page.tsx - 學習頁面 (五種學習模式)
/frontend/app/dashboard/page.tsx - 學習進度顯示

API 端點需求

[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 的智能排程
統計更新: 自動更新每日統計

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

功能需求

支援前端頁面:

/frontend/app/generate/page.tsx - AI 生成頁面
/frontend/app/flashcards/page.tsx - 智能檢測功能

API 端點需求

[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付費用戶)

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

功能需求

支援前端頁面:

/frontend/app/flashcards/page.tsx - 標籤篩選和管理

API 端點需求

[Route("api/[controller]")]
public class TagsController : ControllerBase
{
    [HttpGet]                    // 標籤列表
    [HttpPost]                   // 創建標籤
    [HttpPut("{id}")]           // 更新標籤
    [HttpDelete("{id}")]        // 刪除標籤
}

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

功能需求

支援前端頁面:

/frontend/app/learn/page.tsx - 各學習模式的錯誤回報
/frontend/app/flashcards/page.tsx - 錯誤回報管理

API 端點需求

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

🗄️ 資料庫連接和遷移

需要完成的設定

1. Supabase 連接配置

檔案位置: backend/DramaLing.Api/appsettings.Development.json
需要填入: 實際的 Supabase 連接資訊
參考文檔: 環境設定指南

2. Entity Framework 遷移

cd backend/DramaLing.Api
dotnet ef migrations add InitialCreate
dotnet ef database update

3. 測試資料播種

建立初始測試用戶
新增範例詞卡和卡組
設定預設標籤

🌐 前端 API 整合

需要修改的檔案

1. API 基礎設定

檔案: frontend/app/ 下所有頁面修改: API 調用基礎 URL

// 原本
const response = await fetch('/api/flashcards')

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

2. 認證令牌處理

檔案: 所有需要認證的 API 調用修改: 附加 JWT 令牌

const response = await fetch(url, {
    headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
    }
})

3. 錯誤處理更新

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

📋 實作順序建議

Week 1: 核心功能

AuthController (2-3天)
- 實作用戶認證相關 API
- 整合 JWT 驗證
資料庫連接設定 (1天)
- 配置 Supabase 連接
- 執行 Entity Framework 遷移
基礎測試 (1天)
- 測試 API 端點
- 驗證資料庫連接

Week 2: 學習和 AI 系統

StudyController (3-4天)
- 學習會話管理
- SM-2 算法整合
- 複習排程
AIController (2-3天)
- Google Gemini AI 整合
- 詞卡生成和檢測

Week 3: 進階功能和整合

TagsController & ErrorReportsController (2天)
- 標籤管理
- 錯誤回報系統
前端 API 整合 (3-4天)
- 更新前端 API 調用
- 認證流程整合
- 端到端測試
效能優化 (1天)
- 快取機制
- 查詢優化

📚 相關文檔引用

需求文檔

功能需求規格書 - 了解完整功能需求
技術需求規格書 - 技術實作標準

設計文檔

後端開發計劃 - 整體架構和 API 設計
專案結構指南 - 檔案組織原則

前端實作參考

Dashboard 頁面 - 統計 API 需求
學習頁面 - 學習系統 API 需求
詞卡管理 - 詞卡管理 API 需求
AI 生成 - AI 生成 API 需求

技術實作文檔

.NET 重寫計劃 - 重寫決策和架構說明
環境設定指南 - 環境變數配置

🎯 成功標準

功能完整性檢查清單

🔐 認證系統

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

📚 詞卡管理

卡組 CRUD 操作正常
詞卡 CRUD 操作正常
標籤系統完整運作
批量操作功能

🧠 學習系統

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

🤖 AI 功能

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

📊 統計分析

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

⚠️ 錯誤管理

錯誤回報提交和管理
錯誤回報狀態追蹤
批量處理功能

技術品質檢查

🏗️ 程式碼品質

移除所有編譯警告 (目前14個 unused variable 警告)
統一錯誤處理格式
API 回應格式標準化
輸入驗證完整性

🔒 安全性

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

📈 效能

資料庫查詢優化
API 回應時間 < 200ms
快取機制實作 (可選)

🛠️ 詳細實作指南

第一步：AuthController 實作

建立檔案

檔案位置: backend/DramaLing.Api/Controllers/AuthController.cs

實作重點

JWT 令牌解析: 從 Supabase 令牌中提取用戶 ID
用戶資料管理: 操作 user_profiles 表
設定管理: 操作 user_settings 表，提供預設值
錯誤處理: 統一的錯誤回應格式

相依服務

DbContext: 已完成 Data/DramaLingDbContext.cs
User 模型: 已完成 Models/Entities/User.cs

第二步：StudyController 實作

建立檔案

檔案位置: backend/DramaLing.Api/Controllers/StudyController.cs

實作重點

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

相依服務

SM2Algorithm: 已完成 Services/SM2Algorithm.cs
StudySession 模型: 已完成 Models/Entities/StudySession.cs

第三步：AIController 實作

建立檔案

檔案位置: backend/DramaLing.Api/Controllers/AIController.cs 服務檔案: backend/DramaLing.Api/Services/GeminiService.cs

實作重點

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

需要的 NuGet 套件

<PackageReference Include="Google.AI.GenerativeAI" Version="1.0.0-beta" />

第四步：TagsController 和 ErrorReportsController

實作重點

標籤管理: 標籤 CRUD 和使用統計
錯誤回報: 回報提交、狀態管理、批量處理
關聯管理: 詞卡與標籤的多對多關係

📊 完成度追蹤

當前進度: 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% 完成)

🚀 下一步行動

立即可執行

訪問 Swagger: http://localhost:5000/swagger (查看當前 API)
測試健康檢查: http://localhost:5000/health
查看前端: http://localhost:3001 (確認 UI 功能)

開發建議

先實作 AuthController: 讓前端可以模擬登入
配置資料庫連接: 連接真實的 Supabase
逐步實作其他控制器: 按優先級順序進行

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

15 KiB Raw Permalink Blame History Unescape Escape

.NET Core 後端完成計劃

📊 專案現狀分析

✅ 已完成項目 (約30%)

基礎架構

部分 API 控制器

專案配置

⚠️ 缺失項目 (約70%)

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

功能需求

API 端點需求

技術實作需求

相關檔案參考

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

功能需求

API 端點需求

技術實作需求

相關檔案參考

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

功能需求

API 端點需求

技術實作需求

相關檔案參考

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

功能需求

API 端點需求

相關檔案參考

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

功能需求

API 端點需求

相關檔案參考

🗄️ 資料庫連接和遷移

需要完成的設定

1. Supabase 連接配置

2. Entity Framework 遷移

3. 測試資料播種

🌐 前端 API 整合

需要修改的檔案

1. API 基礎設定

2. 認證令牌處理

3. 錯誤處理更新

📋 實作順序建議

Week 1: 核心功能

Week 2: 學習和 AI 系統

Week 3: 進階功能和整合

📚 相關文檔引用

需求文檔

設計文檔

前端實作參考

技術實作文檔

🎯 成功標準

功能完整性檢查清單

🔐 認證系統

📚 詞卡管理

🧠 學習系統

🤖 AI 功能

📊 統計分析

⚠️ 錯誤管理

技術品質檢查

🏗️ 程式碼品質

🔒 安全性

📈 效能

🛠️ 詳細實作指南

第一步：AuthController 實作

建立檔案

實作重點

相依服務

第二步：StudyController 實作

建立檔案

實作重點

相依服務

第三步：AIController 實作

建立檔案

實作重點

需要的 NuGet 套件

第四步：TagsController 和 ErrorReportsController

實作重點

📊 完成度追蹤

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

里程碑時間表

15 KiB

Raw Permalink Blame History