From 491f184c4ec125191cb8a3ef813d638f57fd8a2d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E9=84=AD=E6=B2=9B=E8=BB=92?= <jettcheng1018@gmail.com>
Date: Sun, 28 Sep 2025 00:37:25 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=E6=99=BA=E8=83=BD?=
 =?UTF-8?q?=E5=A1=AB=E7=A9=BA=E9=A1=8C=E7=B3=BB=E7=B5=B1=E8=A8=AD=E8=A8=88?=
 =?UTF-8?q?=E8=A6=8F=E6=A0=BC=E6=9B=B8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

建立完整的系統重構規格，解決當前填空題挖空邏輯的限制：

## 核心設計
- 將挖空邏輯從前端移至後端統一處理
- 新增 FilledQuestionText 欄位儲存挖空後的題目
- 建立程式碼挖空 + AI輔助的雙重回退機制

## 解決問題
- 支援詞彙變形挖空 (eat/ate, go/went 等)
- 處理複數、比較級、過去分詞等語法變化
- 提供AI輔助確保挖空準確性

## 系統架構
- 後端: BlankGenerationService + API端點強化
- 前端: 簡化SentenceFillTest組件邏輯
- 資料庫: Migration添加新欄位

## 實施計劃
分4個階段: 資料庫結構 → 後端服務 → 前端優化 → 測試優化

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .../review/review-tests/SentenceFillTest.tsx  |   1 -
 .../review-tests/SentenceListeningTest.tsx    |   4 -
 .../review-tests/SentenceReorderTest.tsx      |   1 -
 智能填空題系統設計規格.md                     | 187 ++++++++++++++++++
 4 files changed, 187 insertions(+), 6 deletions(-)
 create mode 100644 智能填空題系統設計規格.md

diff --git a/frontend/components/review/review-tests/SentenceFillTest.tsx b/frontend/components/review/review-tests/SentenceFillTest.tsx
index 824d424..d212616 100644
--- a/frontend/components/review/review-tests/SentenceFillTest.tsx
+++ b/frontend/components/review/review-tests/SentenceFillTest.tsx
@@ -115,7 +115,6 @@ export const SentenceFillTest: React.FC<SentenceFillTestProps> = ({
         {exampleImage && (
           <div className="mb-6">
             <div className="bg-gray-50 rounded-lg p-4">
-              <h3 className="font-semibold text-gray-900 mb-2 text-left">圖片提示</h3>
               <img
                 src={exampleImage}
                 alt="Example illustration"
diff --git a/frontend/components/review/review-tests/SentenceListeningTest.tsx b/frontend/components/review/review-tests/SentenceListeningTest.tsx
index 287f465..98c62ca 100644
--- a/frontend/components/review/review-tests/SentenceListeningTest.tsx
+++ b/frontend/components/review/review-tests/SentenceListeningTest.tsx
@@ -68,9 +68,6 @@ export const SentenceListeningTest: React.FC<SentenceListeningTestProps> = ({
         <div className="text-center mb-8">
           <div className="mb-6">
             <AudioPlayer text={example} />
-            <p className="text-sm text-gray-500 mt-2">
-              點擊播放聽例句
-            </p>
           </div>
         </div>
 
@@ -78,7 +75,6 @@ export const SentenceListeningTest: React.FC<SentenceListeningTestProps> = ({
         {exampleImage && (
           <div className="mb-6">
             <div className="bg-gray-50 rounded-lg p-4">
-              <h3 className="font-semibold text-gray-900 mb-2 text-left">圖片提示</h3>
               <img
                 src={exampleImage}
                 alt="Example illustration"
diff --git a/frontend/components/review/review-tests/SentenceReorderTest.tsx b/frontend/components/review/review-tests/SentenceReorderTest.tsx
index b555430..cac440b 100644
--- a/frontend/components/review/review-tests/SentenceReorderTest.tsx
+++ b/frontend/components/review/review-tests/SentenceReorderTest.tsx
@@ -94,7 +94,6 @@ export const SentenceReorderTest: React.FC<SentenceReorderTestProps> = ({
         {exampleImage && (
           <div className="mb-6">
             <div className="bg-gray-50 rounded-lg p-4">
-              <h3 className="font-semibold text-gray-900 mb-2 text-left">圖片提示</h3>
               <img
                 src={exampleImage}
                 alt="Example illustration"
diff --git a/智能填空題系統設計規格.md b/智能填空題系統設計規格.md
new file mode 100644
index 0000000..0b6cd3a
--- /dev/null
+++ b/智能填空題系統設計規格.md
@@ -0,0 +1,187 @@
+# 智能填空題系統設計規格書
+
+## 概述
+
+將填空題的挖空邏輯從前端移至後端，建立智能的例句處理系統，支援詞彙變形識別和AI輔助挖空。
+
+## 問題分析
+
+### 當前問題
+- 前端使用簡單正則 `\b${word}\b` 進行挖空
+- 無法處理詞彙變形：`eat` vs `ate`、`go` vs `went`
+- 挖空失敗時無替代方案，導致題目無法正常顯示
+
+### 影響範圍
+- 動詞變形：eat/ate、go/went、run/ran
+- 名詞複數：cat/cats、child/children
+- 形容詞比較級：good/better、bad/worse
+- 過去分詞：break/broken、speak/spoken
+
+## 系統架構設計
+
+### 資料庫結構調整
+
+#### Flashcard 實體新增欄位
+```csharp
+[MaxLength(1000)]
+public string? FilledQuestionText { get; set; }  // 挖空後的題目文字
+```
+
+#### 範例資料
+```json
+{
+  "word": "ate",
+  "example": "She ate an apple yesterday.",
+  "filledQuestionText": "She ____ an apple yesterday."
+}
+```
+
+### 後端服務架構
+
+#### 1. BlankGenerationService 服務
+```csharp
+public interface IBlankGenerationService
+{
+    Task<string?> GenerateBlankQuestionAsync(string word, string example);
+    string? TryProgrammaticBlank(string word, string example);
+    Task<string?> GenerateAIBlankAsync(string word, string example);
+}
+```
+
+#### 2. 智能挖空處理流程
+
+##### Step 1: 程式碼挖空 (快速處理)
+```csharp
+// 1. 完全匹配
+var regex1 = new Regex($@"\b{Regex.Escape(word)}\b", RegexOptions.IgnoreCase);
+
+// 2. 常見變形規則
+var variations = GetCommonVariations(word);
+foreach(var variation in variations)
+{
+    var regex2 = new Regex($@"\b{Regex.Escape(variation)}\b", RegexOptions.IgnoreCase);
+    // 嘗試替換
+}
+```
+
+##### Step 2: AI 輔助挖空 (處理複雜變形)
+```csharp
+var prompt = $@"
+請將以下例句中與詞彙「{word}」相關的詞挖空，用____替代：
+
+詞彙: {word}
+例句: {example}
+
+規則:
+1. 只挖空與目標詞彙相關的詞(包含變形、時態、複數等)
+2. 用____替代被挖空的詞
+3. 保持句子其他部分不變
+4. 直接返回挖空後的句子，不要額外說明
+
+挖空後的句子:";
+
+await _geminiService.GenerateTextAsync(prompt);
+```
+
+#### 3. API 端點調整
+
+##### GET /api/flashcards/due 強化邏輯
+```csharp
+foreach(var flashcard in dueCards)
+{
+    if(string.IsNullOrEmpty(flashcard.FilledQuestionText))
+    {
+        var blankQuestion = await _blankGenerationService.GenerateBlankQuestionAsync(
+            flashcard.Word, flashcard.Example);
+
+        if(!string.IsNullOrEmpty(blankQuestion))
+        {
+            flashcard.FilledQuestionText = blankQuestion;
+            // 更新資料庫
+        }
+    }
+}
+```
+
+##### 新增重新生成端點
+```csharp
+[HttpPost("{id}/regenerate-blank")]
+public async Task<ActionResult> RegenerateBlankQuestion(Guid id)
+```
+
+### 前端架構簡化
+
+#### SentenceFillTest 組件調整
+```typescript
+// 移除複雜的 renderSentenceWithInput() 邏輯
+// 改為簡單的模板渲染
+
+interface SentenceFillTestProps {
+  word: string;
+  definition: string;
+  example: string;           // 原始例句
+  filledQuestionText: string; // 挖空後的題目
+  // ... 其他屬性
+}
+
+// 簡化的渲染邏輯
+const renderFilledSentence = () => {
+  return filledQuestionText.replace('____',
+    `<input value="${fillAnswer}" ... />`
+  );
+}
+```
+
+## 實施計劃
+
+### Phase 1: 資料庫結構
+1. 創建 Migration 添加 `FilledQuestionText` 欄位
+2. 更新 Flashcard 實體模型
+
+### Phase 2: 後端服務開發
+1. 實作 `BlankGenerationService`
+2. 建立常見詞彙變形對應表
+3. 整合 AI 挖空功能
+4. 修改 FlashcardsController
+
+### Phase 3: 前端優化
+1. 簡化 SentenceFillTest 組件
+2. 更新 Props 介面
+3. 測試新的渲染邏輯
+
+### Phase 4: 測試與優化
+1. 測試各種詞彙變形情況
+2. 驗證 AI 挖空品質
+3. 效能優化和錯誤處理
+
+## 預期效果
+
+### 功能提升
+- ✅ 支援所有詞彙變形挖空
+- ✅ AI 輔助處理複雜情況
+- ✅ 一次生成，多次使用
+- ✅ 統一的挖空品質
+
+### 技術優勢
+- 🚀 前端邏輯簡化
+- 🎯 後端統一處理
+- 💾 結果快取提升效能
+- 🤖 AI 確保準確性
+
+### 維護性
+- 📦 挖空邏輯集中管理
+- 🔧 易於調整和優化
+- 📊 可監控挖空成功率
+- 🐛 錯誤處理更完善
+
+## 風險評估
+
+### 技術風險
+- AI 調用可能失敗 → 提供降級策略
+- 資料庫遷移 → 確保現有資料相容
+- 效能影響 → 批次處理優化
+
+### 緩解措施
+- 多層回退機制 (程式碼 → AI → 手動)
+- 非同步處理避免阻塞
+- 詳細日誌記錄便於除錯
\ No newline at end of file