dramaling-vocab-learning/note/複習系統/開發控制規範.md

# 複習系統開發控制規範

**目的**: 防止過度工程，確保開發不失控
**適用範圍**: 複習功能的所有開發工作
**強制級別**: 必須遵守
**最後更新**: 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*
*基於實際過度工程失敗經驗*
*強制執行級別: 必須遵守*