dramaling-app/projects/vocabulary-learning-web-development-plan.md

詞彙學習功能開發計劃 (Web版)

📊 專案概要

專案名稱: 詞彙學習功能 (Web版)
規劃日期: 2025-09-10
規格來源: 基於docs/02_design/function-specs/web/vocabulary-learning-web.md
視覺設計源: 基於docs/02_design/html-prototypes/pages/vocabulary.html
技術架構源: 基於docs/04_technical/03_frontend/vue-frontend-architecture.md
開發標準源: 基於docs/04_technical/03_frontend/vue-development-standards.md

預估時程: 6-8週
預計團隊: 3-4人 (前端2人、後端1-2人)
狀態: 📋 規劃中

🎯 功能範圍分析

核心功能模組 (依據function-specs)

1. 詞彙介紹系統 - Page_Vocab_Introduction_W

   • 多列布局：左側詞彙資訊，右側相關詞彙和例句
   • 詞典整合：滑鼠懸停即時顯示釋義，右鍵查詢外部詞典
   • 筆記功能：內建筆記編輯器，支援Markdown格式
   • 書籤管理：瀏覽器書籤整合

2. 練習系統 - 選擇題、圖片匹配、句子重組

   • Page_Vocab_Choice_Practice_W - 詞彙選擇練習頁面
   • Page_Vocab_Fluency_Matching_W - 圖片匹配練習頁面
   • Page_Vocab_Fluency_Reorganize_W - 句子重組練習頁面

3. 複習系統 - 間隔複習演算法

   • Page_Vocab_Review_Main_W - 詞彙複習主頁面

4. 分析儀表板 - Web專用數據視覺化

   • Page_Vocab_Analytics_Dashboard_W - 詞彙學習分析儀表板

5. 快捷鍵系統 - 全鍵盤操作支援 (依據function-specs Web版特色)

Web端特色功能 (依據function-specs)

• 多標籤學習支援
• 筆記編輯器 (Markdown)
• 瀏覽器書籤整合
• 高級數據分析和匯出
• PWA支援

🏗️ 技術架構設計

前端技術棧 (依據vue-frontend-architecture.md)

核心框架: Vue 3.4+ / TypeScript 5.x / Composition API
狀態管理: Pinia 2.1+
路由管理: Vue Router 4.3+
UI框架: Quasar Framework 2.16+ (依據架構推薦)
建構工具: Vite 5.x
測試框架: Vitest 1.6.x + Vue Test Utils 2.4.x
PWA支援: @vitejs/plugin-pwa 0.20.x
代碼檢查: ESLint 9.x + Prettier 3.x

視覺設計規範 (依據vocabulary.html原型)

布局系統:
  - 280px固定側邊欄 (與dashboard保持一致)
  - 主內容區: flex: 1, margin-left: 280px
  - 響應式卡片布局: border-radius: var(--radius-xl)

色彩系統:
  - 主色調: var(--primary-teal) #00e5cc
  - 背景: var(--bg-card), var(--bg-secondary)
  - 文字: var(--text-primary), var(--text-secondary)
  - 邊框: var(--divider)

組件規格:
  - 詞彙卡片: .vocabulary-card, max-width: 600px, text-align: center
  - 詞彙文字: font-size: var(--text-5xl), font-weight: 700
  - 音標: font-size: var(--text-xl), color: var(--text-secondary)
  - 控制按鈕: .control-btn, border-radius: var(--radius-lg)

資料模型設計 (依據function-specs)

詞彙模型 (VocabularyWord):
  - id: 唯一識別碼
  - text: 詞彙文字 (1-50字)
  - phonetic: 音標 (IPA音標格式)
  - definition_chinese: 中文定義 (10-100字)
  - definition_english?: 英文定義 (10-200字, 可選)
  - part_of_speech: 詞性標記 (n./v./adj.等)
  - examples: 例句陣列 (10-100字 × 1-5個)
  - usage_context: 使用情境說明 (20-200字)
  - related_words?: 相關詞彙推薦
  - frequency_rating: 詞頻統計 (1-5星評級)
  - audio_url: 音頻檔案路徑
  - difficulty_level: 難度等級
  - user_notes?: 用戶筆記

學習進度 (Progress):
  - user_id: 使用者ID
  - vocabulary_id: 詞彙ID
  - mastery_level: 掌握程度 (0-100)
  - last_studied: 最後學習時間
  - review_count: 複習次數
  - error_patterns: 錯誤模式

練習記錄 (Exercise):
  - session_id: 學習會話ID
  - exercise_type: 練習類型
  - response_time: 反應時間
  - accuracy: 正確率
  - timestamp: 時間戳記

📅 開發階段規劃

第一階段 (Week 1-2): 基礎架構

Week 1: 專案設置 (依據vue-development-standards.md)

• Vue 3 + Quasar專案初始化和技術棧配置
  • 設置Vite 5.x建構環境
  • 配置TypeScript 5.x強型別支援
  • 整合ESLint 9.x + Prettier 3.x代碼檢查
• Quasar UI組件庫和設計系統建立
  • 實現vocabulary.html原型的色彩變數系統
  • 建立280px側邊欄佈局結構
  • 設置響應式卡片布局組件
• Vue Router路由結構和頁面骨架
  • 設置所有Page_Vocab_*_W路由
  • 實現基礎頁面組件結構
• Pinia狀態管理和API客戶端設置
  • 建立vocabulary store (依據development-standards)
  • 設置API服務層架構
• Vite開發環境和構建流程配置
  • PWA plugin配置
  • 自動導入組件設置

交付物: 可運行的專案骨架，符合HTML原型視覺設計

Week 2: 詞彙介紹頁面 (Page_Vocab_Introduction_W)

• 實現HTML原型的完整視覺布局
  • 280px固定側邊欄
  • vocabulary-card組件 (max-width: 600px, 居中)
  • vocabulary-word樣式 (text-5xl, font-weight: 700)
• Web Audio API音頻播放系統整合
  • 發音播放按鈕 (快捷鍵: Space)
  • 慢速發音按鈕 (快捷鍵: Shift+Space)
  • 例句發音按鈕 (快捷鍵: 1-5)
• Vue 3快捷鍵系統框架實現 (依據function-specs)
  • 收藏功能 (Ctrl+D) - 瀏覽器書籤整合
  • 筆記編輯器 (Ctrl+N) - 支援Markdown
  • 詞典查詢 (F1) - 外部詞典整合
• 多列布局實現 (依據function-specs)
  • 左側詞彙資訊區域
  • 右側相關詞彙和例句面板
• Quasar響應式設計實現

交付物: 完整的詞彙介紹頁面，嚴格遵循HTML原型設計和function-specs

第二階段 (Week 3-4): 練習系統

Week 3: 基礎練習功能

• 選擇題練習頁面 (Page_Vocab_Choice_Practice_W)
  • 實現HTML原型的mode-card布局設計
  • 練習邏輯和狀態管理 (依據Pinia規範)
  • 反應時間測量系統
• 結果分析頁面 (Page_Vocab_Choice_Results_W)
  • 統計卡片視覺呈現
  • 錯誤模式分析
• 本地存儲和離線支援 (PWA功能)

交付物: 可用的選擇題練習系統

Week 4: 進階練習功能

• 圖片匹配練習 (Page_Vocab_Fluency_Matching_W)
• 句子重組練習 (Page_Vocab_Fluency_Reorganize_W)
• 流暢度評估演算法
• 綜合結果頁面 (Page_Vocab_Fluency_Results_W)
• 多練習模式整合

交付物: 完整的練習系統

第三階段 (Week 5-6): 複習系統和分析

Week 5: 複習系統

• 間隔複習演算法實現
• 複習主頁面 (Page_Vocab_Review_Main_W)
• 學習計劃生成
• 薄弱點識別系統
• 複習提醒和通知

交付物: 智能複習系統

Week 6: 分析儀表板 (Web專用功能)

• 分析儀表板頁面 (Page_Vocab_Analytics_Dashboard_W)
  • 實現HTML原型的統計卡片布局
  • header-stats區域視覺實現
• 數據視覺化圖表 (依據架構推薦的圖表庫)
• 報告生成和匯出功能
• 學習建議系統
• 列印友善格式

交付物: 完整的數據分析系統

第四階段 (Week 7-8): 整合和優化

Week 7: Web端特色功能整合

• Vue多標籤學習支援實現 (依據function-specs)
• 瀏覽器書籤整合功能
• Quasar PWA功能實現
• 離線模式和Service Worker優化
• Pinia數據同步機制

交付物: 完整的Web應用

Week 8: 測試和部署

• Vitest + Vue Test Utils單元測試和集成測試 (依據standards)
• 跨瀏覽器相容性測試
• Vite打包優化和效能測試
• 無障礙性測試
• 生產環境部署和Quasar PWA發布

交付物: 可部署的生產版本

👥 團隊分工建議

前端開發 (2人)

前端Lead (Senior):

• Vue 3 + Composition API架構設計 (依據development-standards)
• 複雜頁面開發 (詞彙介紹、分析儀表板)
• Pinia狀態管理和API整合
• Vite效能優化和Quasar PWA功能

前端開發者 (Mid-level):

• Vue練習頁面開發 (依據HTML原型)
• Quasar UI元件開發
• Vue快捷鍵系統實現
• Vitest測試撰寫

後端開發 (1-2人)

後端開發者:

• API端點開發 (依據data models)
• 資料庫設計和優化
• 音頻服務整合
• 學習演算法實現

📋 關鍵里程碑

里程碑	完成日期	交付內容	驗收標準
M1: 基礎架構	Week 2	符合HTML原型的專案骨架和詞彙介紹頁	視覺100%符合vocabulary.html原型，可瀏覽詞彙，播放音頻
M2: 練習系統	Week 4	完整練習功能	3種練習模式正常運行，視覺符合原型
M3: 複習分析	Week 6	複習和分析功能	智能複習安排和數據圖表，符合function-specs
M4: 整合上線	Week 8	完整Web應用	通過所有測試，PWA功能正常，可生產部署

⚠️ 風險識別和緩解

技術風險

風險	可能性	影響	緩解策略
HTML原型vs實際實現差異	中	高	每個milestone嚴格對照HTML原型驗收
Web Audio API 相容性問題	中	高	提前進行瀏覽器測試，準備fallback方案
Quasar組件客製化複雜度	中	中	評估原生HTML/CSS實現vs Quasar組件

規格一致性風險

風險	可能性	影響	緩解策略
偏離function-specs定義	高	高	每週review對照function-specs檢查清單
HTML原型視覺不一致	高	高	像素級對照原型，設置自動化視覺測試
快捷鍵系統規格遺漏	中	中	完整實現function-specs定義的所有快捷鍵

📊 品質保證策略

規格合規檢查

每週檢查清單:
  視覺設計合規:
    - 對照vocabulary.html原型像素級檢查
    - 色彩系統100%使用原型CSS變數
    - 布局結構嚴格遵循原型
  
  功能規格合規:
    - 對照vocabulary-learning-web.md功能檢查表
    - Web端特色功能完整實現
    - 頁面欄位細節100%實現
  
  技術架構合規:
    - Vue 3 Composition API使用規範
    - Quasar Framework整合規範
    - development-standards代碼規範

測試策略 (依據development-standards)

單元測試:
  - 覆蓋率目標: 80%
  - 關鍵業務邏輯必須覆蓋
  - 使用Vitest + Vue Test Utils

集成測試:
  - API整合測試
  - 用戶流程端到端測試
  - 使用Playwright

效能測試:
  - 頁面載入時間 < 3秒
  - 音頻播放延遲 < 200ms
  - 使用Lighthouse和WebPageTest

🔧 開發工具和環境

開發環境 (依據vue-frontend-architecture.md)

IDE: VS Code + 推薦擴展包
版本控制: Git + GitHub/GitLab
專案管理: 依據原有系統
溝通工具: 依據團隊慣例

CI/CD:
  - 自動化測試和部署
  - 代碼品質檢查
  - HTML原型視覺回歸測試

📈 成功指標

技術指標

• 頁面載入時間 < 3秒
• 音頻播放成功率 > 98%
• 跨瀏覽器相容性 > 95%
• 代碼測試覆蓋率 > 80%

規格合規指標

• HTML原型視覺還原度 = 100%
• function-specs功能實現率 = 100%
• Web端特色功能實現率 = 100%
• 快捷鍵系統完整度 = 100%

💰 資源需求評估

人力成本

前端開發 (2人 × 8週): 16人週
後端開發 (1人 × 6週): 6人週
測試和QA (0.5人 × 4週): 2人週
專案管理 (0.2人 × 8週): 1.6人週
總計: 25.6人週

技術成本

開發工具授權: $500/月
第三方服務: $200/月
雲端服務: $300/月
測試設備: $1000 (一次性)

🚀 部署策略

階段性部署

1. 內部測試 (Week 7): 內部團隊測試
2. 規格驗收 (Week 8): 嚴格對照所有specification文檔驗收
3. Beta測試 (上線第1週): 小範圍使用者測試
4. 全面上線 (上線第2週): 100%使用者

監控和維護

• 實時效能監控
• 錯誤報告和快速修復
• 使用者反饋收集
• 定期效能優化

📋 下一步行動

立即行動 (本週)

1. 確認技術棧和架構決策
2. 設置開發環境和工具
3. 建立專案repository和CI/CD
4. 開始UI設計系統開發 (嚴格對照vocabulary.html)

短期目標 (2週內)

1. 完成專案初始化
2. API設計和Mock數據準備
3. 第一個頁面原型完成 (像素級對照HTML原型)
4. 團隊開發流程建立

---

📊 規劃完成: 2025-09-10
🔄 狀態: ✅ 已完成規劃，嚴格基於specification文檔，待開始執行
📋 下一步: 確認團隊資源並開始第一階段開發
📖 合規基礎:

• 視覺設計: /docs/02_design/html-prototypes/pages/vocabulary.html
• 功能規格: /docs/02_design/function-specs/web/vocabulary-learning-web.md
• 技術架構: /docs/04_technical/03_frontend/vue-frontend-architecture.md
• 開發標準: /docs/04_technical/03_frontend/vue-development-standards.md