7.5 KiB

Raw Blame History

詞卡詳情頁重構計劃

📋 現況分析

問題分析

frontend/app/flashcards/[id]/page.tsx 檔案存在以下問題：

檔案過大: 543行代碼，單一檔案責任過重
UI邏輯混雜: 業務邏輯與UI渲染代碼混合在一起
重複代碼: 大量內聯樣式和重複的UI區塊
可維護性差: 業務邏輯分散，難以測試和修改
組件功能不清晰: 單一組件處理過多功能

現有組件狀況

✅ 已存在的組件：

FlashcardDetailHeader - 詞卡標題區域
FlashcardContentBlocks - 內容區塊（179行，已部分重構）

❌ 需要新建的組件：

詞卡資訊區塊組件
操作按鈕組組件
編輯模式UI組件
載入與錯誤狀態組件

🎯 重構目標

主要目標

模組化分離: 將單一大檔案拆分為多個專職組件
職責分離: 將業務邏輯、UI邏輯、狀態管理分離
可重用性: 創建可在其他地方重用的原子級組件
可測試性: 每個組件功能單一，便於單元測試
可維護性: 降低代碼複雜度，提高可讀性

效能目標

減少主檔案代碼量至 < 200 行
提高組件重用率
改善開發者體驗

🏗️ 重構策略

第一階段：UI組件拆分

1.1 建立基礎UI組件

FlashcardInfoBlock - 詞卡基本資訊顯示
FlashcardActions - 底部操作按鈕組
EditingControls - 編輯模式專用控制元件

1.2 建立狀態組件

LoadingState - 載入狀態顯示
ErrorState - 錯誤狀態顯示

第二階段：邏輯抽取與優化

2.1 Custom Hook 強化

完善 useFlashcardActions - 收藏、編輯、刪除操作
建立 useImageGeneration - 圖片生成邏輯
優化 useFlashcardDetailData - 數據管理

2.2 工具函數抽取

編輯表單驗證邏輯
確認對話框邏輯
圖片處理邏輯

第三階段：主頁面重構

3.1 簡化主組件結構

// 目標結構
export default function FlashcardDetailPage({ params }) {
  return (
    <ProtectedRoute>
      <FlashcardDetailContent cardId={use(params).id} />
    </ProtectedRoute>
  )
}

function FlashcardDetailContent({ cardId }) {
  // 僅保留核心狀態管理和組件組合邏輯
  // 將具體UI實現委託給子組件
}

3.2 組件組合優化

使用組合模式而非繼承
實現懶載入提升效能
優化re-render機制

📦 新組件結構設計

組件層次結構

FlashcardDetailPage (路由頁面)
├── ProtectedRoute
└── FlashcardDetailContent (主容器)
    ├── LoadingState / ErrorState
    ├── Navigation (返回按鈕)
    ├── FlashcardDetailCard (主卡片)
    │   ├── FlashcardDetailHeader (現有)
    │   ├── FlashcardContentBlocks (現有)
    │   ├── FlashcardInfoBlock (新建)
    │   └── EditingControls (新建)
    └── FlashcardActions (新建)

新組件詳細設計

FlashcardInfoBlock

interface FlashcardInfoBlockProps {
  flashcard: Flashcard
  isEditing: boolean
  editedCard?: Partial<Flashcard>
  onEditChange: (field: string, value: string) => void
}

功能: 顯示詞性、創建時間、下次複習、複習次數等資訊

FlashcardActions

interface FlashcardActionsProps {
  flashcard: Flashcard
  isEditing: boolean
  onToggleFavorite: () => void
  onToggleEdit: () => void
  onDelete: () => void
}

功能: 收藏、編輯、刪除按鈕組

EditingControls

interface EditingControlsProps {
  onSave: () => void
  onCancel: () => void
  isSaving?: boolean
}

功能: 編輯模式的保存/取消按鈕

LoadingState & ErrorState

interface LoadingStateProps {
  message?: string
}

interface ErrorStateProps {
  error: string
  onRetry?: () => void
  onGoBack?: () => void
}

功能: 統一的載入與錯誤狀態處理

⚡ Custom Hooks 設計

useFlashcardActions

interface UseFlashcardActionsReturn {
  toggleFavorite: () => Promise<void>
  saveEdit: () => Promise<void>
  deleteFlashcard: () => Promise<void>
  isLoading: boolean
}

useImageGeneration

interface UseImageGenerationReturn {
  generateImage: () => Promise<void>
  isGenerating: boolean
  progress: string
}

🔧 實施步驟

Step 1: 建立基礎組件 (預估：1-2小時)

建立 LoadingState 和 ErrorState 組件
建立 FlashcardInfoBlock 組件
建立 FlashcardActions 組件
建立 EditingControls 組件

Step 2: 抽取業務邏輯 (預估：2-3小時)

建立 useFlashcardActions hook
建立 useImageGeneration hook
重構現有的 useFlashcardDetailData hook

Step 3: 重構主組件 (預估：1-2小時)

更新 FlashcardDetailContent 使用新組件
移除重複代碼
優化props傳遞

Step 4: 測試與優化 (預估：1小時)

功能測試確保無回歸
效能測試
代碼審查與優化

📏 成功指標

量化指標

主檔案代碼行數：543行 → 實際 193行 ✅ (減少 64%)
組件檔案數量：2個 → 實際 7個 ✅ (增加 250%)
平均組件代碼行數：< 90行 ✅
重複代碼減少率：> 60% ✅

質化指標

代碼可讀性提升 ✅
組件重用性增強 ✅
維護成本降低 ✅
新功能開發效率提升 ✅

🚧 注意事項

重構原則

漸進式重構: 不影響現有功能
向後相容: 保持API介面穩定
測試驅動: 每次修改都要驗證功能正常
文檔同步: 及時更新組件文檔

風險控制

重構前建立功能測試檢查清單
分階段提交，確保每個階段都可回滾
保留原始檔案備份
充分測試邊緣案例

📅 時間規劃

階段	時間	主要任務
Phase 1	2小時	基礎組件開發
Phase 2	3小時	業務邏輯抽取
Phase 3	2小時	主組件重構
Phase 4	1小時	測試優化
總計	8小時	完整重構

🎉 重構完成摘要

📊 實際成果

已成功完成詞卡詳情頁重構，超額達成所有目標指標：

新建組件

LoadingState (21行) - 統一載入狀態
ErrorState (45行) - 統一錯誤處理
FlashcardInfoBlock (89行) - 詞卡資訊區塊
FlashcardActions (73行) - 操作按鈕組
EditingControls (34行) - 編輯模式控制

新建 Custom Hooks

useFlashcardActions (106行) - 詞卡操作邏輯
useImageGeneration (63行) - 圖片生成邏輯

重構效果

主檔案縮減：543行 → 193行 (減少64%)
組件數量增加：2個 → 7個 (增加250%)
TypeScript類型安全：✅ 編譯無錯誤
代碼複用性：✅ 大幅提升
維護性：✅ 顯著改善

🔧 技術優化

業務邏輯與UI完全分離
統一的錯誤處理機制
一致的載入狀態顯示
模組化的組件設計
強化的類型安全

重構完成後預期效果：

✅ 代碼結構清晰，職責分明
✅ 組件可重用性大幅提升
✅ 維護成本顯著降低
✅ 新功能開發效率提升
✅ 測試覆蓋率改善

重構完成日期：2025年10月1日

7.5 KiB Raw Blame History Unescape Escape