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>
This commit is contained in:
parent
546db58146
commit
9307cb593d
|
|
@ -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*
|
||||
*基於複習功能開發經驗*
|
||||
*目標: 平衡詳細規格與開發控制*
|
||||
|
|
@ -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層
|
||||
|
||||
---
|
||||
|
||||
*技術實作規格維護者: 開發團隊*
|
||||
*版本控制: 與產品需求規格同步更新*
|
||||
*目的: 確保實作準確性，避免開發失控*
|
||||
|
|
@ -1,38 +1,88 @@
|
|||
|
||||
### **US-001: 智能複習排程**
|
||||
**作為**學習者
|
||||
**我希望**系統能根據我的學習表現智能安排復習時間
|
||||
**以便**我能在最佳時機復習，提高學習效率
|
||||
# 複習系統產品需求規格書 (MVP版本)
|
||||
|
||||
### **US-002: 逾期復習處理**
|
||||
**作為**忙碌的學習者
|
||||
**我希望**即使沒有按時復習，系統也能合理調整復習計劃
|
||||
**以便**我能重新回到正軌，不會因偶爾延遲而影響整體學習進度
|
||||
**版本**: 1.0 MVP
|
||||
**日期**: 2025-10-03
|
||||
**策略**: 階段性開發，避免過度工程
|
||||
**當前狀態**: 極簡MVP已完成 ✅
|
||||
|
||||
### **US-007: 聽力和口說練習**
|
||||
**作為**想要提升聽說能力的學習者
|
||||
**我希望**能進行詞彙聽力練習和例句朗讀練習
|
||||
**以便**全面提升我的語言技能
|
||||
---
|
||||
|
||||
- ✅ **詞彙選擇題** (vocab-choice): 定義匹配的客觀測試
|
||||
- ✅ **例句口說題** (sentence-speaking): 發音和表達練習
|
||||
## 🎯 **產品願景**
|
||||
|
||||
### **核心價值主張**
|
||||
幫助用戶通過**翻卡記憶**快速有效地複習詞彙，提升學習效率。
|
||||
|
||||
### **設計理念**
|
||||
- **簡單可用** > 功能完整
|
||||
- **用戶驗證** > 假設需求
|
||||
- **迭代進化** > 一次到位
|
||||
- **真實反饋** > 完美設計
|
||||
|
||||
- 進度條 = (今日完成)/(今日完成+今日到期)
|
||||
---
|
||||
|
||||
- 卡片延緩註記
|
||||
新增：
|
||||
1. 當使用者點選跳過時，將卡片註記一個延遲註記
|
||||
2. 當使用者答錯時，將卡片註記一個延遲註記
|
||||
判斷：
|
||||
撈出下一個複習卡片時，會排除有延遲註記的卡片
|
||||
修改：
|
||||
當使用者答對題目時，會消除延遲註記
|
||||
## 🚀 **階段1: 極簡MVP (當前版本)**
|
||||
|
||||
- 下一次複習時間 = 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` 詳細規定
|
||||
|
||||
|
|
|
|||
|
|
@ -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*
|
||||
*基於實際過度工程失敗經驗*
|
||||
*強制執行級別: 必須遵守*
|
||||
Loading…
Reference in New Issue