# 詞彙學習功能規格文檔

## 📋 功能概述

**功能名稱**: 詞彙學習訓練系統  
**建立日期**: 2025-09-08  
**最後更新**: 2025-09-08  
**負責團隊**: 產品/設計/開發  

### 主要功能
- 漸進式詞彙學習路徑：介紹→練習→測試→複習
- 多維度練習模式：選擇題、圖片匹配、句子應用
- 流暢度評估系統：反應時間與正確率綜合評判
- 間隔複習機制：基於遺忘曲線的智能複習安排
- 個人化學習調整：根據表現動態調整難度和內容

### 適用場景
- 系統化詞彙學習和積累
- 特定情境詞彙的針對性訓練
- 詞彙記憶鞏固和長期保持
- 詞彙應用能力的實戰練習

### 與其他功能的關聯
- **情境對話系統**: 為對話提供詞彙基礎，指定詞彙在對話中使用
- **學習地圖系統**: 按階段解鎖詞彙學習內容  
- **複習系統**: 整合間隔複習演算法，安排詞彙複習
- **成就系統**: 詞彙掌握里程碑和學習成就追蹤

## 📱 涉及的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_Choice_Results** - 選擇題結果分析
2. **UI_Vocab_Fluency_Results** - 流暢度練習綜合結果
3. **UI_Vocab_Sentence_Results** - 句子應用結果分析

## 🎯 詳細畫面規格

### UI_Vocab_Introduction - 詞彙介紹主頁面

#### 功能說明
- **畫面目的**: 為用戶介紹新詞彙，包含發音、定義、例句和使用情境
- **進入條件**: 從學習地圖選擇詞彙學習關卡，或進入新的詞彙單元
- **退出條件**: 完成詞彙介紹，進入練習階段，或用戶主動退出

#### 畫面欄位細節

| 欄位名稱 | 資料類型 | 必填 | 預設值 | 驗證規則 | 顯示條件 |
|---------|---------|------|--------|----------|----------|
| 目標詞彙文字 | 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% | 始終顯示 |

#### 互動元素

| 元素名稱 | 元素類型 | 點擊行為 | 狀態變化 | 備註 |
|---------|---------|----------|----------|------|
| 發音播放按鈕 | 按鈕 | 播放詞彙標準發音 | 正常->播放中 | 支援重複播放 |
| 慢速發音按鈕 | 按鈕 | 播放慢速清楚發音 | 正常->播放中 | 幫助聽力理解 |
| 例句發音按鈕 | 按鈕 | 播放例句完整發音 | 正常->播放中 | 每個例句獨立播放 |
| 收藏按鈕 | 按鈕 | 加入/移出個人收藏 | 未收藏<->已收藏 | 方便後續複習 |
| 相關詞彙按鈕 | 按鈕 | 跳轉到相關詞彙學習 | - | 擴展學習內容 |
| 開始練習按鈕 | 按鈕 | 進入詞彙練習階段 | - | 主要行動按鈕 |
| 跳過介紹按鈕 | 按鈕 | 直接進入練習 | - | 熟悉用戶快速通道 |

#### 使用者操作流程
1. **詞彙展示**: 系統顯示目標詞彙 → 用戶閱讀基本資訊 → 點擊發音播放
2. **深度學習**: 閱讀定義和例句 → 理解使用情境 → 查看相關詞彙
3. **練習準備**: 確認理解程度 → 選擇練習模式 → 點擊開始練習
4. **跳轉選項**: 收藏重要詞彙 → 或跳過直接練習 → 或學習相關詞彙

#### 異常狀況處理
- **音檔載入失敗**: 顯示載入中圖示 → 重新嘗試載入 → 提供離線模式提示
- **網路中斷**: 保存當前學習進度 → 顯示離線模式 → 提供快取內容
- **內容載入錯誤**: 顯示錯誤提示 → 提供重試選項 → 或跳到下一個詞彙

### 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 結果分析] → [決定下一步行動]
```

### 分支流程
- **重點複習**: 表現不佳的詞彙 → 加入複習清單 → 安排間隔複習
- **進階挑戰**: 掌握良好的詞彙 → 進入應用練習 → 整合到對話訓練
- **相關擴展**: 學習相關詞彙 → 詞彙族群學習 → 主題式詞彙掌握

### 錯誤流程
- **答題錯誤**: 顯示正確答案 → 提供解釋說明 → 加入錯題複習 → 扣除命條
- **命條不足**: 學習中止 → 提供命條購買 → 或等待自然恢復 → 重新開始學習
- **網路問題**: 保存學習進度 → 提供離線模式 → 同步恢復功能

## 📊 商業邏輯規則

### 學習成效評估
- **掌握度分級**: 初識(0-25%) → 熟悉(26-60%) → 應用(61-85%) → 掌握(86-100%)
- **間隔複習安排**: 基於艾賓浩斯遺忘曲線，動態調整複習時機
- **難度自適應**: 根據用戶表現自動調整後續詞彙難度

### 命條消耗機制
- **答錯題目**: 扣除1個命條
- **跳過題目**: 視為答錯，扣除1個命條  
- **重複錯誤**: 同一詞彙反覆答錯繼續扣除命條

### 獎勵機制
- **完美通關**: 全對且用時短，獲得額外經驗值和鑽石獎勵
- **持續學習**: 連續學習天數獲得學習獎勵
- **詞彙里程碑**: 掌握詞彙數量達到特定數值獲得成就徽章

## 🧪 測試要點

### 功能測試
- [ ] 詞彙介紹資訊載入正確
- [ ] 發音播放功能正常
- [ ] 選擇題邏輯和計分準確
- [ ] 圖片匹配反應時間記錄
- [ ] 句子重組邏輯正確
- [ ] 結果分析計算準確
- [ ] 間隔複習安排合理
- [ ] 命條消耗機制正常

### 介面測試
- [ ] 雷達圖顯示正確且可互動
- [ ] 詞彙發音按鈕反應靈敏
- [ ] 選擇題選項點擊回饋明確
- [ ] 結果頁面動畫效果流暢
- [ ] 進度條更新即時準確

### 整合測試
- [ ] 與對話系統的詞彙同步
- [ ] 與複習系統的數據整合
- [ ] 與成就系統的里程碑觸發
- [ ] 與命條系統的消耗結算

## 📝 開發注意事項

### 前端開發
- 詞彙發音需要預載入，確保流暢播放
- 選擇題需要防止重複點擊和答案洩漏
- 雷達圖使用Canvas或SVG實現，支援動畫效果
- 結果分析需要數據可視化圖表庫

### 後端開發
- 詞彙掌握度算法需要考慮多維度因素
- 間隔複習演算法需要準確的時間計算
- 學習進度數據需要即時同步和備份
- 詞彙推薦算法基於用戶學習歷史

### 整合注意事項
- 音頻文件需要CDN加速，保證載入速度
- 詞彙數據庫需要支援多語言和更新
- 學習分析需要隱私保護和數據安全
- 複習提醒需要推送通知整合

## 📚 參考資源

- **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`

## 📅 版本歷史

| 版本 | 日期 | 修改內容 | 修改者 |
|-----|------|----------|--------|
| v1.0 | 2025-09-08 | 初始版本建立，基於User Flow規格整合 | Claude AI |

---

**文檔狀態**: 🟢 已完成  
**最後檢查**: 2025-09-08  
**下次檢查**: 2025-09-15