11 KiB

Raw Blame History

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	🟢 低	✅ 無需重構

🚨 頁面問題分析

🔴 高優先級問題

flashcards/page.tsx (898 行)
- 問題: 巨型組件，包含多個功能模塊
- 具體問題:
  - 搜尋控制邏輯 (147 行)
  - 分頁控制邏輯 (76 行)
  - 詞卡項目渲染 (143 行)
  - 圖片生成邏輯 (66 行)
- 影響: 可維護性低、測試困難
flashcards/[id]/page.tsx (773 行)
- 問題: 功能過於集中，混合了多種責任
- 具體問題:
  - 編輯模式邏輯
  - TTS 音頻控制
  - 圖片生成管理
  - 表單處理

🟡 中優先級問題

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 處理邏輯

// 在 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. 詞性轉換邏輯

// 完全相同的函數在多處定義
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

⚡ 性能瓶頸分析

🚨 已識別問題

大型列表渲染
- flashcards/page.tsx 未使用虛擬滾動
- 搜尋結果全量渲染
重複 API 調用
- 缺乏適當的快取機制
- 頁面切換時重複載入相同數據
圖片加載優化
- 缺乏圖片懶加載
- 未實現預載機制

💡 優化建議

實現虛擬滾動 (React Window)
添加 SWR 或 React Query 進行數據快取
使用 Intersection Observer 實現懶加載
Bundle 分析和代碼分割

🔧 技術債務評估

📈 技術債務分類

類型	嚴重程度	數量	預估修復時間
代碼重複	🔴 高	15+ 處	3-5 天
巨型組件	🔴 高	3 個	7-10 天
混合責任	🟡 中	8 個	5-7 天
類型安全	🟡 中	多處 `any`	3-4 天
測試覆蓋	🟡 中	<10%	2-3 週

📊 總技術債務評估

總預估修復時間: 6-8 週
影響可維護性: 高
影響開發速度: 中高
風險等級: 中等

🎯 執行路線圖

🚀 第一階段 (1-2週): 緊急修復

提取共享工具函數 (2天)
拆分 flashcards/page.tsx (4天)
拆分 flashcards/[id]/page.tsx (3天)
優化 ReviewRunner 組件 (4天)

📈 第二階段 (3-4週): 架構改善

建立設計系統基礎組件 (5天)
實現狀態管理優化 (4天)
性能優化實施 (6天)

🎯 第三階段 (5-8週): 完善和測試

完善 TypeScript 類型系統 (4天)
建立測試架構 (10天)
文檔和代碼規範 (3天)

📋 具體行動項目

🔴 立即行動 (本週)

創建工具函數庫

mkdir -p lib/utils
touch lib/utils/{cefrUtils,partOfSpeechUtils,imageUtils}.ts

提取 CEFR 相關邏輯
- 統一顏色配置
- 統一級別判斷邏輯
建立組件重構計劃文檔

🟡 短期目標 (2週內)

分階段重構巨型組件
建立共享組件庫骨架
優化關鍵路徑性能

🟢 中長期目標 (1-2個月)

完整測試覆蓋
性能監控系統
自動化重構工具

🎯 成功指標

📊 量化指標

平均組件大小: 從 134 行降至 < 100 行
代碼重複率: 從 15% 降至 < 5%
測試覆蓋率: 從 < 10% 提升至 80%+
首頁載入時間: 目標 < 2 秒
構建時間: 減少 30%

🎯 質化指標

新功能開發速度提升 40%
Bug 修復時間減少 50%
代碼審查效率提升 60%
團隊開發體驗明顯改善

📝 結論與建議

🎯 核心建議

立即開始重構巨型組件 - 這是影響開發效率的最大瓶頸
建立共享工具庫 - 消除代碼重複，提升一致性
逐步導入設計系統 - 確保 UI 一致性和可維護性
實施性能監控 - 確保重構不影響用戶體驗

⚠️ 風險提醒

避免過度工程化 - 重構應該是漸進式的
確保向後兼容 - 重構期間保持功能穩定
團隊協調 - 確保所有人理解新的架構模式

🚀 預期收益

通過執行此重構計劃，預期可以獲得：

開發效率提升 40%
Bug 修復時間減少 50%
新功能開發加速 30%
代碼維護成本降低 60%

報告生成時間: 2025-10-01 分析版本: v1.0 下次評估計劃: 重構完成後 1 個月

11 KiB Raw Blame History Unescape Escape