371 lines
17 KiB
Markdown
371 lines
17 KiB
Markdown
# 詞彙學習功能規格文檔 (Enhanced Version)
|
||
|
||
## 📋 功能概述
|
||
|
||
**功能名稱**: 多媒體詞彙學習系統
|
||
**建立日期**: 2025-09-08
|
||
**最後更新**: 2025-09-12
|
||
**負責團隊**: 產品/設計/開發
|
||
**原型參考**: `/docs/02_design/prototypes/screens/phase2/05-vocabulary-learning-enhanced.html`
|
||
|
||
### 主要功能
|
||
- **沉浸式詞彙展示**: 詞彙、音標、定義、多媒體整合展示
|
||
- **雙語音頻系統**: 正常速度與慢速發音，支援詞彙與例句
|
||
- **智慧詞彙標註**: 自動標註例句中的目標詞彙及其變形
|
||
- **雙重語境學習**: Source（來源語境）+ Example（教學例句）
|
||
- **視覺輔助學習**: 例句配圖增強理解和記憶
|
||
- **多詞彙導航**: 同一關卡內多個詞彙間無縫切換
|
||
- **進度可視化**: 即時學習進度和完成狀態追蹤
|
||
|
||
### 適用場景
|
||
- **第1關詞彙學習**: 線性闖關學習系統的核心環節
|
||
- **劇本相關詞彙**: 每個劇本包含5個核心詞彙的深度學習
|
||
- **情境詞彙掌握**: 為後續情境對話做好詞彙準備
|
||
- **自主詞彙複習**: 詞彙掌握後的重複學習和鞏固
|
||
|
||
### 與其他功能的關聯
|
||
- **線性闖關系統**: 作為第1關，完成後解鎖第2關（詞彙熟悉）
|
||
- **情境對話系統**: 學習的詞彙將在第3關情境對話中要求使用
|
||
- **口說練習系統**: 可選的第2+關，針對詞彙進行發音訓練
|
||
- **學習地圖系統**: 每個劇本的詞彙學習進度影響整體關卡解鎖
|
||
- **複習系統**: 完成的詞彙自動加入複習清單
|
||
|
||
## 📱 涉及的UI畫面
|
||
|
||
### 主要畫面
|
||
1. **UI_Vocab_Learning_Enhanced** - 多媒體詞彙學習主界面
|
||
- 整合詞彙展示、音頻播放、例句學習於單一畫面
|
||
- 支援多詞彙間的無縫切換導航
|
||
- 包含完整的多媒體學習體驗
|
||
|
||
### 相關畫面（後續關卡）
|
||
1. **UI_Vocab_Choice_Practice** - 第1關完成後的選擇題測試
|
||
2. **UI_Vocab_Mastery_Practice** - 第2關詞彙熟悉練習
|
||
3. **UI_Speaking_Practice** - 第2+關口說練習（可選付費）
|
||
4. **UI_Situational_Dialogue** - 第3關情境對話應用
|
||
|
||
## 🎯 詳細畫面規格
|
||
|
||
### UI_Vocab_Learning_Enhanced - 多媒體詞彙學習主界面
|
||
|
||
#### 功能說明
|
||
- **畫面目的**: 提供完整的詞彙學習體驗，包含詞彙展示、音頻學習、例句理解和視覺輔助
|
||
- **進入條件**: 從學習地圖進入劇本的第1關詞彙學習，或從複習系統進入
|
||
- **退出條件**: 完成所有5個詞彙的學習，進入選擇題測試階段
|
||
|
||
#### 畫面欄位細節
|
||
|
||
| 欄位名稱 | 資料類型 | 必填 | 預設值 | 驗證規則 | 顯示條件 |
|
||
|---------|---------|------|--------|----------|----------|
|
||
| 詞彙本體 | 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. **詞彙認知階段**:
|
||
- 查看詞彙拼寫和CEFR等級 → 聽取正常/慢速發音 → 理解英文定義
|
||
2. **語境學習階段**:
|
||
- 閱讀Example例句並查看配圖 → 播放例句音頻加深印象 → 觀察詞彙在句中的使用
|
||
3. **來源語境階段**:
|
||
- 閱讀Source來源句子 → 理解詞彙的真實使用語境 → 對比Example和Source的差異
|
||
4. **詞彙導航階段**:
|
||
- 使用Previous/Next按鈕切換詞彙 → 觀察進度點變化 → 完成所有5個詞彙學習
|
||
5. **完成轉換階段**:
|
||
- 學完所有詞彙後 → 系統提示進入測試 → 跳轉至選擇題階段
|
||
|
||
#### 異常狀況處理
|
||
- **音檔載入失敗**: 顯示載入中圖示 → 重新嘗試載入 → 提供離線模式提示
|
||
- **網路中斷**: 保存當前學習進度 → 顯示離線模式 → 提供快取內容
|
||
- **內容載入錯誤**: 顯示錯誤提示 → 提供重試選項 → 或跳到下一個詞彙
|
||
|
||
### UI_Vocab_Choice_Practice - 詞彙選擇練習頁面
|
||
|
||
#### 功能說明
|
||
- **畫面目的**: 透過選擇題形式測試用戶對詞彙的理解和記憶
|
||
- **進入條件**: 完成詞彙介紹，選擇練習模式
|
||
- **退出條件**: 完成所有選擇題，或命條歸零失敗
|
||
|
||
#### 畫面欄位細節
|
||
|
||
| 欄位名稱 | 資料類型 | 必填 | 預設值 | 驗證規則 | 顯示條件 |
|
||
|---------|---------|------|--------|----------|----------|
|
||
| 題目序號 | Number | 是 | 1 | 1-20 | 始終顯示 |
|
||
| 總題數 | Number | 是 | 10 | 5-20 | 始終顯示 |
|
||
| 題目內容 | String | 是 | - | 10-200字 | 始終顯示 |
|
||
| 題目類型 | String | 是 | - | 定義題/例句題/圖片題 | 始終顯示 |
|
||
| 選項A | String | 是 | - | 1-100字 | 始終顯示 |
|
||
| 選項B | String | 是 | - | 1-100字 | 始終顯示 |
|
||
| 選項C | String | 是 | - | 1-100字 | 始終顯示 |
|
||
| 選項D | String | 否 | - | 1-100字 | 四選一題型 |
|
||
| 題目圖片 | Image URL | 否 | - | 有效圖片格式 | 圖片題顯示 |
|
||
| 答題時間限制 | Number | 是 | 30 | 15-60秒 | 始終顯示 |
|
||
| 目前得分 | Number | 是 | 0 | 0-100 | 始終顯示 |
|
||
| 答對題數 | Number | 是 | 0 | 0-20 | 始終顯示 |
|
||
|
||
#### 互動元素
|
||
|
||
| 元素名稱 | 元素類型 | 點擊行為 | 狀態變化 | 備註 |
|
||
|---------|---------|----------|----------|------|
|
||
| 選項按鈕A-D | 單選按鈕 | 選擇答案選項 | 未選->已選 | 只能選擇一個選項 |
|
||
| 確認答案按鈕 | 按鈕 | 提交當前選擇 | 正常->已提交 | 選擇選項後啟用 |
|
||
| 題目發音按鈕 | 按鈕 | 播放題目中的詞彙 | 正常->播放中 | 聽力輔助功能 |
|
||
| 跳過題目按鈕 | 按鈕 | 跳過當前題目 | - | 允許跳過題目 |
|
||
| 暫停練習按鈕 | 按鈕 | 暫停當前練習 | 進行中->暫停 | 保存當前進度 |
|
||
| 退出練習按鈕 | 按鈕 | 退出練習模式 | - | 需要二次確認 |
|
||
|
||
### UI_Vocab_Fluency_Results - 流暢度練習綜合結果
|
||
|
||
#### 功能說明
|
||
- **畫面目的**: 展示用戶在各類詞彙練習中的綜合表現分析
|
||
- **進入條件**: 完成一輪詞彙練習（選擇題+圖片匹配+句子應用）
|
||
- **退出條件**: 查看完結果分析，選擇下一步行動
|
||
|
||
#### 畫面欄位細節
|
||
|
||
| 欄位名稱 | 資料類型 | 必填 | 預設值 | 驗證規則 | 顯示條件 |
|
||
|---------|---------|------|--------|----------|----------|
|
||
| 總體得分 | Number | 是 | 0 | 0-100 | 始終顯示 |
|
||
| 掌握度等級 | String | 是 | - | 初識/熟悉/應用/掌握 | 始終顯示 |
|
||
| 識別能力分數 | Number | 是 | 0 | 0-100 | 始終顯示 |
|
||
| 理解能力分數 | Number | 是 | 0 | 0-100 | 始終顯示 |
|
||
| 應用能力分數 | Number | 是 | 0 | 0-100 | 始終顯示 |
|
||
| 反應速度分數 | Number | 是 | 0 | 0-100 | 始終顯示 |
|
||
| 平均答題時間 | Number | 是 | 0 | ≥0秒 | 始終顯示 |
|
||
| 正確率 | Number | 是 | 0 | 0-100% | 始終顯示 |
|
||
| 薄弱點分析 | String | 是 | - | 50-200字 | 始終顯示 |
|
||
| 改進建議 | String | 是 | - | 100-300字 | 始終顯示 |
|
||
| 下次練習重點 | Array | 是 | [] | 建議陣列 | 始終顯示 |
|
||
| 獲得經驗值 | Number | 是 | 0 | ≥0 | 始終顯示 |
|
||
| 獲得獎勵 | Object | 否 | null | 獎勵物件 | 有獎勵時顯示 |
|
||
|
||
#### 互動元素
|
||
|
||
| 元素名稱 | 元素類型 | 點擊行為 | 狀態變化 | 備註 |
|
||
|---------|---------|----------|----------|------|
|
||
| 能力雷達圖 | 圖表 | 顯示各維度詳細分析 | - | 可互動的可視化圖表 |
|
||
| 重新練習按鈕 | 按鈕 | 重新開始詞彙練習 | - | 針對薄弱環節 |
|
||
| 進入複習按鈕 | 按鈕 | 將詞彙加入複習清單 | - | 安排後續複習 |
|
||
| 學習下個詞彙按鈕 | 按鈕 | 繼續下個詞彙學習 | - | 主要行動按鈕 |
|
||
| 查看詳細報告按鈕 | 按鈕 | 展開完整學習分析 | 收合->展開 | 更詳細的數據分析 |
|
||
| 分享成績按鈕 | 按鈕 | 分享到社交平台 | - | 增加社交互動 |
|
||
| 收藏錯題按鈕 | 按鈕 | 將答錯題目加入錯題本 | - | 便於後續複習 |
|
||
|
||
## 🔄 完整使用者流程
|
||
|
||
### 主要流程圖
|
||
```
|
||
[選擇詞彙學習關卡]
|
||
↓
|
||
[UI_Vocab_Introduction 詞彙介紹] → [理解詞彙基本資訊]
|
||
↓
|
||
[選擇練習模式] → [UI_Vocab_Choice_Practice 選擇題練習]
|
||
↓
|
||
[UI_Vocab_Fluency_Matching 圖片匹配] → [UI_Vocab_Fluency_Reorganize 句子重組]
|
||
↓
|
||
[UI_Vocab_Fluency_Results 結果分析] → [決定下一步行動]
|
||
```
|
||
|
||
### 分支流程
|
||
- **重點複習**: 表現不佳的詞彙 → 加入複習清單 → 安排間隔複習
|
||
- **進階挑戰**: 掌握良好的詞彙 → 進入應用練習 → 整合到對話訓練
|
||
- **相關擴展**: 學習相關詞彙 → 詞彙族群學習 → 主題式詞彙掌握
|
||
|
||
### 錯誤流程
|
||
- **答題錯誤**: 顯示正確答案 → 提供解釋說明 → 加入錯題複習
|
||
- **命條不足**: 學習無法啟動 → 提供命條購買 → 或等待自然恢復 → 重新開始學習
|
||
- **網路問題**: 保存學習進度 → 提供離線模式 → 同步恢復功能
|
||
|
||
## 📋 數據模型規格
|
||
|
||
### 詞彙數據結構 (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 // 當前播放狀態的按鈕
|
||
}
|
||
```
|
||
|
||
## 📊 商業邏輯規則
|
||
|
||
### 詞彙學習完成判定
|
||
- **單詞彙完成**: 用戶瀏覽完整詞彙資訊即視為完成（包含發音、定義、例句）
|
||
- **關卡完成**: 所有5個詞彙都被瀏覽過即完成第1關詞彙學習
|
||
- **進度追蹤**: 系統記錄每個詞彙的學習時間和互動行為
|
||
- **自動推進**: 完成所有詞彙後提示進入選擇題測試階段
|
||
|
||
### 命條消耗機制
|
||
> 詳細規格請參閱 → **[共同業務規則 - 命條系統](../common/business-rules.md#🎮-命條系統-life-points-system)**
|
||
|
||
- **關卡啟動**: 進入詞彙學習關卡時消耗1個命條
|
||
- **學習過程**: 學習過程中不消耗額外命條
|
||
- **完成獎勵**: 完成詞彙學習自動獲得3顆星
|
||
|
||
### 音頻播放邏輯
|
||
- **互斥播放**: 同時只能播放一個音頻，新播放會停止舊音頻
|
||
- **狀態管理**: 播放中的按鈕顯示特殊狀態（脈衝動畫）
|
||
- **重複播放**: 支援重複點擊播放同一音頻
|
||
- **載入失敗**: 音頻載入失敗時顯示友善提示
|
||
|
||
### 詞彙標註規則
|
||
- **精確匹配**: 使用正則表達式進行詞邊界匹配
|
||
- **變形處理**: 通過`originalHighlight`和`exampleHighlight`指定確切要標註的詞
|
||
- **視覺區分**: 標註的詞彙使用特殊樣式突出顯示
|
||
- **多語言支持**: 標註邏輯支援各種語言的詞彙變形
|
||
|
||
### 進度同步機制
|
||
- **即時保存**: 詞彙切換和學習行為立即保存到後端
|
||
- **離線支援**: 支援離線模式，網路恢復時同步進度
|
||
- **跨設備同步**: 學習進度在多設備間保持一致
|
||
|
||
## 🧪 測試要點
|
||
|
||
### 功能測試
|
||
- [ ] 詞彙數據載入和顯示正確性
|
||
- [ ] 音頻播放功能（正常/慢速/例句）
|
||
- [ ] 詞彙標註邏輯準確性
|
||
- [ ] 詞彙導航切換功能
|
||
- [ ] 進度指示器狀態更新
|
||
- [ ] 鍵盤快捷鍵支援
|
||
- [ ] 音頻互斥播放邏輯
|
||
- [ ] 學習進度自動保存
|
||
|
||
### 介面測試
|
||
- [ ] 響應式設計在不同設備正確顯示
|
||
- [ ] 音頻按鈕狀態變化和動畫
|
||
- [ ] 詞彙切換動畫流暢性
|
||
- [ ] 進度點視覺狀態準確
|
||
- [ ] 圖片載入和顯示正確
|
||
- [ ] 文字標註高亮效果
|
||
- [ ] 按鈉點擊反饋明確
|
||
|
||
### 整合測試
|
||
- [ ] 與線性闖關系統的解鎖邏輯
|
||
- [ ] 與命條系統的消耗結算
|
||
- [ ] 與學習地圖的進度同步
|
||
- [ ] 與複習系統的詞彙加入
|
||
- [ ] 音頻CDN載入效能
|
||
- [ ] 離線模式數據持久化
|
||
|
||
## 📝 開發注意事項
|
||
|
||
### 前端開發
|
||
- **音頻預載入**: 詞彙音頻文件需要智慧預載入策略，平衡載入速度和流量消耗
|
||
- **狀態管理**: 音頻播放狀態、詞彙索引、學習進度需要統一狀態管理
|
||
- **響應式設計**: 確保在手機、平板、桌面設備的一致體驗
|
||
- **離線支援**: 使用Service Worker實現關鍵詞彙數據的離線快取
|
||
- **動畫效果**: 使用CSS transition實現流暢的切換和狀態變化動畫
|
||
- **鍵盤支援**: 實現桌面端的鍵盤快捷鍵操作
|
||
|
||
### 後端開發
|
||
- **詞彙數據結構**: 設計靈活的詞彙數據模型，支援多語言和擴展
|
||
- **音頻文件管理**: 建立音頻文件CDN分發和版本管理機制
|
||
- **進度追蹤**: 實現精細的學習行為追蹤和分析
|
||
- **數據同步**: 設計可靠的跨設備數據同步機制
|
||
- **效能優化**: 詞彙數據的分批載入和智慧預取
|
||
- **A/B測試**: 支援不同詞彙展示策略的效果測試
|
||
|
||
### 整合注意事項
|
||
- **音頻最佳化**: 使用適當的音頻格式和壓縮率，支援多格式fallback
|
||
- **圖片最佳化**: Example圖片需要WebP格式支援和適當尺寸
|
||
- **數據安全**: 學習進度和詞彙數據需要加密傳輸和儲存
|
||
- **監控告警**: 關鍵學習路徑的效能監控和異常告警
|
||
- **國際化**: 支援多語言界面和詞彙內容本地化
|
||
|
||
## 📚 參考資源
|
||
|
||
- **原型畫面**: `/docs/02_design/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規格 | |
|
||
| | | - 整合線性闖關系統邏輯 | |
|
||
| | | - 優化音頻播放和詞彙標註機制 | |
|
||
|
||
---
|
||
|
||
**文檔狀態**: 🟢 已完成 (v2.0)
|
||
**最後檢查**: 2025-09-12
|
||
**下次檢查**: 2025-09-19
|
||
**原型實現**: ✅ 完整實現於 enhanced 版本 |