jettcheng1018
/
dramaling-vocab-learning
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
dramaling-vocab-learning/note/複習系統/開發控制規範.md

5.9 KiB
Raw Permalink Blame History

複習系統開發控制規範

目的: 防止過度工程，確保開發不失控 適用範圍: 複習功能的所有開發工作 強制級別: 必須遵守 最後更新: 2025-10-03

🚨 複雜度控制規則 (強制)

代碼複雜度上限

// 嚴格限制
單個組件文件: < 200行
單個函數: < 20行
組件Props: < 8個
狀態變數: < 5個
useEffect依賴: < 5個
嵌套層次: < 3層

架構複雜度上限

// 系統層面限制
Store數量: 0個 (MVP階段禁止)
Service層: 0個 (MVP階段禁止)
抽象層次: < 2層
組件依賴: < 5個
API端點: < 3個

功能複雜度上限

// 功能範圍限制
測驗模式: 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. 考慮放棄功能 - 如果簡化後價值不大

📏 具體實作標準

狀態管理標準

// MVP階段只允許
✅ React useState
✅ 簡單的useEffect
✅ 基礎的useCallback (避免重新渲染)

// 禁止使用
❌ useReducer (除非狀態轉換 > 5個)
❌ Context API (除非組件樹 > 3層)
❌ 任何狀態管理庫

API調用標準

// MVP階段標準
✅ 直接fetch調用
✅ 簡單的錯誤處理
✅ 基礎的loading狀態

// 禁止
❌ 複雜的API抽象層
❌ 請求攔截器
❌ 複雜的緩存機制
❌ 狀態同步機制

組件設計標準

// 組件職責
✅ 單一職責原則
✅ 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 基於實際過度工程失敗經驗 強制執行級別: 必須遵守