363 lines
11 KiB
Markdown
363 lines
11 KiB
Markdown
# DramaLing Frontend 架構分析報告
|
||
|
||
## 📋 **執行摘要**
|
||
|
||
本報告對 DramaLing 詞彙學習系統的前端架構進行了全面分析，涵蓋了 **11 個頁面**和 **36 個組件**，總計約 **8,668 行代碼**。分析發現了多個重構機會，特別是在代碼重複、組件拆分和架構優化方面。
|
||
|
||
---
|
||
|
||
## 🎯 **頁面結構分析** (app 資料夾)
|
||
|
||
### 📊 **檔案大小統計**
|
||
|
||
| 檔案名稱 | 行數 | 複雜度等級 | 重構優先級 |
|
||
|---------|------|-----------|-----------|
|
||
| `flashcards/page.tsx` | 898 | 🔴 極高 | 🔴 高優先級 |
|
||
| `flashcards/[id]/page.tsx` | 773 | 🔴 極高 | 🔴 高優先級 |
|
||
| `generate/page.tsx` | 625 | 🟡 高 | 🟡 中優先級 |
|
||
| `review-design/page.tsx` | 279 | 🟡 中等 | 🟢 低優先級 |
|
||
| `dashboard/page.tsx` | 256 | 🟡 中等 | 🟢 低優先級 |
|
||
| `review/page.tsx` | 253 | 🟡 中等 | 🟢 低優先級 |
|
||
| `register/page.tsx` | 242 | 🟡 中等 | 🟢 低優先級 |
|
||
| `settings/page.tsx` | 208 | 🟢 低 | 🟢 低優先級 |
|
||
| `login/page.tsx` | 154 | 🟢 低 | ✅ 無需重構 |
|
||
| `page.tsx` (首頁) | 129 | 🟢 低 | ✅ 無需重構 |
|
||
| `layout.tsx` | 26 | 🟢 低 | ✅ 無需重構 |
|
||
|
||
### 🚨 **頁面問題分析**
|
||
|
||
#### 🔴 **高優先級問題**
|
||
|
||
1. **`flashcards/page.tsx` (898 行)**
|
||
- **問題**: 巨型組件，包含多個功能模塊
|
||
- **具體問題**:
|
||
- 搜尋控制邏輯 (147 行)
|
||
- 分頁控制邏輯 (76 行)
|
||
- 詞卡項目渲染 (143 行)
|
||
- 圖片生成邏輯 (66 行)
|
||
- **影響**: 可維護性低、測試困難
|
||
|
||
2. **`flashcards/[id]/page.tsx` (773 行)**
|
||
- **問題**: 功能過於集中，混合了多種責任
|
||
- **具體問題**:
|
||
- 編輯模式邏輯
|
||
- TTS 音頻控制
|
||
- 圖片生成管理
|
||
- 表單處理
|
||
|
||
#### 🟡 **中優先級問題**
|
||
|
||
3. **`generate/page.tsx` (625 行)**
|
||
- **問題**: AI 分析邏輯與 UI 混合
|
||
- **建議**: 拆分業務邏輯到 hooks
|
||
|
||
---
|
||
|
||
## 🧩 **組件架構分析** (components 資料夾)
|
||
|
||
### 📊 **組件大小統計**
|
||
|
||
| 組件名稱 | 行數 | 類型 | 重構優先級 |
|
||
|---------|------|------|-----------|
|
||
| `review/ReviewRunner.tsx` | 439 | 核心業務組件 | 🔴 高優先級 |
|
||
| `generate/ClickableTextV2.tsx` | 413 | 功能組件 | 🔴 高優先級 |
|
||
| `review/TestStatusIndicator.tsx` | 322 | UI組件 | 🟡 中優先級 |
|
||
| `review/shared/AnswerActions.tsx` | 295 | 共享組件 | 🟡 中優先級 |
|
||
| `review/NavigationController.tsx` | 241 | 控制組件 | 🟡 中優先級 |
|
||
| `review/shared/TestContainer.tsx` | 233 | 容器組件 | 🟢 低優先級 |
|
||
| `flashcards/FlashcardForm.tsx` | 227 | 表單組件 | 🟡 中優先級 |
|
||
|
||
### 🏗️ **組件架構評估**
|
||
|
||
#### ✅ **良好的架構模式**
|
||
- **分層清晰**: `review/shared/` 共享組件層級
|
||
- **組件專業化**: 測試類型組件分離良好
|
||
- **容器模式**: `TestContainer` 提供統一布局
|
||
|
||
#### 🔴 **架構問題**
|
||
- **ReviewRunner**: 過於巨大，承擔太多責任
|
||
- **ClickableTextV2**: 複雜的詞彙分析邏輯
|
||
- **重複邏輯**: CEFR 顏色函數在多處定義
|
||
|
||
---
|
||
|
||
## 🔍 **重複代碼分析**
|
||
|
||
### 🚨 **嚴重重複問題**
|
||
|
||
#### 1. **CEFR 處理邏輯**
|
||
```typescript
|
||
// 在 2+ 個檔案中重複出現
|
||
const getCEFRColor = (level: string) => {
|
||
switch (level) {
|
||
case 'A1': return 'bg-green-100 text-green-700 border-green-200'
|
||
case 'A2': return 'bg-blue-100 text-blue-700 border-blue-200'
|
||
// ... 重複 30+ 行代碼
|
||
}
|
||
}
|
||
```
|
||
**位置**: `flashcards/page.tsx`, `flashcards/[id]/page.tsx`, `ClickableTextV2.tsx`
|
||
|
||
#### 2. **詞性轉換邏輯**
|
||
```typescript
|
||
// 完全相同的函數在多處定義
|
||
const getPartOfSpeechDisplay = (partOfSpeech: string): string => {
|
||
const shortMap: {[key: string]: string} = {
|
||
'noun': 'n.',
|
||
'verb': 'v.',
|
||
// ... 重複 20+ 行代碼
|
||
}
|
||
}
|
||
```
|
||
**位置**: `flashcards/page.tsx`, `flashcards/[id]/page.tsx`
|
||
|
||
#### 3. **圖片生成邏輯**
|
||
- 相似的進度管理狀態
|
||
- 重複的錯誤處理模式
|
||
- 類似的 API 調用結構
|
||
|
||
### 📊 **重複統計**
|
||
- **CEFR 相關代碼**: 21 處引用，3 處重複定義
|
||
- **Interface Props**: 48 個組件介面定義
|
||
- **狀態管理模式**: 重複的 `useState` 組合
|
||
|
||
---
|
||
|
||
## 🛠️ **詳細重構建議**
|
||
|
||
### 🔴 **第一優先級 (立即執行)**
|
||
|
||
#### 1. **拆分巨型頁面組件**
|
||
|
||
**flashcards/page.tsx 重構計劃**:
|
||
```
|
||
flashcards/
|
||
├── FlashcardsPage.tsx (主頁面，100行以內)
|
||
├── components/
|
||
│ ├── FlashcardsHeader.tsx (50行)
|
||
│ ├── FlashcardsFilters.tsx (120行)
|
||
│ ├── FlashcardsList.tsx (80行)
|
||
│ ├── FlashcardItem.tsx (100行)
|
||
│ └── FlashcardsPagination.tsx (60行)
|
||
└── hooks/
|
||
├── useFlashcardsData.tsx
|
||
└── useImageGeneration.tsx
|
||
```
|
||
|
||
**預估工作量**: 2-3 天
|
||
|
||
#### 2. **建立共享工具函數庫**
|
||
|
||
創建 `lib/utils/` 統一管理:
|
||
```
|
||
lib/utils/
|
||
├── cefrUtils.ts (統一 CEFR 處理)
|
||
├── partOfSpeechUtils.ts (詞性處理)
|
||
├── imageUtils.ts (圖片相關工具)
|
||
└── validationUtils.ts (表單驗證)
|
||
```
|
||
|
||
**預估工作量**: 1 天
|
||
|
||
#### 3. **ReviewRunner 組件重構**
|
||
|
||
```
|
||
components/review/
|
||
├── ReviewRunner.tsx (主控制器，150行以內)
|
||
├── TestOrchestrator.tsx (測試編排)
|
||
├── AnswerProcessor.tsx (答案處理)
|
||
└── TestRenderer.tsx (測試渲染)
|
||
```
|
||
|
||
**預估工作量**: 3-4 天
|
||
|
||
### 🟡 **第二優先級 (1-2週內)**
|
||
|
||
#### 4. **建立設計系統**
|
||
|
||
創建一致的 UI 組件庫:
|
||
```
|
||
components/ui/
|
||
├── Button.tsx (統一按鈕樣式)
|
||
├── Card.tsx (卡片組件)
|
||
├── Badge.tsx (標籤組件)
|
||
├── Modal.tsx (彈窗組件)
|
||
└── forms/
|
||
├── Input.tsx
|
||
├── Select.tsx
|
||
└── Textarea.tsx
|
||
```
|
||
|
||
#### 5. **狀態管理優化**
|
||
|
||
- 統一使用 Zustand 或 Context
|
||
- 建立共享的 API 狀態管理
|
||
- 實現樂觀更新機制
|
||
|
||
#### 6. **性能優化**
|
||
|
||
- 實現組件懶加載
|
||
- 優化大列表渲染 (虛擬滾動)
|
||
- 圖片懶加載和預載機制
|
||
|
||
### 🟢 **第三優先級 (長期規劃)**
|
||
|
||
#### 7. **TypeScript 類型系統完善**
|
||
- 建立統一的類型定義
|
||
- 消除 `any` 類型使用
|
||
- 實現嚴格的類型檢查
|
||
|
||
#### 8. **測試架構建立**
|
||
- 單元測試覆蓋率 80%+
|
||
- 組件整合測試
|
||
- E2E 測試關鍵流程
|
||
|
||
---
|
||
|
||
## 📊 **重構優先級矩陣**
|
||
|
||
| 項目 | 影響程度 | 實現難度 | 工作量 | 優先級 |
|
||
|------|----------|----------|--------|--------|
|
||
| 拆分巨型組件 | 🔴 極高 | 🟡 中等 | 5-7天 | P0 |
|
||
| 提取共享邏輯 | 🔴 高 | 🟢 低 | 1-2天 | P0 |
|
||
| ReviewRunner重構 | 🟡 高 | 🟡 中等 | 3-4天 | P1 |
|
||
| 建立設計系統 | 🟡 中等 | 🟡 中等 | 1-2週 | P1 |
|
||
| 性能優化 | 🟡 中等 | 🔴 高 | 1-2週 | P2 |
|
||
| 測試架構 | 🟢 中等 | 🟡 中等 | 2-3週 | P3 |
|
||
|
||
---
|
||
|
||
## ⚡ **性能瓶頸分析**
|
||
|
||
### 🚨 **已識別問題**
|
||
|
||
1. **大型列表渲染**
|
||
- `flashcards/page.tsx` 未使用虛擬滾動
|
||
- 搜尋結果全量渲染
|
||
|
||
2. **重複 API 調用**
|
||
- 缺乏適當的快取機制
|
||
- 頁面切換時重複載入相同數據
|
||
|
||
3. **圖片加載優化**
|
||
- 缺乏圖片懶加載
|
||
- 未實現預載機制
|
||
|
||
### 💡 **優化建議**
|
||
|
||
1. **實現虛擬滾動** (React Window)
|
||
2. **添加 SWR 或 React Query** 進行數據快取
|
||
3. **使用 Intersection Observer** 實現懶加載
|
||
4. **Bundle 分析和代碼分割**
|
||
|
||
---
|
||
|
||
## 🔧 **技術債務評估**
|
||
|
||
### 📈 **技術債務分類**
|
||
|
||
| 類型 | 嚴重程度 | 數量 | 預估修復時間 |
|
||
|------|----------|------|-------------|
|
||
| 代碼重複 | 🔴 高 | 15+ 處 | 3-5 天 |
|
||
| 巨型組件 | 🔴 高 | 3 個 | 7-10 天 |
|
||
| 混合責任 | 🟡 中 | 8 個 | 5-7 天 |
|
||
| 類型安全 | 🟡 中 | 多處 `any` | 3-4 天 |
|
||
| 測試覆蓋 | 🟡 中 | <10% | 2-3 週 |
|
||
|
||
### 📊 **總技術債務評估**
|
||
- **總預估修復時間**: 6-8 週
|
||
- **影響可維護性**: 高
|
||
- **影響開發速度**: 中高
|
||
- **風險等級**: 中等
|
||
|
||
---
|
||
|
||
## 🎯 **執行路線圖**
|
||
|
||
### 🚀 **第一階段 (1-2週)**: 緊急修復
|
||
- [x] 提取共享工具函數 (2天) ✅ **完成** - 2025-10-01
|
||
- [ ] 拆分 `flashcards/page.tsx` (4天) 🔄 **準備中**
|
||
- [ ] 拆分 `flashcards/[id]/page.tsx` (3天)
|
||
- [ ] 優化 `ReviewRunner` 組件 (4天)
|
||
|
||
### 📈 **第二階段 (3-4週)**: 架構改善
|
||
- [ ] 建立設計系統基礎組件 (5天)
|
||
- [ ] 實現狀態管理優化 (4天)
|
||
- [ ] 性能優化實施 (6天)
|
||
|
||
### 🎯 **第三階段 (5-8週)**: 完善和測試
|
||
- [ ] 完善 TypeScript 類型系統 (4天)
|
||
- [ ] 建立測試架構 (10天)
|
||
- [ ] 文檔和代碼規範 (3天)
|
||
|
||
---
|
||
|
||
## 📋 **具體行動項目**
|
||
|
||
### 🔴 **立即行動 (本週)**
|
||
1. **創建工具函數庫**
|
||
```bash
|
||
mkdir -p lib/utils
|
||
touch lib/utils/{cefrUtils,partOfSpeechUtils,imageUtils}.ts
|
||
```
|
||
|
||
2. **提取 CEFR 相關邏輯**
|
||
- 統一顏色配置
|
||
- 統一級別判斷邏輯
|
||
|
||
3. **建立組件重構計劃文檔**
|
||
|
||
### 🟡 **短期目標 (2週內)**
|
||
1. **分階段重構巨型組件**
|
||
2. **建立共享組件庫骨架**
|
||
3. **優化關鍵路徑性能**
|
||
|
||
### 🟢 **中長期目標 (1-2個月)**
|
||
1. **完整測試覆蓋**
|
||
2. **性能監控系統**
|
||
3. **自動化重構工具**
|
||
|
||
---
|
||
|
||
## 🎯 **成功指標**
|
||
|
||
### 📊 **量化指標**
|
||
- **平均組件大小**: 從 134 行降至 < 100 行
|
||
- **代碼重複率**: 從 15% 降至 < 5%
|
||
- **測試覆蓋率**: 從 < 10% 提升至 80%+
|
||
- **首頁載入時間**: 目標 < 2 秒
|
||
- **構建時間**: 減少 30%
|
||
|
||
### 🎯 **質化指標**
|
||
- 新功能開發速度提升 40%
|
||
- Bug 修復時間減少 50%
|
||
- 代碼審查效率提升 60%
|
||
- 團隊開發體驗明顯改善
|
||
|
||
---
|
||
|
||
## 📝 **結論與建議**
|
||
|
||
### 🎯 **核心建議**
|
||
1. **立即開始重構巨型組件** - 這是影響開發效率的最大瓶頸
|
||
2. **建立共享工具庫** - 消除代碼重複，提升一致性
|
||
3. **逐步導入設計系統** - 確保 UI 一致性和可維護性
|
||
4. **實施性能監控** - 確保重構不影響用戶體驗
|
||
|
||
### ⚠️ **風險提醒**
|
||
- **避免過度工程化** - 重構應該是漸進式的
|
||
- **確保向後兼容** - 重構期間保持功能穩定
|
||
- **團隊協調** - 確保所有人理解新的架構模式
|
||
|
||
### 🚀 **預期收益**
|
||
通過執行此重構計劃，預期可以獲得：
|
||
- **開發效率提升 40%**
|
||
- **Bug 修復時間減少 50%**
|
||
- **新功能開發加速 30%**
|
||
- **代碼維護成本降低 60%**
|
||
|
||
---
|
||
|
||
**報告生成時間**: 2025-10-01
|
||
**分析版本**: v1.0
|
||
**下次評估計劃**: 重構完成後 1 個月 |