# 學習地圖功能規格文檔 (Web版)

## 📋 功能概述

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

### 整合共用規範
> 本規格基於以下共用模組，請參閱對應規格文件：
> - **[線性闖關學習系統](../common/progressive-stage-system.md)** - 13階段×20劇本×4關卡架構
> - **[共同業務規則](../common/business-rules.md)** - 關卡解鎖和命條系統
> - **[AI算法規格](../common/ai-algorithm-specs.md)** - 學習進度追蹤

### 主要功能 (基於線性闖關系統)
- **13階段學習路徑**: 完整的英語學習階段劃分
- **20+劇本內容**: 每階段包含豐富的情境劇本
- **四關卡系統**: 詞彙學習→詞彙熟悉→口說練習→情境對話
- **線性解鎖機制**: 嚴格的順序闖關，確保學習品質
- **進度視覺化**: 清晰的學習進度和成就展示
- **星級系統**: 關卡完成品質的星級評估

### Web端特色功能
- **全景地圖視圖**: 大螢幕完整顯示學習路徑全貌
- **多階段並排**: 可同時查看多個階段的劇本分布
- **詳細統計面板**: 各階段學習數據的深度分析
- **快速導航**: 鍵盤快捷鍵和搜尋功能快速定位
- **學習規劃**: 桌面環境的學習計劃制定和追蹤
- **全螢幕模式**: 沉浸式學習地圖瀏覽體驗

### 適用場景
- 桌面環境的學習規劃和進度檢視
- 需要大範圍學習路徑overview的情況
- 詳細學習數據分析和統計檢視
- 多螢幕環境下的學習管理

### 與其他功能的關聯
- **四關卡系統**: 直接進入詞彙學習、詞彙熟悉、口說練習、情境對話
- **命條系統**: 整合 [共同業務規則](../common/business-rules.md#🎮-命條系統-life-points-system) 的關卡啟動限制
- **成就系統**: 顯示學習成就和里程碑
- **複習系統**: 整合間隔複習的詞彙管理

## 💻 涉及的Web頁面 (線性闖關架構)

### 主要頁面
1. **Page_Learning_Map_Overview_W** - 學習地圖總覽頁面 (Web版)
2. **Page_Stage_Detail_W** - 階段詳情頁面 (Web版)
3. **Page_Script_Preview_W** - 劇本預覽頁面 (Web版)
4. **Page_Level_Progress_W** - 關卡進度頁面 (Web版)

### Web專用頁面
1. **Page_Learning_Statistics_W** - 學習統計儀表板 (Web專用)
2. **Page_Learning_Planner_W** - 學習規劃頁面 (Web專用)
3. **Page_Achievement_Gallery_W** - 成就展示廊 (Web專用)

### 輔助頁面
1. **Modal_Stage_Unlock_W** - 階段解鎖慶祝模態視窗
2. **Panel_Quick_Stats_W** - 快速統計面板
3. **Modal_Level_Preview_W** - 關卡預覽模態視窗

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

### Page_Learning_Map_Overview_W - 學習地圖總覽頁面

#### 功能說明 (整合共用規範)
- **頁面目的**: 展示完整的13階段×20劇本×4關卡學習架構
- **地圖架構**: 參考 [線性闖關學習系統](../common/progressive-stage-system.md#📚-闖關架構)
- **解鎖機制**: 參考 [線性闖關學習系統 - 關卡解鎖](../common/progressive-stage-system.md#🔒-關卡解鎖機制)

#### 學習架構展示
基於共用規範的三層架構：
```
13個階段 (Stage)
├── 每階段 20+ 劇本 (Script)  
│   ├── 第1關：詞彙學習 (Vocabulary Learning)
│   ├── 第2關：詞彙熟悉 (Vocabulary Mastery)
│   ├── 第2+關：口說練習特別關卡 (Speaking Practice Bonus)
│   └── 第3關：情境對話 (Situational Dialogue)
```

#### Web版佈局特點
- **階段總覽區**: 頂部13個階段的水平展示
- **劇本網格區**: 中央20×4的關卡網格展示
- **進度統計區**: 右側進度、成就、命條狀態
- **快速操作區**: 底部搜尋、篩選、導航功能

#### 頁面欄位細節

| 欄位名稱 | 資料類型 | 必填 | 預設值 | 驗證規則 | 顯示條件 |
|---------|---------|------|--------|----------|----------|
| 當前階段 | Number | 是 | 1 | 1-13 | 高亮顯示當前階段 |
| 階段解鎖狀態 | Array | 是 | [] | 解鎖陣列 | 13個階段狀態 |
| 劇本完成進度 | Array | 是 | [] | 進度陣列 | 每劇本4關完成狀態 |
| 總學習時間 | Number | 是 | 0 | >=0分鐘 | 統計面板顯示 |
| 總獲得星數 | Number | 是 | 0 | >=0 | 成就統計 |
| 命條餘額 | Number | 是 | 5 | >=0 | 右上角顯示 |
| 連續學習天數 | Number | 是 | 0 | >=0 | 成就指標 |
| 下次複習詞彙數 | Number | 是 | 0 | >=0 | 複習提醒 |
| 搜尋關鍵詞 | String | 否 | "" | 0-50字 | 搜尋框輸入 |
| 篩選條件 | Object | 否 | {} | 篩選物件 | 篩選面板設定 |

#### Web版互動元素

| 元素名稱 | 元素類型 | 操作方式 | 快捷鍵 | 狀態變化 | 備註 |
|---------|---------|----------|--------|----------|------|
| 階段選擇器 | 水平滑桿 | 點擊/方向鍵 | ←→ | 階段1-13切換 | 滑動動畫效果 |
| 劇本卡片 | 卡片元素 | 點擊/數字鍵 | 1-20 | 未選→已選 | 懸停顯示詳情 |
| 關卡圖示 | 圖示按鈕 | 點擊/L鍵 | L | 鎖定→可用→完成 | 四關狀態圖示 |
| 搜尋框 | 輸入框 | 點擊/Ctrl+F | Ctrl+F | 空白→輸入中 | 即時搜尋 |
| 篩選按鈕 | 下拉選單 | 點擊/F鍵 | F | 收合→展開 | 多條件篩選 |
| 全螢幕按鈕 | 按鈕 | 點擊/F11 | F11 | 正常↔全螢幕 | 沉浸式地圖 |
| 統計面板 | 摺疊面板 | 點擊/S鍵 | S | 收合↔展開 | 學習統計 |
| 快速跳轉 | 按鈕 | 點擊/G鍵 | G | - | 跳轉到指定關卡 |
| 學習規劃 | 按鈕 | 點擊/P鍵 | P | - | 開啟學習規劃 |

#### 關卡狀態視覺化
基於 [線性闖關學習系統 - 關卡狀態](../common/progressive-stage-system.md#關卡狀態管理)：
- **🔒 鎖定狀態**: 灰色圖示，顯示解鎖要求
- **⏳ 可進行狀態**: 彩色圖示，可點擊進入
- **🔄 進行中狀態**: 動畫圖示，顯示進度
- **✅ 已完成狀態**: 綠色圖示+星級顯示

### Page_Stage_Detail_W - 階段詳情頁面

#### 功能說明 (整合進度追蹤)
- **頁面目的**: 詳細展示單一階段的20+劇本內容
- **進度追蹤**: 整合 [AI算法規格 - 學習進度追蹤](../common/ai-algorithm-specs.md#🎯-學習進度追蹤)
- **成就系統**: 顯示階段相關成就和里程碑

#### 階段內容結構
- **階段概述**: 學習目標、主要場景、詞彙範圍
- **劇本網格**: 20×4的關卡詳細展示
- **統計分析**: 該階段的學習表現分析
- **學習建議**: 基於進度的個人化建議

#### 頁面欄位細節

| 欄位名稱 | 資料類型 | 必填 | 預設值 | 驗證規則 | 顯示條件 |
|---------|---------|------|--------|----------|----------|
| 階段編號 | Number | 是 | - | 1-13 | 頁面標題 |
| 階段名稱 | String | 是 | - | 5-50字 | 主標題顯示 |
| 階段描述 | String | 是 | - | 50-200字 | 概述區域 |
| 學習目標 | Array | 是 | [] | 目標陣列 | 列表形式 |
| 劇本列表 | Array | 是 | [] | 劇本陣列 | 網格佈局 |
| 完成劇本數 | Number | 是 | 0 | 0-20+ | 進度統計 |
| 階段完成度 | Number | 是 | 0 | 0-100% | 進度條 |
| 平均星級 | Number | 是 | 0 | 0-3.0 | 品質指標 |
| 詞彙掌握數 | Number | 是 | 0 | >=0 | 學習成果 |
| 推薦學習時間 | Number | 是 | - | >0小時 | 建議時長 |

### Page_Learning_Statistics_W - 學習統計儀表板 (Web專用)

#### 功能說明
- **頁面目的**: 提供詳盡的學習數據分析和可視化
- **數據範圍**: 跨階段、跨時間的綜合統計
- **Web專用優勢**: 大螢幕多圖表並列顯示

#### 統計維度
基於 [AI算法規格 - 數據追蹤](../common/ai-algorithm-specs.md#📊-數據追蹤需求)：
- **關卡表現數據**: 完成時間、嘗試次數、星級分布
- **學習行為分析**: 學習模式、停留時間、跳離率
- **進步軌跡**: 長期學習趨勢和能力提升
- **比較分析**: 與其他學習者的表現對比

#### 頁面欄位細節

| 欄位名稱 | 資料類型 | 必填 | 預設值 | 驗證規則 | 顯示條件 |
|---------|---------|------|--------|----------|----------|
| 統計時間範圍 | DateRange | 是 | 最近30天 | 有效日期 | 頁面頂部選擇器 |
| 學習時間統計 | Object | 是 | {} | 時間統計 | 圓餅圖顯示 |
| 關卡完成分布 | Array | 是 | [] | 完成陣列 | 長條圖顯示 |
| 星級獲得趨勢 | Array | 是 | [] | 時間序列 | 折線圖顯示 |
| 詞彙學習進度 | Object | 是 | {} | 進度統計 | 進度環顯示 |
| 四關表現對比 | Object | 是 | {} | 關卡統計 | 雷達圖顯示 |
| 學習建議列表 | Array | 是 | [] | 建議陣列 | 智能建議卡片 |
| 成就解鎖狀態 | Array | 是 | [] | 成就陣列 | 成就牆顯示 |

### Page_Learning_Planner_W - 學習規劃頁面 (Web專用)

#### 功能說明
- **頁面目的**: 制定和管理個人化學習計劃
- **規劃範圍**: 日程安排、目標設定、進度追蹤
- **智能建議**: 基於學習表現的個人化建議

#### 規劃功能
- **學習目標設定**: 階段目標、時間目標、星級目標
- **日程規劃**: 每日學習安排、複習排程
- **進度監控**: 實時進度對比和調整建議
- **提醒系統**: 學習提醒、複習提醒、目標檢查

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

### 響應式設計
- **桌面優先**: 1200px以上寬度的完整地圖展示
- **階段並排**: 大螢幕可同時顯示多個階段
- **關卡網格**: 清晰的4×20關卡網格佈局
- **統計面板**: 詳細的數據視覺化展示

### 視覺化系統
- **進度動畫**: 關卡解鎖和完成的動畫效果
- **狀態圖示**: 清晰的關卡狀態視覺表示
- **星級展示**: 直觀的學習品質指標
- **成就系統**: 學習里程碑的視覺化慶祝

### 效能最佳化
- **虛擬捲動**: 大量關卡數據的效能優化
- **懶載入**: 階段內容按需載入
- **快取策略**: 學習進度本地快取
- **預載入**: 預先載入即將解鎖的內容

## ⌨️ Web版快捷鍵一覽

### 導航快捷鍵
- `←→` - 切換階段
- `1-20` - 直接跳轉劇本
- `L` - 查看關卡詳情
- `G` - 快速跳轉
- `Home/End` - 跳到第一/最後階段

### 功能快捷鍵
- `Ctrl+F` - 開啟搜尋
- `F` - 顯示篩選選項
- `S` - 切換統計面板
- `P` - 開啟學習規劃
- `F11` - 全螢幕模式
- `Esc` - 返回總覽

### 學習相關快捷鍵
- `Enter` - 進入選中的關卡
- `Space` - 展開/收合劇本詳情
- `Ctrl+R` - 刷新進度數據
- `I` - 查看學習統計

## 📊 Web版業務邏輯差異

### 學習地圖管理
基於 [線性闖關學習系統](../common/progressive-stage-system.md) 的Web端實現：
- **全景視圖**: 可同時查看多個階段的學習狀態
- **詳細統計**: 比Mobile端更豐富的數據分析
- **批量操作**: 可同時管理多個學習計劃
- **深度分析**: 提供學習行為的詳細洞察

### 進度同步機制
- **即時同步**: 學習進度跨設備即時同步
- **離線支援**: 離線查看已快取的進度數據
- **衝突解決**: 處理多設備同時學習的衝突
- **備份恢復**: 學習進度的自動備份機制

### 關卡解鎖邏輯
基於 [共同業務規則 - 命條系統](../common/business-rules.md#🎮-命條系統-life-points-system)：
- **解鎖條件**: 嚴格的線性解鎖機制
- **命條檢查**: 進入關卡前檢查命條餘額
- **特別關卡**: 第2+關的跳過機制
- **階段解鎖**: 完成前一階段所有劇本才解鎖下一階段

## 🧪 Web版測試要點

### 地圖顯示測試
- [ ] 13階段×20劇本×4關卡正確顯示
- [ ] 關卡狀態圖示準確反映實際狀態
- [ ] 解鎖邏輯符合線性闖關規則
- [ ] 進度統計數據準確無誤

### 響應式佈局測試
- [ ] 1920x1080 完整地圖展示
- [ ] 1366x768 適當簡化佈局
- [ ] 1024x768 關卡網格正常顯示
- [ ] 快捷鍵功能完整可用

### 效能測試
- [ ] 大量關卡數據載入<3秒
- [ ] 階段切換動畫流暢
- [ ] 統計圖表渲染順暢
- [ ] 長時間使用無記憶體洩漏

### 數據同步測試
- [ ] 跨設備進度同步正常
- [ ] 離線數據快取有效
- [ ] 進度衝突正確解決
- [ ] 備份恢復機制可靠

## 📝 Web端開發注意事項

### 前端開發
- 使用現代JavaScript框架處理複雜的地圖狀態
- 實現高效的虛擬捲動和懶載入
- 整合多種圖表庫進行數據視覺化
- 響應式設計支援多種螢幕尺寸

### 業務邏輯整合
- 嚴格遵循 [線性闖關學習系統](../common/progressive-stage-system.md) 的解鎖機制
- 整合 [共同業務規則](../common/business-rules.md) 的命條系統
- 實現與其他功能模組的無縫整合
- 確保學習進度的一致性和準確性

### 用戶體驗優化
- 地圖載入和切換的流暢動畫
- 清晰的視覺層次和資訊組織
- 直觀的關卡狀態表示
- 豐富的互動反饋和提示

### 資料管理
- 高效的學習進度數據結構
- 即時的進度同步機制
- 可靠的資料備份和恢復
- 詳細的學習分析和統計

---

**文檔狀態**: 🟢 已完成 (基於共用規範更新)  
**最後更新**: 2025-09-11  
**版本**: v2.0 - 整合線性闖關學習地圖系統  
**相關文檔**: 
- `../common/progressive-stage-system.md` - 線性闖關學習系統規格
- `../common/business-rules.md` - 共同業務規則  
- `../common/ai-algorithm-specs.md` - AI算法規格
- `../mobile/03_learning-map-mobile.md` - 對應的Mobile版規格