# 詞彙學習功能規格文檔 (Web版)

## 📋 功能概述

**功能名稱**: 四關線性闖關詞彙學習系統 (Web端)  
**建立日期**: 2025-09-11  
**最後更新**: 2025-09-11  
**負責團隊**: 前端Web/設計/開發  
**對應Mobile規格**: `../mobile/vocabulary-learning-mobile.md`

### 整合共用規範
> 本規格基於以下共用模組，請參閱對應規格文件：
> - **[線性闖關學習系統](../common/progressive-stage-system.md)** - 四關闖關機制
> - **[AI算法規格](../common/ai-algorithm-specs.md)** - AI學習支援系統
> - **[共同業務規則](../common/business-rules.md)** - 命條系統和付費機制
> - **[用戶流程規格](../common/comprehensive-user-flows-with-ui.md)** - 完整用戶流程
> - **[平台UI映射表](../common/platform-ui-mapping.md)** - Mobile/Web UI視圖對照

### 主要功能 (基於四關線性闖關)
- **第1關 詞彙學習**: 5個詞彙展示與選擇題測試
- **第2關 詞彙熟悉**: 例句重組與詞彙配對練習
- **第2+關 口說練習**: 付費特別關卡，五維口說評分
- **第3關 情境對話**: 綜合應用，雙重通關條件
- **間隔複習系統**: 基於遺忘曲線的智慧複習安排
- **個人化學習調整**: 根據表現動態調整難度和內容

### Web端特色功能
- **大螢幕四關同屏**: 桌面環境可同時預覽四關卡狀態
- **快捷鍵操作**: 支援鍵盤快捷鍵提升學習效率
- **多視窗支援**: 可同時開啟多個詞彙學習模組
- **進階統計面板**: 詳細的四關學習數據可視化分析
- **複習排程管理**: 桌面級的複習計劃和提醒系統

### 適用場景
- 辦公室或家中的深度詞彙學習時段
- 需要大量練習的詞彙熟悉階段
- 付費口說練習的精準發音訓練
- 多螢幕環境下的沉浸式四關闖關學習

### 與其他功能的關聯
- **情境對話系統**: 為情境對話提供5個指定詞彙基礎
- **學習地圖系統**: 按階段解鎖詞彙學習內容，完成四關才解鎖下一劇本
- **命條系統**: 整合 [共同業務規則](../common/business-rules.md#🎮-命條系統-life-points-system) 的生命管理機制
- **道具商店系統**: 整合口說練習付費機制和輔助道具
- **複習系統**: 整合間隔複習演算法，四關完成詞彙自動加入複習清單

## 🔄 Web版用戶流程對應

### 📱 流程參考
> **基礎流程**: [詞彙學習流程](../common/comprehensive-user-flows-with-ui.md#2️⃣-詞彙學習流程)
> **UI映射表**: [平台UI映射表 - 核心學習類](../common/platform-ui-mapping.md#-核心學習類)

### 💻 Web版流程轉換
基礎流程中的 `UI_*` 視圖對應到Web版的 `Page_*_W` 頁面：

```mermaid
flowchart TD
    A[Page_Level_Map_W: 學習地圖] -->|1個命條| B[Page_Vocab_Level1_Learning_W: 第1關詞彙學習]
    B --> C[Page_Vocab_Choice_Practice_W: 選擇題測試]
    C -->|通過| D[Page_Vocab_Level2_Mastery_W: 第2關詞彙熟悉]
    D -->|通過| E[Page_Vocab_Level2Plus_Speaking_W: 第2+關口說練習]
    E -->|通過| F[Page_Dialogue_Main_W: 第3關情境對話]
    F --> G[Page_Result_Success_A_W: 關卡完成]
```

### 🎆 Web版增強特色
- **四關同屏預覽**: 桌面環境可同時預覽四關卡狀態
- **快捷鍵操作**: 空格播放、←→切換詞彙
- **多視窗支援**: 可同時開啟多個詞彙學習模組
- **進階統計面板**: 詳細的四關學習數據可視化分析

## 💻 涉及的Web頁面 (四關架構)

### 主要關卡頁面
1. **Page_Vocab_Level1_Learning_W** - 第1關：詞彙學習頁面 (Web版)
2. **Page_Vocab_Level2_Mastery_W** - 第2關：詞彙熟悉頁面 (Web版)
3. **Page_Vocab_Level2Plus_Speaking_W** - 第2+關：口說練習特別關卡 (Web版)
4. **Page_Vocab_Review_Main_W** - 間隔複習主頁面 (Web版)

### 結果反饋頁面
1. **Page_Vocab_Level1_Results_W** - 第1關結果分析 (Web版)
2. **Page_Vocab_Level2_Results_W** - 第2關結果分析 (Web版)
3. **Page_Vocab_Speaking_Results_W** - 口說練習結果分析 (Web版)
4. **Page_Vocab_Progress_Dashboard_W** - 四關進度儀表板 (Web專用)

### 輔助功能頁面
1. **Page_Vocab_Overview_W** - 劇本詞彙總覽頁面 (Web專用)
2. **Page_Review_Schedule_W** - 複習排程管理頁面 (Web專用)

## 🎯 詳細頁面規格 (基於線性闖關系統)

### Page_Vocab_Level1_Learning_W - 第1關：詞彙學習頁面

#### 功能說明 (整合共用規範)
- **頁面目的**: 展示劇本5個核心詞彙，進行4選1選擇題測試
- **關卡機制**: 參考 [線性闖關學習系統 - 第1關](../common/progressive-stage-system.md#第1關詞彙學習-vocabulary-learning)
- **進入條件**: 從學習地圖選擇詞彙學習關卡，消耗1個命條
- **退出條件**: 完成所有詞彙題目，自動獲得3顆星

#### 詞彙組合設計標準
基於 [AI算法規格 - 共用詞彙設計](../common/ai-algorithm-specs.md#共用詞彙設計標準)：
- 3個常用單字 
- 1個常用片語
- 1個常用俚語

**範例組合**:
- 買菜小冒險: market, vegetables, price + "ask for a discount" + "a steal"
- 遲到的咖啡約會: coffee, late, apologize + "run into traffic" + "my bad"

#### 頁面欄位細節

| 欄位名稱 | 資料類型 | 必填 | 預設值 | 驗證規則 | 顯示條件 |
|---------|---------|------|--------|----------|----------|
| 劇本情境標題 | String | 是 | - | 5-30字 | 頁面頂部顯示 |
| 目標詞彙展示 | Array | 是 | - | 5個詞彙 | 大字體標題區域 |
| 音標顯示 | String | 是 | - | IPA音標格式 | 詞彙下方，支援點擊複製 |
| 中文定義 | String | 是 | - | 10-100字 | 主要定義區域 |
| 詞性標記 | String | 是 | - | n./v./adj.等 | 色彩編碼顯示 |
| 示意圖 | Image | 是 | - | 圖片URL | 視覺化學習輔助 |
| 例句展示 | String | 是 | - | 10-100字 | 語境使用範例 |
| 選擇題選項 | Array | 是 | - | 4選1 | 測試用選項列表 |
| 答題進度 | Number | 是 | 0 | 0-100% | 進度條顯示 |
| 命條狀態 | Number | 是 | - | >=0 | 右上角命條顯示 |

#### Web版互動元素

| 元素名稱 | 元素類型 | 操作方式 | 快捷鍵 | 狀態變化 | 備註 |
|---------|---------|----------|--------|----------|------|
| 發音播放按鈕 | 按鈕 | 點擊/空白鍵 | Space | 正常→播放中 | 支援重複播放 |
| 慢速發音按鈕 | 按鈕 | 點擊/Shift+Space | Shift+Space | 正常→播放中 | 0.5x-1.5x語速調節 |
| 選項選擇按鈕 | 按鈕組 | 點擊/A-D鍵 | A-D | 未選→已選 | 4選1單選 |
| 提交答案按鈕 | 按鈕 | 點擊/Enter | Enter | 正常→處理中 | 答題確認 |
| 下一題按鈕 | 按鈕 | 點擊/→鍵 | → | 正常→載入中 | 進入下一詞彙 |
| 詞彙收藏按鈕 | 按鈕 | 點擊/Ctrl+D | Ctrl+D | 未收藏↔已收藏 | 個人詞彙庫 |
| 跳過詞彙按鈕 | 按鈕 | 點擊/Shift+→ | Shift+→ | - | 快速通道 |

### Page_Vocab_Level2_Mastery_W - 第2關：詞彙熟悉頁面

#### 功能說明 (整合共用規範)
- **頁面目的**: 加深詞彙理解，訓練語境應用能力
- **關卡機制**: 參考 [線性闖關學習系統 - 第2關](../common/progressive-stage-system.md#第2關詞彙熟悉-vocabulary-mastery)
- **進入條件**: 完成第1關，消耗1個命條
- **退出條件**: 所有配對和重組正確，自動獲得3顆星

#### Web版佈局特點
- **左側**: 例句重組區域，拖拽式單字組合
- **右側**: 詞彙配對區域，示意圖與詞彙連線
- **底部**: 進度指示和操作按鈕

#### 頁面欄位細節

| 欄位名稱 | 資料類型 | 必填 | 預設值 | 驗證規則 | 顯示條件 |
|---------|---------|------|--------|----------|----------|
| 例句重組題目 | Array | 是 | - | 句子片段陣列 | 左側拖拽區域 |
| 單字選取池 | Array | 是 | - | 詞彙陣列 | 可拖拽單字池 |
| 詞彙配對左側 | Array | 是 | - | 示意圖陣列 | 配對題左側 |
| 詞彙配對右側 | Array | 是 | - | 詞彙陣列 | 配對題右側 |
| 重組完成狀態 | Boolean | 是 | false | true/false | 完成度檢查 |
| 配對完成狀態 | Boolean | 是 | false | true/false | 完成度檢查 |
| 總體完成進度 | Number | 是 | 0 | 0-100% | 進度條顯示 |

#### Web版互動元素

| 元素名稱 | 元素類型 | 操作方式 | 快捷鍵 | 狀態變化 | 備註 |
|---------|---------|----------|--------|----------|------|
| 單字拖拽 | 拖拽元素 | 滑鼠拖拽 | - | 待選→拖拽中 | HTML5 Drag API |
| 配對連線 | 連線元素 | 點擊連接 | 1-5數字鍵 | 未連→已連 | SVG連線動畫 |
| 重組檢查按鈕 | 按鈕 | 點擊/Ctrl+Enter | Ctrl+Enter | 正常→檢查中 | 句子正確性檢驗 |
| 配對檢查按鈕 | 按鈕 | 點擊/Shift+Enter | Shift+Enter | 正常→檢查中 | 配對正確性檢驗 |
| 重置按鈕 | 按鈕 | 點擊/Ctrl+R | Ctrl+R | - | 重新開始 |
| 提示按鈕 | 按鈕 | 點擊/H鍵 | H | 正常→顯示提示 | 學習輔助 |

### Page_Vocab_Level2Plus_Speaking_W - 第2+關：口說練習特別關卡

#### 功能說明 (整合共用規範)
- **頁面目的**: 付費口說訓練，五維度口說評分
- **關卡機制**: 參考 [線性闖關學習系統 - 第2+關](../common/progressive-stage-system.md#第2關口說練習特別關卡-speaking-practice-bonus)
- **付費模式**: 消耗5鑽石進入，不消耗命條
- **評分系統**: 整合 [口說評分系統](../common/speaking-evaluation-specs.md) 五維度評估

#### 付費機制與獎勵
基於 [共同業務規則](../common/business-rules.md) 的道具商店系統：
- **通關條件**: 平均分數≥70分
- **獎勵階梯**:
  - 70-79分：1鑽石 + 10XP (回收部分成本)
  - 80-89分：3鑽石 + 10XP (略有虧損但有進步)
  - 90-100分：5鑽石 + 20XP (獲利且大幅經驗值)

#### 頁面欄位細節

| 欄位名稱 | 資料類型 | 必填 | 預設值 | 驗證規則 | 顯示條件 |
|---------|---------|------|--------|----------|----------|
| 付費確認狀態 | Boolean | 是 | false | true/false | 進入前確認 |
| 鑽石餘額 | Number | 是 | - | >=0 | 右上角顯示 |
| 詞彙例句列表 | Array | 是 | - | 5個例句 | 朗讀練習內容 |
| 當前朗讀詞彙 | String | 是 | - | 詞彙字串 | 大字體顯示 |
| 語音輸入狀態 | Boolean | 是 | false | true/false | 麥克風狀態 |
| 五維即時評分 | Object | 是 | {} | 評分物件 | 發音/流暢度/韻律/完整度/準確度 |
| 平均分數 | Number | 是 | 0 | 0-100 | 整體表現分數 |
| 完成進度 | Number | 是 | 0 | 0-100% | 朗讀進度 |

#### Web版互動元素

| 元素名稱 | 元素類型 | 操作方式 | 快捷鍵 | 狀態變化 | 備註 |
|---------|---------|----------|--------|----------|------|
| 付費確認按鈕 | 按鈕 | 點擊 | - | 正常→確認中 | 5鑽石消費確認 |
| 語音錄製按鈕 | 按鈕 | 點擊/Space | Space | 待錄→錄製中 | Web Audio API |
| 範例播放按鈕 | 按鈕 | 點擊/P鍵 | P | 正常→播放中 | 標準發音示範 |
| 重錄按鈕 | 按鈕 | 點擊/R鍵 | R | - | 重新錄製 |
| 下一詞彙按鈕 | 按鈕 | 點擊/→鍵 | → | 正常→載入中 | 進入下一詞彙 |
| 評分詳情按鈕 | 按鈕 | 點擊/I鍵 | I | 收合→展開 | 詳細評分說明 |

### Page_Vocab_Progress_Dashboard_W - 四關進度儀表板 (Web專用)

#### 功能說明
- **頁面目的**: 提供四關學習進度的綜合分析和可視化
- **進入條件**: 從詞彙學習主頁或結果頁面進入
- **Web專用功能**: 大螢幕多圖表並列顯示

#### 頁面欄位細節

| 欄位名稱 | 資料類型 | 必填 | 預設值 | 驗證規則 | 顯示條件 |
|---------|---------|------|--------|----------|----------|
| 四關完成統計 | Object | 是 | {} | 統計物件 | 卡片式布局 |
| 關卡通過率分布 | Array | 是 | [] | 百分比陣列 | 圓餅圖顯示 |
| 學習時間分析 | Object | 是 | {} | 時間統計 | 長條圖顯示 |
| 口說練習投資報酬率 | Number | 否 | 0 | 可為負數 | 付費關卡分析 |
| 詞彙掌握度熱力圖 | Array | 是 | [] | 矩陣數據 | 熱力圖顯示 |
| 複習排程預覽 | Array | 是 | [] | 日期陣列 | 日曆式顯示 |

## 🌐 Web端技術特點 (整合共用規範)

### 響應式設計
- **桌面優先**: 1200px以上寬度的最佳化四關並列顯示
- **平板適應**: 768px-1199px的關卡卡片式佈局
- **快捷鍵系統**: 完整的鍵盤操作支援
- **無障礙設計**: 符合WCAG 2.1 AA標準

### AI系統整合
基於 [AI算法規格](../common/ai-algorithm-specs.md) 的Web端實現：
- **詞彙展示AI**: 自動生成詞彙學習內容
- **語境應用AI**: 智慧配對和重組題目生成
- **口說評分AI**: 整合五維度口說評分系統
- **間隔複習AI**: 基於遺忘曲線的複習排程算法

### 效能最佳化
- **懶載入**: 四關內容按需載入
- **快取策略**: 詞彙內容本地快取
- **預載入**: 預先載入下一關卡內容
- **CDN加速**: 音頻和圖片資源分發

## ⌨️ Web版快捷鍵一覽

### 通用快捷鍵
- `Space` - 播放/暫停詞彙發音
- `1-4` - 第1-4關快速切換
- `A-D` - 選擇對應選項
- `Enter` - 確認/下一步
- `Esc` - 取消/返回
- `H` - 顯示提示
- `Ctrl+D` - 收藏詞彙

### 關卡專用快捷鍵
- `→/←` - 上一題/下一題
- `Ctrl+R` - 重新開始
- `P` - 播放範例發音 (口說關卡)
- `R` - 重新錄製 (口說關卡)

## 📊 Web版業務邏輯差異

### 四關學習會話管理
- **關卡狀態同步**: 四關進度即時同步
- **付費狀態管理**: 口說練習付費狀態追蹤
- **複習整合**: 四關完成自動加入間隔複習系統
- **跨裝置同步**: 透過帳戶同步四關學習狀態

### 命條系統整合
基於 [共同業務規則 - 命條系統](../common/business-rules.md#🎮-命條系統-life-points-system)：
- **啟動扣除**: 第1、2、3關啟動時各消耗1個命條
- **付費豁免**: 第2+關付費關卡不消耗命條
- **等級差異**: 不同用戶等級的命條上限和恢復速度

## 🧪 Web版測試要點

### 四關流程測試
- [ ] 第1關→第2關順序解鎖正常
- [ ] 第2+關付費機制正常運作
- [ ] 第3關（情境對話）正常解鎖
- [ ] 四關完成後正確加入複習系統

### 付費功能測試
- [ ] 鑽石餘額顯示正確
- [ ] 口說練習付費確認流程
- [ ] 獎勵發放機制正常
- [ ] 不足鑽石時的處理

### 響應式測試
- [ ] 1920x1080 四關並列顯示
- [ ] 1366x768 關卡卡片式佈局
- [ ] 快捷鍵功能完整

## 📝 Web端開發注意事項

### 前端開發
- 使用現代JavaScript框架整合四關流程
- 整合 [口說評分系統](../common/speaking-evaluation-specs.md) API
- 實現 [間隔複習算法](../common/ai-algorithm-specs.md#間隔複習系統-spaced-repetition)
- 響應式設計支援四關並列和堆疊佈局

### 業務邏輯整合
- 嚴格遵循 [線性闖關學習系統](../common/progressive-stage-system.md) 的解鎖機制
- 整合 [共同業務規則](../common/business-rules.md) 的命條和付費系統
- 實現與情境對話系統的詞彙傳遞機制

### 數據同步
- 四關進度的即時保存
- 與Mobile端的學習記錄同步
- 複習系統的跨平台數據一致性

---

**文檔狀態**: 🟢 已完成 (基於共用規範更新)  
**最後更新**: 2025-09-11  
**版本**: v2.0 - 整合四關線性闖關系統  
**相關文檔**: 
- `../common/progressive-stage-system.md` - 線性闖關學習系統規格
- `../common/ai-algorithm-specs.md` - AI算法規格
- `../common/business-rules.md` - 共同業務規則
- `../common/speaking-evaluation-specs.md` - 口說評分系統規格