dramaling-vocab-learning/Review-Tests組件架構優化計劃.md

Review-Tests 組件架構優化計劃

🔍 當前架構問題分析

檔案大小與複雜度

• FlipMemoryTest.tsx: 9350 bytes (過大)
• SentenceFillTest.tsx: 9513 bytes (過大)
• SentenceReorderTest.tsx: 8084 bytes (較大)
• 單一組件承擔太多責任

Props 介面不一致

// FlipMemoryTest - 有 synonyms
interface FlipMemoryTestProps {
  synonyms?: string[]
  // ...
}

// VocabChoiceTest - 沒有 synonyms
interface VocabChoiceTestProps {
  // 缺少 synonyms
  // ...
}

程式碼重複問題

1. AudioPlayer 重複引用 - 每個組件都獨立處理音頻
2. 狀態管理重複 - 相似的 useState 邏輯
3. UI 模式重複 - 按鈕、卡片、回饋機制
4. 錯誤處理重複 - onReportError 邏輯分散

🎯 優化目標

1. 統一資料介面

// types/review.ts
interface ReviewCardData {
  id: string
  word: string
  definition: string
  example: string
  translation: string
  pronunciation?: string
  synonyms: string[]
  difficultyLevel: string
  exampleTranslation: string
  filledQuestionText?: string
  exampleImage?: string
}

interface BaseReviewProps {
  cardData: ReviewCardData
  onAnswer: (answer: string) => void
  onReportError: () => void
  disabled?: boolean
}

2. 創建共用 Hook

// hooks/useReviewLogic.ts
export const useReviewLogic = () => {
  // 統一的答案驗證
  // 共用的狀態管理
  // 統一的錯誤處理
  // 音頻播放邏輯
}

3. 抽取共用 UI 組件

components/review/shared/
├── AudioSection.tsx      // 音頻播放區域
├── CardHeader.tsx        // 詞卡標題和基本資訊
├── SynonymsDisplay.tsx   // 同義詞顯示
├── ConfidenceButtons.tsx // 信心度選擇按鈕
├── ErrorReportButton.tsx // 錯誤回報按鈕
├── DifficultyBadge.tsx   // 難度等級標籤
└── AnswerFeedback.tsx    // 答案回饋機制

4. 重構測試組件

// 每個測試組件專注於核心邏輯
export const FlipMemoryTest: React.FC<BaseReviewProps> = ({ cardData, ...props }) => {
  const { /* 共用邏輯 */ } = useReviewLogic()

  return (
    <div>
      <CardHeader cardData={cardData} />
      <AudioSection pronunciation={cardData.pronunciation} />
      {/* 翻卡特定邏輯 */}
      <ConfidenceButtons onSubmit={props.onAnswer} />
      <ErrorReportButton onClick={props.onReportError} />
    </div>
  )
}

📋 實施階段

階段 1: 基礎架構 ✅ 已完成

• 創建統一的 TypeScript 介面 (types/review.ts)
• 建立共用 Hook (hooks/useReviewLogic.ts)
• 抽取基礎 UI 組件 (6個共用組件)
  • CardHeader.tsx - 詞卡標題和基本資訊
  • SynonymsDisplay.tsx - 同義詞顯示
  • DifficultyBadge.tsx - 難度等級標籤
  • AudioSection.tsx - 音頻播放區域
  • ConfidenceButtons.tsx - 信心度選擇按鈕
  • ErrorReportButton.tsx - 錯誤回報按鈕

階段 2: 重構現有組件 ✅ 已完成同義詞整合

• FlipMemoryTest 同義詞整合 (添加同義詞顯示功能，檔案大小 9350 bytes)
• VocabChoiceTest 同義詞整合 (添加同義詞功能，檔案大小 4304 bytes + synonyms)
• SentenceFillTest 同義詞整合 (添加同義詞功能，檔案大小 9513 bytes + synonyms)
• 應用共用架構到實際組件 (架構已建立但未使用)

階段 3: 統一整合 ⏳ 待執行

• 更新 review-design 頁面
• 統一 props 傳遞
• 測試所有功能

階段 4: 優化與測試 ⏳ 待執行

• 效能優化
• 錯誤處理改善
• 使用者體驗統一

🎯 當前狀況 (2025-09-28 16:30)

已建立的檔案

frontend/
├── types/review.ts (統一介面)
├── hooks/useReviewLogic.ts (共用邏輯)
├── components/review/shared/ (共用組件)
│   ├── CardHeader.tsx
│   ├── SynonymsDisplay.tsx
│   ├── DifficultyBadge.tsx
│   ├── AudioSection.tsx
│   ├── ConfidenceButtons.tsx
│   ├── ErrorReportButton.tsx
│   └── index.ts
└── components/review/review-tests/
    ├── FlipMemoryTest.tsx (9350 bytes - 已添加同義詞功能)
    ├── VocabChoiceTest.tsx (4304 bytes - 原版本，未優化)
    └── SentenceFillTest.tsx (9513 bytes - 原版本，未優化)

實際狀況對比

• FlipMemoryTest: 9350 bytes (已添加同義詞功能 ✅)
• VocabChoiceTest: 4304 bytes + synonyms (已添加同義詞功能 ✅)
• SentenceFillTest: 9513 bytes + synonyms (已添加同義詞功能 ✅)
• 實際效果: 所有組件已完成同義詞功能整合 ✅，架構優化未實際應用

✅ 實際完成成果 (2025-09-28 最新更新)

1. 完整的基礎架構 - types, hooks, shared components 全部建立 ✅
2. FlipMemoryTest 同義詞整合 - 添加同義詞顯示功能 ✅
3. VocabChoiceTest 同義詞整合 - 已添加同義詞功能 ✅
4. SentenceFillTest 同義詞整合 - 已添加同義詞功能 ✅
5. 架構應用 - 共用組件未實際使用於現有組件 ⏳

🎯 實際可用優勢

• ✅ 完整基礎架構 - 為未來優化準備了完整的工具
• ✅ 全面同義詞功能 - 所有組件已整合同義詞顯示
• ✅ 統一介面 - 所有組件現在都支援 synonyms?: string[] 參數
• ⏳ 潛在優化 - 架構已建立，可應用於其他組件
• ⚠️ 架構未應用 - 共用組件目前未被實際使用

📋 下一步選項

1. 立即切換 - 啟用優化版本 (建議先在開發環境測試)
2. 漸進遷移 - 單獨測試每個優化組件
3. 保持現狀 - 使用原始版本，優化版本作為未來參考

🎯 預期效果

程式碼品質

• ✅ 減少 50% 程式碼重複
• ✅ 組件大小縮減至 3-5KB
• ✅ 統一的介面和體驗

維護性

• ✅ 新增測試類型更容易
• ✅ Bug 修復影響範圍更小
• ✅ 程式碼更容易理解

功能擴展

• ✅ 同義詞功能統一整合
• ✅ 新功能 (如圖片) 易於添加
• ✅ 響應式設計更一致

⚠️ 風險評估

重構風險

• 中等風險: 需要修改多個檔案
• 測試需求: 需要全面測試所有測試類型
• 向後相容: 確保現有功能不受影響

建議策略

1. 漸進式重構 - 一次重構一個組件
2. 保留備份 - 重構前做 git commit
3. 充分測試 - 每個階段都要測試

---

此計劃基於當前 review-tests 組件的架構分析，旨在提升程式碼品質和維護性。