docs: 建立複習系統三層文檔架構 - 解決實作細節歸屬問題

## 核心成就 - 📚 建立專業的三層文檔架構 - 📋 產品需求規格.md - 用戶故事和業務目標 - 🔧 技術實作規格.md - 具體算法、公式、UI規格 - 🛡️ 開發控制規範.md - 防過度工程的約束規則 - 📖 README.md - 文檔使用指南和關聯索引 ## 解決的問題 - ✅ 實作細節有專門歸屬 (技術實作規格) - ✅ 開發控制有明確約束 (開發控制規範) - ✅ 產品需求保持高層次 (產品需求規格) - ✅ 防止開發失控有具體機制 ## 實作細節完整保留 - 進度條計算公式: (今日完成)/(今日完成+今日到期) - 延遲註記機制: 跳過/答錯 → 延遲標記 - 複習時間算法: 2^成功複習次數 - 詞彙選擇題方案: 固定apple/orange/banana選項 ## 過度工程防護 - 複雜度上限、禁止功能、檢查點機制 - 基於實際失敗經驗的約束規則 - 階段性擴展的決策框架完美平衡: 詳細技術規格 + 有效開發控制 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-10-04 15:55:41 +08:00 · 2025-10-04 15:55:41 +08:00 · 9307cb593d
parent 546db58146
commit 9307cb593d
4 changed files with 801 additions and 26 deletions
--- a/note/複習系統/README.md
+++ b/note/複習系統/README.md
@ -0,0 +1,123 @@
 # 複習系統文檔總覽
 **目標**: 建立清晰的三層文檔架構，既保留實作細節又防止開發失控
 ---
 ## 📚 **文檔架構說明**
 ### **三層文檔分工**
 ```
 📋 產品需求規格.md
 ├── 用戶故事和業務目標
 ├── 階段性功能規劃
 ├── 成功標準定義
 └── 受眾: 產品經理、決策者
 🔧 技術實作規格.md
 ├── 具體算法和公式
 ├── 數據結構和API設計
 ├── UI/UX實作細節
 └── 受眾: 開發者、技術主管
 🛡️ 開發控制規範.md
 ├── 複雜度控制規則
 ├── 禁止功能列表
 ├── 開發檢查點
 └── 受眾: 開發團隊、項目管理
 ```
 ---
 ## 🎯 **如何使用這些文檔**
 ### **產品需求變更時**
 1. 修改 `產品需求規格.md`
 2. 評估對 `技術實作規格.md` 的影響
 3. 檢查是否違反 `開發控制規範.md`
 ### **技術實作時**
 1. 參考 `產品需求規格.md` 理解業務目標
 2. 遵循 `技術實作規格.md` 的具體規範
 3. 嚴格遵守 `開發控制規範.md` 的約束
 ### **代碼審查時**
 1. 檢查是否實現了產品需求
 2. 檢查是否遵循技術實作規範
 3. 檢查是否違反開發控制規則
 ---
 ## 📊 **當前狀態總覽**
 ### **已完成 ✅**
 - 階段1: 極簡MVP翻卡功能
 - 專業UI設計 (復用您的調教成果)
 - 真實API數據結構
 - 完整的測試體系
 ### **文檔覆蓋範圍**
 - ✅ 產品需求: 3個階段的用戶故事
 - ✅ 技術實作: 算法公式、UI規格、API設計
 - ✅ 開發控制: 複雜度限制、禁止清單、檢查點
 ### **防護機制**
 - 🛡️ 過度工程預防規則
 - 🚨 緊急剎車條件
 - 📏 具體的量化標準
 ---
 ## 🚀 **立即行動指南**
 ### **當前重點 (第1週)**
 ```
 目標: 用戶驗證和反饋收集
 行動:
 1. 邀請3-5個用戶測試 /review-simple
 2. 記錄用戶行為和反饋
 3. 識別真正的痛點
 ```
 ### **決策時參考順序**
 1. 檢查 `開發控制規範.md` - 是否被禁止？
 2. 查看 `產品需求規格.md` - 是否有用戶需求？
 3. 參考 `技術實作規格.md` - 如何實現？
 ---
 ## 📋 **文檔維護責任**
 ### **更新觸發條件**
 - 用戶需求變化 → 更新產品需求規格
 - 技術方案調整 → 更新技術實作規格
 - 開發問題出現 → 更新開發控制規範
 ### **版本控制**
 - 所有文檔與代碼同步版本控制
 - 重大變更需要團隊討論
 - 保持文檔與實際實作一致
 ---
 ## 💡 **關鍵成功因素**
 ### **文檔分層的好處**
 1. **職責清晰** - 每個文檔有明確目的
 2. **受眾明確** - 不同角色看不同文檔
 3. **控制有效** - 技術細節有具體約束
 4. **防止失控** - 開發規範明確限制
 ### **使用原則**
 - **產品需求規格** - 回答 "做什麼"
 - **技術實作規格** - 回答 "怎麼做"
 - **開發控制規範** - 回答 "不能做什麼"
 **這個三層架構既保留了您的實作細節，又有效防止開發失控！** 🎯
 ---
 *文檔架構建立: 2025-10-03*
 *基於複習功能開發經驗*
 *目標: 平衡詳細規格與開發控制*
--- a/note/複習系統/技術實作規格.md
+++ b/note/複習系統/技術實作規格.md
@ -0,0 +1,353 @@
 # 複習系統技術實作規格書
 **版本**: 1.0
 **對應PRD**: 產品需求規格.md
 **目標讀者**: 開發者、技術主管
 **最後更新**: 2025-10-03
 ---
 ## 📊 **核心算法和公式**
 ### **進度條計算公式**
 ```typescript
 進度百分比 = (今日完成) / (今日完成 + 今日到期) * 100
 ```
 **實作範例**:
 ```typescript
 const progressPercentage = completedToday / (completedToday + dueToday) * 100
 ```
 ### **複習間隔算法**
 ```typescript
 下一次複習時間 = 當前時間 + (2^成功複習次數) 天
 ```
 **實作範例**:
 ```typescript
 const nextReviewDate = new Date()
 nextReviewDate.setDate(nextReviewDate.getDate() + Math.pow(2, successCount))
 ```
 ---
 ## 🏷️ **卡片狀態管理機制**
 ### **延遲註記系統**
 **新增延遲註記的情況**:
 1. 用戶點選 "跳過" → 卡片標記 `isDelayed: true`
 2. 用戶答錯題目 → 卡片標記 `isDelayed: true`
 **延遲註記的影響**:
 ```typescript
 // 撈取下一個複習卡片時排除延遲卡片
 const nextCards = allCards.filter(card => !card.isDelayed)
 ```
 **消除延遲註記**:
 ```typescript
 // 用戶答對題目時
 if (isCorrect) {
  card.isDelayed = false
  card.successCount++
  card.nextReviewDate = calculateNextReviewDate(card.successCount)
 }
 ```
 ---
 ## 🎯 **測驗模式實作**
 ### **階段1: 翻卡記憶 (已實作)**
 **數據結構**:
 ```typescript
 interface FlashcardData {
  id: string
  word: string
  definition: string
  example: string
  exampleTranslation: string
  pronunciation: string
  synonyms: string[]
  cefr: string
 }
 ```
 **狀態管理**:
 ```typescript
 const [isFlipped, setIsFlipped] = useState(false)
 const [selectedConfidence, setSelectedConfidence] = useState<number | null>(null)
 const [cardHeight, setCardHeight] = useState<number>(400)
 ```
 **信心度評分映射**:
 ```typescript
 const confidenceToScore = {
  1: 0,    // 完全不懂 → 答錯
  2: 0,    // 模糊 → 答錯
  3: 1,    // 一般 → 答對
  4: 1,    // 熟悉 → 答對
  5: 1     // 非常熟悉 → 答對
 }
 ```
 ### **階段2: 詞彙選擇題 (計劃中)**
 **選項生成算法**:
 ```typescript
 // 暫時使用固定選項 (MVP階段)
 const mockOptions = ['apple', 'orange', 'banana', correctAnswer]
 const shuffledOptions = shuffle(mockOptions)
 ```
 **未來升級方案**:
 ```typescript
 // 基於詞性和CEFR等級生成干擾項
 const generateDistractors = (correctWord, allWords) => {
  const samePOS = allWords.filter(w => w.partOfSpeech === correctWord.partOfSpeech)
  const sameCEFR = allWords.filter(w => w.cefr === correctWord.cefr)
  return selectRandom([...samePOS, ...sameCEFR], 3)
 }
 ```
 ---
 ## 🎨 **UI/UX實作規格**
 ### **翻卡動畫參數**
 ```css
 /* 3D翻卡動畫 - 已調校的完美參數 */
 .flip-card {
  perspective: 1000px;
  transition: transform 0.6s cubic-bezier(0.4, 0, 0.2, 1);
 }
 .flip-card.flipped {
  transform: rotateY(180deg);
 }
 ```
 ### **響應式高度計算**
 ```typescript
 const calculateCardHeight = () => {
  const backHeight = backRef.current?.scrollHeight || 0
  const minHeight = window.innerWidth <= 480 ? 300 :
                   window.innerWidth <= 768 ? 350 : 400
  return Math.max(minHeight, backHeight)
 }
 ```
 ### **信心度按鈕配色**
 ```typescript
 const confidenceColors = {
  1: 'bg-red-100 text-red-700 border-red-200',      // 完全不懂
  2: 'bg-orange-100 text-orange-700 border-orange-200', // 模糊
  3: 'bg-yellow-100 text-yellow-700 border-yellow-200', // 一般
  4: 'bg-blue-100 text-blue-700 border-blue-200',   // 熟悉
  5: 'bg-green-100 text-green-700 border-green-200'  // 非常熟悉
 }
 ```
 ---
 ## 📱 **API設計規格** (階段3實作)
 ### **獲取複習卡片API**
 ```typescript
 GET /api/flashcards/due?limit=10
 Response:
 {
  "success": true,
  "data": {
    "flashcards": FlashcardData[],
    "count": number
  },
  "timestamp": string
 }
 ```
 ### **記錄複習結果API**
 ```typescript
 POST /api/flashcards/{id}/review
 Request:
 {
  "confidence": number,  // 1-5
  "isCorrect": boolean,  // 基於confidence >= 3判斷
  "reviewType": "flip-memory",
  "responseTimeMs": number
 }
 Response:
 {
  "success": boolean,
  "nextReviewDate": string,
  "newSuccessCount": number
 }
 ```
 ---
 ## 🗄️ **數據存儲設計**
 ### **階段1: 內存狀態 (當前)**
 ```typescript
 // 純React狀態，會話結束即消失
 const [currentIndex, setCurrentIndex] = useState(0)
 const [score, setScore] = useState({ correct: 0, total: 0 })
 ```
 ### **階段2: 本地存儲 (計劃)**
 ```typescript
 // localStorage持久化
 const saveProgress = (progress: ReviewProgress) => {
  localStorage.setItem('review-progress', JSON.stringify({
    currentIndex,
    score,
    timestamp: Date.now()
  }))
 }
 ```
 ### **階段3: 後端同步 (遠期)**
 ```typescript
 // 與後端API同步
 const syncProgress = async (progress: ReviewProgress) => {
  await api.post('/api/user/review-progress', progress)
 }
 ```
 ---
 ## 🔒 **業務邏輯約束**
 ### **狀態轉換規則**
 ```typescript
 // 卡片狀態轉換
 enum CardState {
  PENDING = 'pending',     // 未開始
  COMPLETED = 'completed', // 已完成
  DELAYED = 'delayed'      // 延遲 (跳過或答錯)
 }
 // 狀態轉換邏輯
 const handleAnswer = (confidence: number) => {
  if (confidence >= 3) {
    // 答對: 移除延遲標記，標記完成
    card.state = CardState.COMPLETED
    card.isDelayed = false
    card.successCount++
  } else {
    // 答錯: 添加延遲標記
    card.isDelayed = true
    card.state = CardState.DELAYED
  }
 }
 ```
 ### **隊列管理邏輯**
 ```typescript
 // 下一張卡片選擇邏輯
 const getNextCard = (cards: FlashCard[]) => {
  // 1. 優先選擇未延遲的卡片
  const normalCards = cards.filter(c => !c.isDelayed && c.state === CardState.PENDING)
  if (normalCards.length > 0) {
    return normalCards[0]
  }
  // 2. 如果沒有正常卡片，選擇延遲卡片
  const delayedCards = cards.filter(c => c.isDelayed)
  return delayedCards[0] || null
 }
 ```
 ---
 ## ⚡ **性能和優化規格**
 ### **載入性能要求**
 ```typescript
 // 性能指標
 const PERFORMANCE_TARGETS = {
  INITIAL_LOAD: 2000,      // 初始載入 < 2秒
  CARD_FLIP: 500,          // 翻卡響應 < 500ms
  CONFIDENCE_SELECT: 200,  // 按鈕響應 < 200ms
  NAVIGATION: 300          // 頁面切換 < 300ms
 }
 ```
 ### **記憶體管理**
 ```typescript
 // 避免記憶體洩漏
 useEffect(() => {
  const timer = setTimeout(updateHeight, 100)
  const resizeHandler = () => updateHeight()
  window.addEventListener('resize', resizeHandler)
  return () => {
    clearTimeout(timer)
    window.removeEventListener('resize', resizeHandler)
  }
 }, [dependencies])
 ```
 ---
 ## 🧪 **測試規格** (TDD Implementation)
 ### **測試覆蓋要求**
 - **核心邏輯**: 100% 測試覆蓋
 - **UI組件**: 關鍵交互測試
 - **API調用**: Mock測試
 - **狀態管理**: 狀態轉換測試
 ### **測試案例範例**
 ```typescript
 // 翻卡邏輯測試
 describe('FlipCard Component', () => {
  test('應該在點擊時切換翻轉狀態', () => {
    const { result } = renderHook(() => useFlipCard())
    act(() => result.current.flip())
    expect(result.current.isFlipped).toBe(true)
  })
  test('應該在選擇信心度時觸發提交', () => {
    const onSubmit = jest.fn()
    const card = render(<FlipCard onSubmit={onSubmit} />)
    card.selectConfidence(4)
    expect(onSubmit).toHaveBeenCalledWith(4)
  })
 })
 ```
 ---
 ## 📋 **實作檢查清單**
 ### **每個功能完成時檢查**
 - [ ] 功能符合產品需求規格
 - [ ] 遵循技術約束和算法
 - [ ] 通過所有相關測試
 - [ ] 性能指標達標
 - [ ] 無記憶體洩漏
 - [ ] 錯誤處理完善
 ### **代碼品質標準**
 - [ ] TypeScript 無錯誤
 - [ ] ESLint 無警告
 - [ ] 組件 < 200行
 - [ ] 函數 < 20行
 - [ ] 嵌套層次 < 3層
 ---
 *技術實作規格維護者: 開發團隊*
 *版本控制: 與產品需求規格同步更新*
 *目的: 確保實作準確性，避免開發失控*
--- a/note/複習系統/產品需求規格.md
+++ b/note/複習系統/產品需求規格.md
@ -1,38 +1,88 @@
-### **US-001: 智能複習排程** 
+# 複習系統產品需求規格書 (MVP版本)
 **作為**學習者
 **我希望**系統能根據我的學習表現智能安排復習時間
 **以便**我能在最佳時機復習，提高學習效率
-### **US-002: 逾期復習處理**
+**版本**: 1.0 MVP
-**作為**忙碌的學習者
+**日期**: 2025-10-03
-**我希望**即使沒有按時復習，系統也能合理調整復習計劃
+**策略**: 階段性開發，避免過度工程
-**以便**我能重新回到正軌，不會因偶爾延遲而影響整體學習進度
+**當前狀態**: 極簡MVP已完成 ✅
-### **US-007: 聽力和口說練習**
+---
 **作為**想要提升聽說能力的學習者
 **我希望**能進行詞彙聽力練習和例句朗讀練習
 **以便**全面提升我的語言技能
- ✅ **詞彙選擇題** (vocab-choice): 定義匹配的客觀測試
+## 🎯 **產品願景**
 - ✅ **例句口說題** (sentence-speaking): 發音和表達練習
 ### **核心價值主張**
 幫助用戶通過**翻卡記憶**快速有效地複習詞彙，提升學習效率。
 ### **設計理念**
 - **簡單可用** > 功能完整
 - **用戶驗證** > 假設需求
 - **迭代進化** > 一次到位
 - **真實反饋** > 完美設計
- 進度條 = (今日完成)/(今日完成+今日到期)
+---
- 卡片延緩註記
+## 🚀 **階段1: 極簡MVP (當前版本)**
 新增：
 1. 當使用者點選跳過時，將卡片註記一個延遲註記
 2. 當使用者答錯時，將卡片註記一個延遲註記
 判斷：
 撈出下一個複習卡片時，會排除有延遲註記的卡片
 修改：
 當使用者答對題目時，會消除延遲註記
- 下一次複習時間 = 2^成功複習次數
+### **US-001: 基礎翻卡記憶**
 **作為** 想複習詞彙的學習者
 **我希望** 能夠翻卡查看詞彙內容並評估自己的熟悉程度
 **以便** 測試和強化我的詞彙記憶
 **實作狀態**: ✅ 已完成
 **技術路徑**: `/review-simple`
- 詞彙選擇題：
+### **核心功能清單**
-暫時先做假的，前端就直接固定塞apple orange banana這三個詞彙當選項
+- ✅ 3D翻卡動畫和互動
 - ✅ 詞彙內容顯示 (定義、例句、同義詞)
 - ✅ 信心度評估 (1-5級)
 - ✅ 基礎進度追蹤
 - ✅ 完成統計結果
 ---
 ## 🎯 **階段2: 雙模式版本 (待用戶驗證)**
 ### **US-002: 詞彙選擇測試**
 **作為** 想要客觀測試的學習者
 **我希望** 能夠通過選擇題測試詞彙記憶
 **以便** 更準確地評估學習成效
 **觸發條件**:
 - ✅ 階段1穩定運行 > 1週
 - ✅ 收到用戶明確反饋需要更多測驗方式
 ### **功能範圍**
 - 4選1選擇題測驗
 - 模式切換介面
 - localStorage進度保存
 ---
 ## 🎯 **階段3: API集成版本 (遠期)**
 ### **US-003: 真實詞彙庫**
 **作為** 想學習更多詞彙的學習者
 **我希望** 能夠複習我收藏的真實詞彙
 **以便** 學習我感興趣的內容
 **觸發條件**:
 - ✅ 有明確需要更多詞彙的用戶反饋
 - ✅ 靜態數據已無法滿足需求
 ---
 ## 📊 **成功標準**
 ### **MVP階段成功標準**
 - [ ] 用戶能完整完成複習流程
 - [ ] 無功能性錯誤或崩潰
 - [ ] 載入時間 < 2秒
 - [ ] 用戶反饋正面
 ### **避免的功能**
 ❌ 智能排程算法
 ❌ 複雜狀態管理
 ❌ 多重測驗模式架構
 **參考**: `技術實作規格.md` 和 `開發控制規範.md` 詳細規定
--- a/note/複習系統/開發控制規範.md
+++ b/note/複習系統/開發控制規範.md
@ -0,0 +1,249 @@
 # 複習系統開發控制規範
 **目的**: 防止過度工程，確保開發不失控
 **適用範圍**: 複習功能的所有開發工作
 **強制級別**: 必須遵守
 **最後更新**: 2025-10-03
 ---
 ## 🚨 **複雜度控制規則** (強制)
 ### **代碼複雜度上限**
 ```typescript
 // 嚴格限制
 單個組件文件: < 200行
 單個函數: < 20行
 組件Props: < 8個
 狀態變數: < 5個
 useEffect依賴: < 5個
 嵌套層次: < 3層
 ```
 ### **架構複雜度上限**
 ```typescript
 // 系統層面限制
 Store數量: 0個 (MVP階段禁止)
 Service層: 0個 (MVP階段禁止)
 抽象層次: < 2層
 組件依賴: < 5個
 API端點: < 3個
 ```
 ### **功能複雜度上限**
 ```typescript
 // 功能範圍限制
 測驗模式: 1個 (MVP階段)
 用戶設定: 0個 (MVP階段)
 個性化邏輯: 0個 (MVP階段)
 算法系統: 基礎數學公式 (無ML/AI)
 ```
 ---
 ## 🛑 **禁止實作功能列表**
 ### **MVP階段絕對禁止**
 ```
 ❌ Zustand/Redux Store架構
 ❌ 複雜的Service層
 ❌ 多重測驗模式切換系統
 ❌ CEFR自適應算法
 ❌ 智能優先級排序
 ❌ 間隔重複複雜算法
 ❌ 用戶行為分析
 ❌ 個性化推薦系統
 ❌ 深度學習集成
 ❌ 複雜的動畫庫 (現有CSS已足夠)
 ```
 ### **任何階段都禁止**
 ```
 ❌ 過度抽象的設計模式
 ❌ 不必要的工廠模式
 ❌ 複雜的依賴注入
 ❌ 過度的泛型設計
 ❌ 未來可能需要的預留功能
 ```
 ---
 ## ✅ **開發檢查點**
 ### **每個功能開發前必須確認**
 ```
 □ 有明確的用戶需求嗎？ (不能是假設)
 □ 最簡單的實現方案是什麼？
 □ 會增加多少代碼行數？ (< 50行可接受)
 □ 會增加多少複雜度？ (< 20%可接受)
 □ 不做這個功能用戶會抱怨嗎？
 □ 有更簡單的替代方案嗎？
 ```
 ### **開發過程中檢查**
 ```
 □ 今天寫的代碼用戶能感受到價值嗎？
 □ 新人能在15分鐘內理解今天的代碼嗎？
 □ 如果刪掉今天的代碼，會影響核心功能嗎？
 □ 今天的代碼是解決實際問題還是假想問題？
 ```
 ### **完成後檢查**
 ```
 □ 功能完全可用，無Bug？
 □ 代碽複雜度在控制範圍內？
 □ 添加新功能仍然容易？
 □ 團隊其他成員能快速理解？
 ```
 ---
 ## 🚨 **緊急剎車條件**
 ### **立即停止開發的信號**
 ```
 🔴 單個功能開發時間 > 1週
 🔴 需要重大架構改變才能實現
 🔴 出現難以除錯的複雜問題
 🔴 複雜度增長 > 50%
 🔴 開始討論"更優雅的架構"
 🔴 開始引入新的第三方庫
 🔴 團隊開始爭論實現方案
 ```
 ### **剎車後的行動**
 1. **停止當前開發**
 2. **重新評估需求** - 是否真的需要這個功能
 3. **尋找簡化方案** - 有沒有更簡單的實現
 4. **考慮放棄功能** - 如果簡化後價值不大
 ---
 ## 📏 **具體實作標準**
 ### **狀態管理標準**
 ```typescript
 // MVP階段只允許
 ✅ React useState
 ✅ 簡單的useEffect
 ✅ 基礎的useCallback (避免重新渲染)
 // 禁止使用
 ❌ useReducer (除非狀態轉換 > 5個)
 ❌ Context API (除非組件樹 > 3層)
 ❌ 任何狀態管理庫
 ```
 ### **API調用標準**
 ```typescript
 // MVP階段標準
 ✅ 直接fetch調用
 ✅ 簡單的錯誤處理
 ✅ 基礎的loading狀態
 // 禁止
 ❌ 複雜的API抽象層
 ❌ 請求攔截器
 ❌ 複雜的緩存機制
 ❌ 狀態同步機制
 ```
 ### **組件設計標準**
 ```typescript
 // 組件職責
 ✅ 單一職責原則
 ✅ Props接口簡單明確
 ✅ 無複雜的內部邏輯
 // 組件通信
 ✅ 簡單的props傳遞
 ✅ 基礎的callback函數
 // 禁止
 ❌ 複雜的組件繼承
 ❌ Higher-Order Components
 ❌ Render Props模式 (除非確實需要)
 ```
 ---
 ## 🎯 **迭代控制策略**
 ### **階段升級條件** (全部滿足才能進入下階段)
 ```
 ✅ 當前階段穩定運行 > 2週
 ✅ 收到 > 3個用戶明確功能需求
 ✅ 新功能複雜度評估 < 20%
 ✅ 有足夠開發時間 (不影響其他功能)
 ✅ 團隊對實現方案有共識
 ```
 ### **功能決策框架**
 ```
 高需求 + 低複雜度 = 🟢 立即實施
 高需求 + 高複雜度 = 🟡 尋找簡化方案
 低需求 + 低複雜度 = 🟡 考慮實施
 低需求 + 高複雜度 = 🔴 拒絕實施
 ```
 ---
 ## 📚 **參考和約束**
 ### **必須參考的文檔**
 - `產品需求規格.md` - 了解業務需求
 - `技術實作規格.md` - 了解具體實作細節
 - `過度工程詳解與避免策略.md` - 理解風險
 ### **開發前必讀**
 - 什麼是過度工程？
 - YAGNI原則 (You Aren't Gonna Need It)
 - KISS原則 (Keep It Simple, Stupid)
 - MVP思維 (Minimum Viable Product)
 ---
 ## 💪 **成功案例** (複習功能)
 ### **正確的開發方式** ✅
 ```
 1. 發現複雜版本壞掉 (過度工程)
 2. 承認失敗，決定重寫
 3. 設計極簡MVP (純useState)
 4. 復用現有UI設計
 5. 使用真實API數據格式
 6. 2小時內完成可用版本
 ```
 ### **錯誤的開發方式** ❌
 ```
 1. 設計完美的架構 (5個Store)
 2. 實現所有可能功能 (7種測驗)
 3. 建立複雜算法 (智能排序)
 4. 過度測試覆蓋 (所有UI細節)
 5. 結果: 功能壞掉，無法使用
 ```
 ---
 ## 🎯 **實際應用指引**
 ### **日常開發使用**
 1. **開發前** - 檢查功能是否在禁止列表
 2. **開發中** - 監控代碼行數和複雜度
 3. **開發後** - 進行完成檢查清單驗證
 4. **部署前** - 確認所有控制規則都遵守
 ### **團隊協作**
 - **代碼審查** - 重點檢查複雜度控制
 - **功能討論** - 先問"真的需要嗎？"
 - **技術選型** - 總是選擇最簡單方案
 - **架構決策** - 拒絕"為了未來"的設計
 **這個規範的目標: 確保複習功能永遠保持簡單、可用、易維護！**
 ---
 *開發控制規範制定: 2025-10-03*
 *基於實際過度工程失敗經驗*
 *強制執行級別: 必須遵守*