206 lines
6.8 KiB
Markdown
206 lines
6.8 KiB
Markdown
# Review-Tests 組件架構優化計劃
|
|
|
|
## 🔍 當前架構問題分析
|
|
|
|
### **檔案大小與複雜度**
|
|
- **FlipMemoryTest.tsx**: 9350 bytes (過大)
|
|
- **SentenceFillTest.tsx**: 9513 bytes (過大)
|
|
- **SentenceReorderTest.tsx**: 8084 bytes (較大)
|
|
- 單一組件承擔太多責任
|
|
|
|
### **Props 介面不一致**
|
|
```typescript
|
|
// FlipMemoryTest - 有 synonyms
|
|
interface FlipMemoryTestProps {
|
|
synonyms?: string[]
|
|
// ...
|
|
}
|
|
|
|
// VocabChoiceTest - 沒有 synonyms
|
|
interface VocabChoiceTestProps {
|
|
// 缺少 synonyms
|
|
// ...
|
|
}
|
|
```
|
|
|
|
### **程式碼重複問題**
|
|
1. **AudioPlayer 重複引用** - 每個組件都獨立處理音頻
|
|
2. **狀態管理重複** - 相似的 useState 邏輯
|
|
3. **UI 模式重複** - 按鈕、卡片、回饋機制
|
|
4. **錯誤處理重複** - onReportError 邏輯分散
|
|
|
|
## 🎯 優化目標
|
|
|
|
### **1. 統一資料介面**
|
|
```typescript
|
|
// 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**
|
|
```typescript
|
|
// 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. 重構測試組件**
|
|
```typescript
|
|
// 每個測試組件專注於核心邏輯
|
|
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: 基礎架構** ✅ **已完成**
|
|
- [x] 創建統一的 TypeScript 介面 (`types/review.ts`)
|
|
- [x] 建立共用 Hook (`hooks/useReviewLogic.ts`)
|
|
- [x] 抽取基礎 UI 組件 (6個共用組件)
|
|
- [x] `CardHeader.tsx` - 詞卡標題和基本資訊
|
|
- [x] `SynonymsDisplay.tsx` - 同義詞顯示
|
|
- [x] `DifficultyBadge.tsx` - 難度等級標籤
|
|
- [x] `AudioSection.tsx` - 音頻播放區域
|
|
- [x] `ConfidenceButtons.tsx` - 信心度選擇按鈕
|
|
- [x] `ErrorReportButton.tsx` - 錯誤回報按鈕
|
|
|
|
### **階段 2: 重構現有組件** ✅ **已完成同義詞整合**
|
|
- [x] FlipMemoryTest 同義詞整合 (添加同義詞顯示功能，檔案大小 9350 bytes)
|
|
- [x] VocabChoiceTest 同義詞整合 (添加同義詞功能，檔案大小 4304 bytes + synonyms)
|
|
- [x] 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 組件的架構分析，旨在提升程式碼品質和維護性。* |