From 8bddc3b06dd4d62b7333f8fb920bf638854835cc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=84=AD=E6=B2=9B=E8=BB=92?= Date: Fri, 12 Sep 2025 00:26:27 +0800 Subject: [PATCH] feat: implement enhanced vocabulary learning system with multimedia interface MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Create immersive vocabulary learning prototype with Source/Example dual-context - Update business rules to support view-based completion (BR-VOCAB-01 to BR-VOCAB-03) - Enhance data models with originalHighlight/exampleHighlight for direct annotation - Modernize API specifications for multimedia vocabulary learning endpoints - Update progressive stage system to reflect no-pressure learning approach - Establish UI/UX guidelines for functional button design principles 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .../common/api-specifications.md | 77 +- .../function-specs/common/business-rules.md | 59 +- .../function-specs/common/data-models.md | 44 +- .../common/progressive-stage-system.md | 21 +- .../mobile/02_vocabulary-learning-mobile.md | 299 +++-- docs/02_design/ui-ux/ui-ux-guidelines.md | 25 + .../05-vocabulary-learning-enhanced.html | 1008 +++++++++++++++++ 7 files changed, 1404 insertions(+), 129 deletions(-) create mode 100644 prototypes/screens/phase2/05-vocabulary-learning-enhanced.html diff --git a/docs/02_design/function-specs/common/api-specifications.md b/docs/02_design/function-specs/common/api-specifications.md index c2da662..d143748 100644 --- a/docs/02_design/function-specs/common/api-specifications.md +++ b/docs/02_design/function-specs/common/api-specifications.md @@ -173,9 +173,10 @@ GET /vocabulary Authorization: Bearer Query Parameters: - language: string (required) - 語言代碼 -- level: number (optional) - 難度等級 1-5 +- level: string (optional) - CEFR等級 (A1/A2/B1/B2/C1/C2) - category: string (optional) - 詞彙分類 -- limit: number (optional) - 返回數量限制 +- stageId: string (optional) - 關卡ID (用於獲取特定關卡的詞彙) +- limit: number (optional) - 返回數量限制 (預設5) - offset: number (optional) - 偏移量 ``` @@ -189,16 +190,24 @@ Authorization: Bearer ```typescript interface VocabularyDetail { id: string; - word: string; - pronunciation: string; - definitions: Definition[]; - examples: Example[]; - audioUrl: string; - relatedWords: RelatedWord[]; + word: string; // 詞彙本體 (原形) + level: string; // CEFR等級 (A1/A2/B1/B2/C1/C2) + phonetic: string; // IPA音標 + definition: string; // 英文定義 + originalSentence: string; // Source句子 (學習者遇到的真實語境) + originalHighlight: string; // Source句子中要標註的詞 + exampleSentence: string; // Example句子 (教學例句) + exampleHighlight: string; // Example句子中要標註的詞 + audioFiles: { + word: string; // 詞彙發音音檔URL + example: string; // Example句子音檔URL + }; + imageUrl?: string; // Example句子配圖URL userProgress?: { masteryLevel: number; lastStudied: string; studyCount: number; + completed: boolean; // 是否已完成瀏覽 }; } ``` @@ -240,10 +249,12 @@ Content-Type: application/json { "type": "vocabulary" | "dialogue" | "review", "contentId": "content_uuid", + "stageId": "stage_uuid", // 關卡ID (適用於詞彙學習) "settings": { "difficulty": number, "timeLimit": number, - "hints": boolean + "hints": boolean, + "autoPlay": boolean // 自動播放音檔設定 } } ``` @@ -253,13 +264,46 @@ Content-Type: application/json interface SessionResponse { sessionId: string; content: LearningContent; - questions: Question[]; + vocabularyList?: VocabularyDetail[]; // 詞彙學習專用 + questions: Question[]; // 對話學習專用 timeLimit: number; lifePointsCost: number; + totalItems: number; // 總項目數 + currentIndex: number; // 當前項目索引 } ``` -### 提交答案 +### 記錄詞彙瀏覽進度 +```http +POST /learning/vocabulary/{vocabularyId}/viewed +Authorization: Bearer +Content-Type: application/json + +{ + "sessionId": "session_uuid", + "timeSpent": number, // 瀏覽時間(秒) + "audioPlayed": { + "word": boolean, // 是否播放詞彙音檔 + "example": boolean // 是否播放例句音檔 + } +} +``` + +**回應**: +```typescript +interface VocabularyViewResponse { + viewed: boolean; + progress: { + current: number; // 當前進度 + total: number; // 總項目數 + percentage: number; // 完成百分比 + }; + nextVocabularyId?: string; // 下一個詞彙ID + stageCompleted: boolean; // 是否完成關卡 +} +``` + +### 提交答案 (對話學習專用) ```http POST /learning/sessions/{sessionId}/answers Authorization: Bearer @@ -289,6 +333,13 @@ interface AnswerResponse { ```http POST /learning/sessions/{sessionId}/complete Authorization: Bearer +Content-Type: application/json + +{ + "completedItems": string[], // 已完成的詞彙ID列表 + "totalTimeSpent": number, // 總學習時間(秒) + "sessionType": "vocabulary" | "dialogue" | "review" +} ``` **回應**: @@ -298,8 +349,12 @@ interface SessionCompleteResponse { accuracy: number; xpGained: number; diamondsGained: number; + starsEarned: number; // 獲得星星數 (詞彙學習固定3星) + vocabulariesMastered: number; // 掌握的詞彙數量 achievementsUnlocked: Achievement[]; nextRecommendations: Recommendation[]; + stageCompleted: boolean; // 是否完成關卡 + nextStageId?: string; // 下一關卡ID } ``` diff --git a/docs/02_design/function-specs/common/business-rules.md b/docs/02_design/function-specs/common/business-rules.md index 7a0dbca..b866e34 100644 --- a/docs/02_design/function-specs/common/business-rules.md +++ b/docs/02_design/function-specs/common/business-rules.md @@ -26,9 +26,9 @@ ### 消耗場景 (四關闖關系統) | 場景 | 命條消耗 | 說明 | | -------------- | -------- | ---------------------------- | -| 第1關：詞彙學習 | 1個 | 啟動關卡時消耗，無論答對答錯 | +| 第1關：詞彙學習 | 1個 | 啟動關卡時消耗，學習過程免費 | | 第2關：詞彙熟悉 | 1個 | 啟動關卡時消耗，無論答對答錯 | -| 第2+關：口說練習特別關卡 | 0個 | 付費關卡，不消耗命條 | +| 第2+關：口說練習特別關卡 | 0個 | 付費關卡（5鑽石），不消耗命條 | | 第3關：情境對話 | 1個 | 啟動關卡時消耗，無論成功失敗 | | 對話有辱罵情形 | 3個 | 額外扣除懲罰 | @@ -220,6 +220,61 @@ ## 📈 學習進度系統 +### 📚 詞彙學習系統商業規則 (Vocabulary Learning Business Rules) + +#### BR-VOCAB-01: 多媒體詞彙學習機制 +```yaml +規則名稱: 沉浸式詞彙學習體驗 +適用範圍: 第1關詞彙學習關卡 +技術實現: + - 每個劇本固定包含5個核心詞彙 + - 詞彙數據結構: 原形+CEFR等級+IPA音標+英文定義+雙語境+多媒體 + - 音頻系統: 詞彙正常速度+慢速+例句音頻 + - 視覺輔助: 例句配圖增強記憶效果 +學習流程: + - 詞彙認知: 拼寫+發音+定義理解 + - 語境學習: Example例句+視覺輔助+音頻學習 + - 來源理解: Source句子展示真實使用語境 + - 導航學習: 5個詞彙間無縫切換 +完成判定: + - 單詞彙完成: 用戶瀏覽完整詞彙資訊即視為完成 + - 關卡完成: 所有5個詞彙都被瀏覽過即完成 + - 自動獎勵: 完成關卡自動獲得3顆星 + - 進度追蹤: 即時保存學習進度和行為數據 +``` + +#### BR-VOCAB-02: 智慧詞彙標註系統 +```yaml +規則名稱: 精確詞彙變形標註 +適用範圍: 所有詞彙例句和來源句 +技術實現: + - 直接標註法: 使用originalHighlight和exampleHighlight指定確切標註詞 + - 精確匹配: 正則表達式詞邊界匹配避免誤標 + - 視覺區分: 標註詞彙使用特殊樣式突出顯示 + - 多語言支援: 支援各種語言的詞彙變形處理 +標註規則: + - Source句子: 顯示學習者當初遇到詞彙的真實語境 + - Example句子: 教學用例句，配備圖片和音頻 + - 變形處理: 支援動詞時態、名詞複數等各種變形 + - 不重複標註: 避免對已標註內容的重複處理 +``` + +#### BR-VOCAB-03: 音頻播放業務邏輯 +```yaml +規則名稱: 互斥音頻播放管理 +適用範圍: 所有詞彙學習音頻功能 +技術實現: + - 互斥播放: 同時只能播放一個音頻，新播放停止舊音頻 + - 狀態管理: 播放中按鈕顯示脈衝動畫狀態 + - 重複播放: 支援用戶重複點擊播放同一音頻 + - 載入策略: 音頻智慧預載入平衡速度和流量 +按鈕設計原則: + - 功能明確按鈕: 無文字標註，純圖示設計（遵循UI/UX規範） + - 圓形設計: 音頻播放按鈕統一使用圓形設計 + - 即時回饋: 播放狀態的視覺回饋和動畫效果 + - 載入失敗: 音頻載入失敗時友善提示處理 +``` + ### 🎯 線性闖關系統 (Progressive Stage System) 基於 [線性闖關學習系統規格](./progressive-stage-system.md) 的核心業務規則： diff --git a/docs/02_design/function-specs/common/data-models.md b/docs/02_design/function-specs/common/data-models.md index a52b3df..0401052 100644 --- a/docs/02_design/function-specs/common/data-models.md +++ b/docs/02_design/function-specs/common/data-models.md @@ -345,29 +345,40 @@ interface EvaluationCriteria { speakingStar: SpeakingStarCriteria; // ⭐ 口說星標準 } -### Vocabulary - 詞彙數據 (整合四關系統) +### Vocabulary - 詞彙數據 (增強版多媒體詞彙學習) ```typescript interface Vocabulary { id: string; - word: string; // 詞彙本體 + word: string; // 詞彙本體 (原形) language: string; // 語言代碼 - // 詞彙資訊 - pronunciation: string; // IPA音標 + // 詞彙基本資訊 + level: string; // CEFR等級 (A1/A2/B1/B2/C1/C2) + phonetic: string; // IPA音標 (如 "/ˌrek.əˈmend/") partOfSpeech: string; // 詞性 difficulty: number; // 難度等級 1-5 frequency: number; // 使用頻率評分 wordType: 'word' | 'phrase' | 'idiom'; // 詞彙類型 - // 釋義 + // 多媒體詞彙學習數據結構 (基於增強版原型) + definition: string; // 英文定義 (主要定義) + originalSentence: string; // Source句子 (學習者遇到的真實語境) + originalHighlight: string; // Source句子中要標註的詞 (支援變形) + exampleSentence: string; // Example句子 (教學例句) + exampleHighlight: string; // Example句子中要標註的詞 (支援變形) + + // 音頻系統 (支援多種音頻) + audioFiles: VocabularyAudioFiles; + + // 視覺輔助 (例句配圖) + imageUrl?: string; // Example句子配圖URL + imageDescription?: string; // 圖片描述 + + // 傳統釋義系統 (向下相容) definitions: Definition[]; examples: Example[]; - // 音頻 - audioUrl: string; // 標準發音音頻URL - slowAudioUrl?: string; // 慢速發音音頻URL - - // 視覺學習輔助 + // 視覺學習輔助 (傳統) illustrationUrl?: string; // 示意圖URL illustrationEmoji?: string; // 表情符號表示 @@ -386,10 +397,23 @@ interface Vocabulary { masteryCount: number; // 被掌握的用戶數量 favoriteCount: number; // 被收藏的次數 + // 學習統計 (基於增強版使用數據) + viewCount: number; // 被瀏覽次數 + audioPlayCount: number; // 音頻播放次數 + averageViewTime: number; // 平均瀏覽時間(秒) + createdAt: Date; updatedAt: Date; } +// 詞彙音頻文件結構 (增強版多媒體支援) +interface VocabularyAudioFiles { + normal: string; // 詞彙正常速度音檔URL + slow: string; // 詞彙慢速音檔URL + example: string; // Example句子音檔URL + // 注意: 不包含original (Source句子音檔)，因為Source不提供音頻 +} + interface Definition { id: string; definition: string; // 定義文字 diff --git a/docs/02_design/function-specs/common/progressive-stage-system.md b/docs/02_design/function-specs/common/progressive-stage-system.md index cf08c3b..c26ff6c 100644 --- a/docs/02_design/function-specs/common/progressive-stage-system.md +++ b/docs/02_design/function-specs/common/progressive-stage-system.md @@ -29,18 +29,27 @@ Drama Ling 的核心闖關學習機制，採用線性順序闖關設計，確保 ## 🎮 主線+特別關卡機制 ### 第1關：詞彙學習 (Vocabulary Learning) -**功能目的**: 學習劇本相關的5個核心詞彙 +**功能目的**: 透過多媒體沉浸式體驗學習劇本相關的5個核心詞彙 **關卡類型**: 免費關卡 #### 關卡內容 -- [ ] **詞彙展示**: 顯示詞彙、詞義、例句、示意圖 -- [ ] **選擇題測試**: 根據示意圖選擇正確詞彙 (4選1) -- [ ] **錯誤重測**: 答錯的題目在最後重新測試 +- [x] **沉浸式詞彙瀏覽**: 學習者依序瀏覽5個詞彙的完整學習資料 +- [x] **多媒體學習體驗**: 詞彙音標、音檔、例句音檔、配圖完整呈現 +- [x] **雙語境展示**: Source句子(真實語境) + Example句子(教學例句) +- [x] **直接詞彙標註**: 使用originalHighlight/exampleHighlight進行精確標註 +- [x] **自由導航**: 用戶可自由前後瀏覽，無測試壓力的純學習體驗 + +#### 關卡介面特色 +- **響應式設計**: 適配行動裝置和桌面端的完整UI +- **音檔控制**: 獨立的詞彙和例句音檔播放按鈕(純圖示設計) +- **視覺層次**: 清楚的資訊層次劃分和視覺引導 +- **導航控制**: 直觀的上一個/下一個詞彙切換 #### 通關條件 -- **基本要求**: 所有詞彙題目都答對 +- **基本要求**: 瀏覽完所有5個詞彙即視為完成 +- **完成判定**: 無需測試，純粹的學習體驗導向 - **獎勵標準**: 通關自動獲得3顆星 -- **資源消耗**: 完全免費，答錯扣1命條 +- **資源消耗**: 完全免費，無命條消耗 - **解鎖效果**: 開啟第2關 #### 詞彙組合設計 diff --git a/docs/02_design/function-specs/mobile/02_vocabulary-learning-mobile.md b/docs/02_design/function-specs/mobile/02_vocabulary-learning-mobile.md index 4853391..8de745f 100644 --- a/docs/02_design/function-specs/mobile/02_vocabulary-learning-mobile.md +++ b/docs/02_design/function-specs/mobile/02_vocabulary-learning-mobile.md @@ -1,88 +1,100 @@ -# 詞彙學習功能規格文檔 +# 詞彙學習功能規格文檔 (Enhanced Version) ## 📋 功能概述 -**功能名稱**: 詞彙學習訓練系統 +**功能名稱**: 多媒體詞彙學習系統 **建立日期**: 2025-09-08 -**最後更新**: 2025-09-08 +**最後更新**: 2025-09-12 **負責團隊**: 產品/設計/開發 +**原型參考**: `/prototypes/screens/phase2/05-vocabulary-learning-enhanced.html` ### 主要功能 -- 漸進式詞彙學習路徑：介紹→練習→測試→複習 -- 多維度練習模式：選擇題、圖片匹配、句子應用 -- 流暢度評估系統：反應時間與正確率綜合評判 -- 間隔複習機制：基於遺忘曲線的智能複習安排 -- 個人化學習調整：根據表現動態調整難度和內容 +- **沉浸式詞彙展示**: 詞彙、音標、定義、多媒體整合展示 +- **雙語音頻系統**: 正常速度與慢速發音，支援詞彙與例句 +- **智慧詞彙標註**: 自動標註例句中的目標詞彙及其變形 +- **雙重語境學習**: Source（來源語境）+ Example（教學例句） +- **視覺輔助學習**: 例句配圖增強理解和記憶 +- **多詞彙導航**: 同一關卡內多個詞彙間無縫切換 +- **進度可視化**: 即時學習進度和完成狀態追蹤 ### 適用場景 -- 系統化詞彙學習和積累 -- 特定情境詞彙的針對性訓練 -- 詞彙記憶鞏固和長期保持 -- 詞彙應用能力的實戰練習 +- **第1關詞彙學習**: 線性闖關學習系統的核心環節 +- **劇本相關詞彙**: 每個劇本包含5個核心詞彙的深度學習 +- **情境詞彙掌握**: 為後續情境對話做好詞彙準備 +- **自主詞彙複習**: 詞彙掌握後的重複學習和鞏固 ### 與其他功能的關聯 -- **情境對話系統**: 為對話提供詞彙基礎，指定詞彙在對話中使用 -- **學習地圖系統**: 按階段解鎖詞彙學習內容 -- **複習系統**: 整合間隔複習演算法，安排詞彙複習 -- **成就系統**: 詞彙掌握里程碑和學習成就追蹤 +- **線性闖關系統**: 作為第1關，完成後解鎖第2關（詞彙熟悉） +- **情境對話系統**: 學習的詞彙將在第3關情境對話中要求使用 +- **口說練習系統**: 可選的第2+關，針對詞彙進行發音訓練 +- **學習地圖系統**: 每個劇本的詞彙學習進度影響整體關卡解鎖 +- **複習系統**: 完成的詞彙自動加入複習清單 ## 📱 涉及的UI畫面 ### 主要畫面 -1. **UI_Vocab_Introduction** - 詞彙介紹主頁面 -2. **UI_Vocab_Choice_Practice** - 詞彙選擇練習頁面 -3. **UI_Vocab_Fluency_Matching** - 圖片匹配練習頁面 -4. **UI_Vocab_Fluency_Reorganize** - 句子重組練習頁面 -5. **UI_Vocab_Review_Main** - 詞彙複習主頁面 +1. **UI_Vocab_Learning_Enhanced** - 多媒體詞彙學習主界面 + - 整合詞彙展示、音頻播放、例句學習於單一畫面 + - 支援多詞彙間的無縫切換導航 + - 包含完整的多媒體學習體驗 -### 結果反饋畫面 -1. **UI_Vocab_Choice_Results** - 選擇題結果分析 -2. **UI_Vocab_Fluency_Results** - 流暢度練習綜合結果 -3. **UI_Vocab_Sentence_Results** - 句子應用結果分析 +### 相關畫面（後續關卡） +1. **UI_Vocab_Choice_Practice** - 第1關完成後的選擇題測試 +2. **UI_Vocab_Mastery_Practice** - 第2關詞彙熟悉練習 +3. **UI_Speaking_Practice** - 第2+關口說練習（可選付費） +4. **UI_Situational_Dialogue** - 第3關情境對話應用 ## 🎯 詳細畫面規格 -### UI_Vocab_Introduction - 詞彙介紹主頁面 +### UI_Vocab_Learning_Enhanced - 多媒體詞彙學習主界面 #### 功能說明 -- **畫面目的**: 為用戶介紹新詞彙，包含發音、定義、例句和使用情境 -- **進入條件**: 從學習地圖選擇詞彙學習關卡，或進入新的詞彙單元 -- **退出條件**: 完成詞彙介紹，進入練習階段，或用戶主動退出 +- **畫面目的**: 提供完整的詞彙學習體驗，包含詞彙展示、音頻學習、例句理解和視覺輔助 +- **進入條件**: 從學習地圖進入劇本的第1關詞彙學習，或從複習系統進入 +- **退出條件**: 完成所有5個詞彙的學習，進入選擇題測試階段 #### 畫面欄位細節 | 欄位名稱 | 資料類型 | 必填 | 預設值 | 驗證規則 | 顯示條件 | |---------|---------|------|--------|----------|----------| -| 目標詞彙文字 | String | 是 | - | 1-50字 | 始終顯示 | -| 音標顯示 | String | 是 | - | IPA音標格式 | 始終顯示 | -| 中文定義 | String | 是 | - | 10-100字 | 始終顯示 | -| 英文定義 | String | 否 | - | 10-200字 | 進階模式顯示 | -| 詞性標記 | String | 是 | - | n./v./adj.等 | 始終顯示 | -| 例句1 | String | 是 | - | 10-100字 | 始終顯示 | -| 例句2 | String | 否 | - | 10-100字 | 進階詞彙顯示 | -| 例句3 | String | 否 | - | 10-100字 | 高難度詞彙顯示 | -| 使用情境說明 | String | 是 | - | 20-200字 | 始終顯示 | -| 相關詞彙推薦 | Array | 否 | [] | 詞彙陣列 | 有相關詞彙時 | -| 難度等級 | Number | 是 | 1-5 | 1-5等級 | 始終顯示 | -| 學習進度 | Number | 是 | 0 | 0-100% | 始終顯示 | +| 詞彙本體 | String | 是 | - | 1-50字 | 始終顯示 | +| CEFR等級標籤 | String | 是 | - | A1/A2/B1/B2/C1/C2 | 始終顯示 | +| IPA音標 | String | 是 | - | 標準IPA格式 | 始終顯示 | +| 英文定義 | String | 是 | - | 10-200字 | 始終顯示 | +| Source句子 | String | 是 | - | 5-100字 | 始終顯示 | +| Source高亮詞 | String | 是 | - | 詞彙變形 | 始終顯示 | +| Example句子 | String | 是 | - | 5-100字 | 始終顯示 | +| Example高亮詞 | String | 是 | - | 詞彙變形 | 始終顯示 | +| Example圖片URL | String | 否 | - | 有效圖片URL | 有圖片時顯示 | +| 詞彙正常速度音檔 | String | 是 | - | 音頻URL | 始終顯示 | +| 詞彙慢速音檔 | String | 是 | - | 音頻URL | 始終顯示 | +| Example句子音檔 | String | 是 | - | 音頻URL | 始終顯示 | +| 當前詞彙索引 | Number | 是 | 0 | 0-4 | 始終顯示 | +| 學習進度點 | Array | 是 | [0,0,0,0,0] | 進度狀態陣列 | 始終顯示 | #### 互動元素 | 元素名稱 | 元素類型 | 點擊行為 | 狀態變化 | 備註 | |---------|---------|----------|----------|------| -| 發音播放按鈕 | 按鈕 | 播放詞彙標準發音 | 正常->播放中 | 支援重複播放 | -| 慢速發音按鈕 | 按鈕 | 播放慢速清楚發音 | 正常->播放中 | 幫助聽力理解 | -| 例句發音按鈕 | 按鈕 | 播放例句完整發音 | 正常->播放中 | 每個例句獨立播放 | -| 收藏按鈕 | 按鈕 | 加入/移出個人收藏 | 未收藏<->已收藏 | 方便後續複習 | -| 相關詞彙按鈕 | 按鈕 | 跳轉到相關詞彙學習 | - | 擴展學習內容 | -| 開始練習按鈕 | 按鈕 | 進入詞彙練習階段 | - | 主要行動按鈕 | -| 跳過介紹按鈕 | 按鈕 | 直接進入練習 | - | 熟悉用戶快速通道 | +| 詞彙正常速度播放 | 音頻按鈕 | 播放詞彙標準發音 | 正常->播放中->正常 | 純圖示按鈕，無文字標註 | +| 詞彙慢速播放 | 音頻按鈕 | 播放詞彙慢速發音 | 正常->播放中->正常 | 學習發音輔助 | +| Example句子播放 | 音頻按鈕 | 播放例句語音 | 正常->播放中->正常 | 純圖示按鈕，圓形設計 | +| Previous Word按鈕 | 導航按鈕 | 切換到上一個詞彙 | - | 詞彙索引>0時啟用 | +| Next Word按鈕 | 導航按鈕 | 切換到下一個詞彙 | - | 主要導航按鈕 | +| 進度指示點 | 指示器 | 顯示當前詞彙位置 | 完成->當前->待學習 | 5個點表示5個詞彙 | +| 鍵盤快捷鍵支援 | 快捷鍵 | ←→切換詞彙，空格播放 | - | 提升操作效率 | #### 使用者操作流程 -1. **詞彙展示**: 系統顯示目標詞彙 → 用戶閱讀基本資訊 → 點擊發音播放 -2. **深度學習**: 閱讀定義和例句 → 理解使用情境 → 查看相關詞彙 -3. **練習準備**: 確認理解程度 → 選擇練習模式 → 點擊開始練習 -4. **跳轉選項**: 收藏重要詞彙 → 或跳過直接練習 → 或學習相關詞彙 +1. **詞彙認知階段**: + - 查看詞彙拼寫和CEFR等級 → 聽取正常/慢速發音 → 理解英文定義 +2. **語境學習階段**: + - 閱讀Example例句並查看配圖 → 播放例句音頻加深印象 → 觀察詞彙在句中的使用 +3. **來源語境階段**: + - 閱讀Source來源句子 → 理解詞彙的真實使用語境 → 對比Example和Source的差異 +4. **詞彙導航階段**: + - 使用Previous/Next按鈕切換詞彙 → 觀察進度點變化 → 完成所有5個詞彙學習 +5. **完成轉換階段**: + - 學完所有詞彙後 → 系統提示進入測試 → 跳轉至選擇題階段 #### 異常狀況處理 - **音檔載入失敗**: 顯示載入中圖示 → 重新嘗試載入 → 提供離線模式提示 @@ -186,87 +198,174 @@ - **命條不足**: 學習無法啟動 → 提供命條購買 → 或等待自然恢復 → 重新開始學習 - **網路問題**: 保存學習進度 → 提供離線模式 → 同步恢復功能 +## 📋 數據模型規格 + +### 詞彙數據結構 (VocabularyItem) +```javascript +{ + word: String, // 詞彙原形，如 "recommend" + level: String, // CEFR等級：A1/A2/B1/B2/C1/C2 + phonetic: String, // IPA音標："/ˌrek.əˈmend/" + definition: String, // 英文定義 + originalSentence: String, // Source來源句子 + originalHighlight: String, // Source句子中要標註的詞 + exampleSentence: String, // Example教學例句 + exampleHighlight: String, // Example句子中要標註的詞 + imageUrl: String, // Example例句配圖URL（可選） + audioFiles: { + normal: String, // 詞彙正常速度音檔URL + slow: String, // 詞彙慢速音檔URL + example: String // Example句子音檔URL + } +} +``` + +### 詞彙關卡數據 (VocabularyLevel) +```javascript +{ + stageId: Number, // 階段ID + scriptId: String, // 劇本ID + levelType: "vocabulary_learning", // 關卡類型固定值 + vocabularies: [VocabularyItem], // 5個詞彙的陣列 + learningObjectives: [String], // 學習目標列表 + estimatedTime: Number, // 預估學習時間（分鐘） + prerequisites: [String] // 前置條件檢查 +} +``` + +### 學習進度數據 (LearningProgress) +```javascript +{ + userId: String, // 用戶ID + stageId: Number, // 階段ID + scriptId: String, // 劇本ID + levelType: "vocabulary_learning", // 關卡類型 + currentVocabIndex: Number, // 當前詞彙索引 (0-4) + completedVocabs: [Boolean], // 各詞彙完成狀態 [true,false,true,false,false] + startTime: Date, // 開始學習時間 + totalTimeSpent: Number, // 總學習時間（秒） + isCompleted: Boolean, // 關卡是否完成 + completionTime: Date // 完成時間 +} +``` + +### 音頻播放狀態 (AudioPlayState) +```javascript +{ + currentPlayingType: String, // "normal"|"slow"|"example"|null + currentPlayingElement: AudioElement, // 當前播放的音頻元素 + playingButton: HTMLElement // 當前播放狀態的按鈕 +} +``` + ## 📊 商業邏輯規則 -### 學習成效評估 -- **掌握度分級**: 初識(0-25%) → 熟悉(26-60%) → 應用(61-85%) → 掌握(86-100%) -- **間隔複習安排**: 基於艾賓浩斯遺忘曲線，動態調整複習時機 -- **難度自適應**: 根據用戶表現自動調整後續詞彙難度 +### 詞彙學習完成判定 +- **單詞彙完成**: 用戶瀏覽完整詞彙資訊即視為完成（包含發音、定義、例句） +- **關卡完成**: 所有5個詞彙都被瀏覽過即完成第1關詞彙學習 +- **進度追蹤**: 系統記錄每個詞彙的學習時間和互動行為 +- **自動推進**: 完成所有詞彙後提示進入選擇題測試階段 ### 命條消耗機制 > 詳細規格請參閱 → **[共同業務規則 - 命條系統](../common/business-rules.md#🎮-命條系統-life-points-system)** -- **啟動關卡**: 進入詞彙學習關卡時消耗1個命條，無論答對答錯 -- **跳過題目**: 允許跳過，不額外扣除命條 +- **關卡啟動**: 進入詞彙學習關卡時消耗1個命條 +- **學習過程**: 學習過程中不消耗額外命條 +- **完成獎勵**: 完成詞彙學習自動獲得3顆星 -### 獎勵機制 -- **完美通關**: 全對且用時短，獲得額外經驗值和鑽石獎勵 -- **持續學習**: 連續學習天數獲得學習獎勵 -- **詞彙里程碑**: 掌握詞彙數量達到特定數值獲得成就徽章 +### 音頻播放邏輯 +- **互斥播放**: 同時只能播放一個音頻，新播放會停止舊音頻 +- **狀態管理**: 播放中的按鈕顯示特殊狀態（脈衝動畫） +- **重複播放**: 支援重複點擊播放同一音頻 +- **載入失敗**: 音頻載入失敗時顯示友善提示 + +### 詞彙標註規則 +- **精確匹配**: 使用正則表達式進行詞邊界匹配 +- **變形處理**: 通過`originalHighlight`和`exampleHighlight`指定確切要標註的詞 +- **視覺區分**: 標註的詞彙使用特殊樣式突出顯示 +- **多語言支持**: 標註邏輯支援各種語言的詞彙變形 + +### 進度同步機制 +- **即時保存**: 詞彙切換和學習行為立即保存到後端 +- **離線支援**: 支援離線模式，網路恢復時同步進度 +- **跨設備同步**: 學習進度在多設備間保持一致 ## 🧪 測試要點 ### 功能測試 -- [ ] 詞彙介紹資訊載入正確 -- [ ] 發音播放功能正常 -- [ ] 選擇題邏輯和計分準確 -- [ ] 圖片匹配反應時間記錄 -- [ ] 句子重組邏輯正確 -- [ ] 結果分析計算準確 -- [ ] 間隔複習安排合理 -- [ ] 命條消耗機制正常 +- [ ] 詞彙數據載入和顯示正確性 +- [ ] 音頻播放功能（正常/慢速/例句） +- [ ] 詞彙標註邏輯準確性 +- [ ] 詞彙導航切換功能 +- [ ] 進度指示器狀態更新 +- [ ] 鍵盤快捷鍵支援 +- [ ] 音頻互斥播放邏輯 +- [ ] 學習進度自動保存 ### 介面測試 -- [ ] 雷達圖顯示正確且可互動 -- [ ] 詞彙發音按鈕反應靈敏 -- [ ] 選擇題選項點擊回饋明確 -- [ ] 結果頁面動畫效果流暢 -- [ ] 進度條更新即時準確 +- [ ] 響應式設計在不同設備正確顯示 +- [ ] 音頻按鈕狀態變化和動畫 +- [ ] 詞彙切換動畫流暢性 +- [ ] 進度點視覺狀態準確 +- [ ] 圖片載入和顯示正確 +- [ ] 文字標註高亮效果 +- [ ] 按鈉點擊反饋明確 ### 整合測試 -- [ ] 與對話系統的詞彙同步 -- [ ] 與複習系統的數據整合 -- [ ] 與成就系統的里程碑觸發 +- [ ] 與線性闖關系統的解鎖邏輯 - [ ] 與命條系統的消耗結算 +- [ ] 與學習地圖的進度同步 +- [ ] 與複習系統的詞彙加入 +- [ ] 音頻CDN載入效能 +- [ ] 離線模式數據持久化 ## 📝 開發注意事項 ### 前端開發 -- 詞彙發音需要預載入，確保流暢播放 -- 選擇題需要防止重複點擊和答案洩漏 -- 雷達圖使用Canvas或SVG實現，支援動畫效果 -- 結果分析需要數據可視化圖表庫 +- **音頻預載入**: 詞彙音頻文件需要智慧預載入策略，平衡載入速度和流量消耗 +- **狀態管理**: 音頻播放狀態、詞彙索引、學習進度需要統一狀態管理 +- **響應式設計**: 確保在手機、平板、桌面設備的一致體驗 +- **離線支援**: 使用Service Worker實現關鍵詞彙數據的離線快取 +- **動畫效果**: 使用CSS transition實現流暢的切換和狀態變化動畫 +- **鍵盤支援**: 實現桌面端的鍵盤快捷鍵操作 ### 後端開發 -- 詞彙掌握度算法需要考慮多維度因素 -- 間隔複習演算法需要準確的時間計算 -- 學習進度數據需要即時同步和備份 -- 詞彙推薦算法基於用戶學習歷史 +- **詞彙數據結構**: 設計靈活的詞彙數據模型，支援多語言和擴展 +- **音頻文件管理**: 建立音頻文件CDN分發和版本管理機制 +- **進度追蹤**: 實現精細的學習行為追蹤和分析 +- **數據同步**: 設計可靠的跨設備數據同步機制 +- **效能優化**: 詞彙數據的分批載入和智慧預取 +- **A/B測試**: 支援不同詞彙展示策略的效果測試 ### 整合注意事項 -- 音頻文件需要CDN加速，保證載入速度 -- 詞彙數據庫需要支援多語言和更新 -- 學習分析需要隱私保護和數據安全 -- 複習提醒需要推送通知整合 +- **音頻最佳化**: 使用適當的音頻格式和壓縮率，支援多格式fallback +- **圖片最佳化**: Example圖片需要WebP格式支援和適當尺寸 +- **數據安全**: 學習進度和詞彙數據需要加密傳輸和儲存 +- **監控告警**: 關鍵學習路徑的效能監控和異常告警 +- **國際化**: 支援多語言界面和詞彙內容本地化 ## 📚 參考資源 -- **UI截圖**: - - `docs/02_design/views/UI_Vocab_Introduction.png` - - `docs/02_design/views/UI_Vocab_Choice_Practice.png` - - `docs/02_design/views/UI_Vocab_Fluency_Results.png` -- **User Flow**: `docs/04_technical/user-flow-specification.md` - 詞彙練習系統章節 -- **API文檔**: `docs/04_technical/api/vocabulary.md` -- **設計規範**: `docs/02_design/ui-ux-guidelines.md` +- **原型畫面**: `/prototypes/screens/phase2/05-vocabulary-learning-enhanced.html` +- **線性闖關系統**: `docs/02_design/function-specs/common/progressive-stage-system.md` +- **UI/UX設計規範**: `docs/02_design/ui-ux/ui-ux-guidelines.md` - 按鈕文字標注原則 +- **命條系統規則**: `docs/02_design/function-specs/common/business-rules.md` +- **口說練習系統**: `docs/02_design/function-specs/common/speaking-evaluation-specs.md` ## 📅 版本歷史 | 版本 | 日期 | 修改內容 | 修改者 | |-----|------|----------|--------| | v1.0 | 2025-09-08 | 初始版本建立，基於User Flow規格整合 | Claude AI | +| v2.0 | 2025-09-12 | 重大更新：基於enhanced原型重寫完整規格 | Claude AI | +| | | - 新增多媒體詞彙學習系統設計 | | +| | | - 完善數據模型和API規格 | | +| | | - 整合線性闖關系統邏輯 | | +| | | - 優化音頻播放和詞彙標註機制 | | --- -**文檔狀態**: 🟢 已完成 -**最後檢查**: 2025-09-08 -**下次檢查**: 2025-09-15 \ No newline at end of file +**文檔狀態**: 🟢 已完成 (v2.0) +**最後檢查**: 2025-09-12 +**下次檢查**: 2025-09-19 +**原型實現**: ✅ 完整實現於 enhanced 版本 \ No newline at end of file diff --git a/docs/02_design/ui-ux/ui-ux-guidelines.md b/docs/02_design/ui-ux/ui-ux-guidelines.md index e3fb1f2..3e017df 100644 --- a/docs/02_design/ui-ux/ui-ux-guidelines.md +++ b/docs/02_design/ui-ux/ui-ux-guidelines.md @@ -183,6 +183,31 @@ ### 按鈕組件 +#### 按鈕文字標注原則 *(新增重要原則)* +- [ ] **功能性按鈕**: 對於功能性操作按鈕（如播放、暫停、刪除等），如果按鈕本身功能明確且不會造成負面後果，應避免添加文字標注以減少畫面混亂 +- [ ] **高風險按鈕**: 對於可能造成負面影響的按鈕（如刪除、支付、退出等），必須包含清楚的文字標注以確保用戶理解操作後果 +- [ ] **圖示優先**: 當圖示本身足以表達功能且操作是可逆的或無風險的，優先使用純圖示按鈕 +- [ ] **一致性考量**: 同類型功能的按鈕在整個應用中保持一致的標注策略 + +**範例應用**: +```css +/* ✅ 正確：音頻播放按鈕 - 純圖示，功能明確且無風險 */ +.audio-play-btn { + display: flex; + align-items: center; + justify-content: center; + width: 40px; + height: 40px; + border-radius: 50%; + background: var(--primary-teal); +} + +/* ❌ 錯誤：支付按鈕 - 高風險操作必須有文字 */ +.payment-btn { + /* 必須包含 "確認支付" 等明確文字 */ +} +``` + #### 主要按鈕 (Primary Button) ```css .btn-primary { diff --git a/prototypes/screens/phase2/05-vocabulary-learning-enhanced.html b/prototypes/screens/phase2/05-vocabulary-learning-enhanced.html new file mode 100644 index 0000000..dfae485 --- /dev/null +++ b/prototypes/screens/phase2/05-vocabulary-learning-enhanced.html @@ -0,0 +1,1008 @@ + + + + + + Drama Ling - 詞彙學習 (增強版) + + + + +
+ +
+
+
📚
+
+
詞彙學習 - 第1關
+
餐廳點餐情境
+
+
+ + +
+
+
+
+
+
+
+
+
3/5
+
+
+ + +
+
+ +
+
+ optimal + B2 +
+
/ˈɒp.tɪ.məl/
+ + +
+
+
🔊
+
正常速度
+
+
+
🐌
+
慢速度
+
+
+
+ + +
+

+ 📖 + Definition 定義 +

+
+ The best or most effective possible in a particular situation. +
+
+ + +
+

+ 💬 + Examples 例句 +

+
+ +
+
Example
+
+ The optimal time to plant these seeds is in early spring. +
+
+ +
+ +
+
+ 🌱 Optimal Planting Time +
+
+ Visual example showing the concept in context +
+
+
+ + +
+
Source
+
+ For the optimal coding experience, enable the recommended settings. +
+
+
+
+ +
+
+ + +
+ + +
+
optimal
+
Word 3 of 5
+
+ + +
+
+ + + + + + + + + + + + \ No newline at end of file