# 學習地圖功能規格文檔

## 📋 功能概述

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

### 主要功能
- 階段化學習路徑：13階段×20劇本×4關卡的完整學習架構
- 線性闖關機制：必須按 詞彙學習→詞彙熟悉→口說練習特別關卡→情境對話 順序闖關，特別關卡可跳過
- 進度導航系統：地圖直接顯示當前可進行的關卡，無需選擇彈窗
- 關卡狀態管理：🔒鎖定/⏳可進行/🔄進行中/✅已完成 四種狀態
- 星級評價系統：基於各關卡特定標準給予1-3星評價

### 適用場景
- 新用戶學習路徑規劃和引導
- 日常學習內容的選擇和導航
- 學習進度的查看和管理
- 關卡成就的展示和炫耀

### 與其他功能的關聯
- **線性闖關系統**: 依循 [線性闖關學習系統規格](../common/progressive-stage-system.md) 的四關順序
- **詞彙學習系統**: 第1、2關的詞彙學習和熟悉訓練
- **口說評分系統**: 第2+關的口說練習特別關卡評估
- **情境對話系統**: 第3關的綜合對話應用
- **命條系統**: 關卡啟動時的資源消耗管理
- **成就系統**: 關卡完成觸發成就和徽章解鎖

## 📱 涉及的UI畫面

### 主要畫面
1. **UI_Level_Map** - 學習地圖主畫面 (線性闖關版)
2. **UI_Current_Level_Info** - 當前可進行關卡資訊面板
3. **UI_Level_Progress_Detail** - 關卡進度詳情頁面
4. **UI_Stage_Overview** - 階段總覽和劇本選擇
5. **UI_Level_Locked_Modal** - 關卡鎖定提示彈窗

### 輔助畫面  
1. **UI_Cost_Confirm_Popup** - 口說練習特別關卡付費確認彈窗
2. **UI_Insufficient_Resources** - 資源不足提示頁面
3. **UI_Level_Status_Indicator** - 關卡狀態指示器組件
4. **UI_Progress_Path_Visual** - 闖關路徑可視化組件

## 🎯 詳細畫面規格

### UI_Level_Map - 學習地圖主畫面 (線性闖關版)

#### 功能說明
- **畫面目的**: 展示線性闖關學習路徑，清楚標示13階段×20劇本×4關卡的進度狀態
- **進入條件**: 完成用戶註冊和等級評估，或從底部導航進入
- **退出條件**: 直接進入當前可進行的關卡，或切換到其他功能模組
- **核心變化**: 取消關卡選擇彈窗，地圖直接顯示下一個可進行的關卡

#### 畫面欄位細節

| 欄位名稱 | 資料類型 | 必填 | 預設值 | 驗證規則 | 顯示條件 |
|---------|---------|------|--------|----------|----------|
| 當前階段編號 | Number | 是 | 1 | 1-13 | 始終顯示 |
| 當前劇本編號 | Number | 是 | 1 | 1-20+ | 始終顯示 |
| 當前關卡類型 | String | 是 | "詞彙學習" | 關卡枚舉 | 始終顯示 |
| 階段名稱 | String | 是 | - | 5-50字 | 始終顯示 |
| 劇本標題 | String | 是 | - | 3-30字 | 始終顯示 |
| 階段背景圖 | Image URL | 是 | - | 有效圖片格式 | 始終顯示 |
| 階段完成度 | Number | 是 | 0 | 0-100% | 始終顯示 |
| 劇本完成度 | Number | 是 | 0 | 0-100% | 始終顯示 |
| 已完成關卡數 | Number | 是 | 0 | ≥0 | 始終顯示 |
| 總關卡數 | Number | 是 | 80 | ≥80 | 始終顯示 (4關×20劇本) |
| 累積星數 | Number | 是 | 0 | ≥0 | 始終顯示 |
| 連續學習天數 | Number | 是 | 0 | ≥0 | 始終顯示 |
| 用戶命條數量 | Number | 是 | 5 | 0-5 | 始終顯示 |
| 用戶鑽石數量 | Number | 是 | 0 | ≥0 | 始終顯示 |
| 下一關卡資訊 | Object | 是 | - | 關卡物件 | 始終顯示 |
| 四關進度狀態 | Array | 是 | [] | 狀態陣列 | 始終顯示 |

#### 互動元素

| 元素名稱 | 元素類型 | 點擊行為 | 狀態變化 | 備註 |
|---------|---------|----------|----------|------|
| 當前可進行關卡 | 大型卡片按鈕 | 直接進入關卡 | - | 清楚標示關卡類型和要求 |
| 四關進度指示器 | 進度條組件 | 查看劇本四關進度 | - | 🔒鎖定/⏳可進行/🔄進行中/✅已完成 |
| 劇本選擇區域 | 水平滾動列表 | 查看其他劇本進度 | - | 只顯示已解鎖劇本 |
| 階段切換按鈕 | 按鈕組 | 切換到其他階段 | - | 未解鎖階段禁用 |
| 學習統計面板 | 資訊卡片 | 查看詳細學習數據 | - | 展開/收合統計資訊 |
| 時光關卡按鈕 | 特殊按鈕 | 使用時光卷挑戰 | - | 需要時光卷道具 |
| 每日任務指示 | 提示標誌 | 查看今日學習任務 | - | 跳轉到任務系統 |
| 成就通知 | 浮動提示 | 查看新獲得成就 | - | 自動消失或手動關閉 |

#### 使用者操作流程 (線性闖關版)
1. **進度確認**: 進入地圖 → 查看當前階段和劇本 → 確認四關進度狀態
2. **直接闖關**: 點擊當前可進行關卡 → 確認資源需求 → 直接進入關卡
3. **劇本瀏覽**: 查看四關進度指示器 → 了解完成狀況 → 規劃後續學習
4. **階段導航**: 完成劇本後 → 自動解鎖下一劇本 → 或切換到其他階段

#### 異常狀況處理
- **資源不足**: 顯示資源不足提示 → 引導到商店購買 → 或提供免費獲得方式
- **網路中斷**: 顯示離線模式 → 載入快取內容 → 恢復連線時同步進度
- **關卡載入失敗**: 顯示載入錯誤 → 提供重試選項 → 或跳到其他可用關卡

### UI_Current_Level_Info - 當前可進行關卡資訊面板

#### 功能說明
- **畫面目的**: 清楚展示當前可進行關卡的詳細資訊，引導用戶直接進入學習
- **進入條件**: 學習地圖主畫面的核心組件，始終可見
- **顯示邏輯**: 根據四關線性闖關進度，自動顯示下一個可進行的關卡資訊

#### 畫面欄位細節

| 欄位名稱 | 資料類型 | 必填 | 預設值 | 驗證規則 | 顯示條件 |
|---------|---------|------|--------|----------|----------|
| 劇本名稱 | String | 是 | - | 5-100字 | 始終顯示 |
| 劇本描述 | String | 是 | - | 20-300字 | 始終顯示 |
| 劇本預覽圖 | Image URL | 是 | - | 有效圖片格式 | 始終顯示 |
| 難度等級 | Number | 是 | 1 | 1-5星 | 始終顯示 |
| 預估學習時間 | Number | 是 | 10 | 5-60分鐘 | 始終顯示 |
| 核心詞彙數量 | Number | 是 | 5 | 3-15個 | 始終顯示 |
| 關卡完成狀態 | Object | 是 | - | 狀態物件 | 始終顯示 |
| 獲得星數 | Number | 是 | 0 | 0-3星 | 已完成關卡顯示 |
| 關卡獎勵預覽 | Object | 是 | - | 獎勵物件 | 始終顯示 |

#### 互動元素

| 元素名稱 | 元素類型 | 點擊行為 | 狀態變化 | 備註 |
|---------|---------|----------|----------|------|
| 詞彙認識關卡按鈕 | 按鈕 | 進入詞彙介紹和練習 | - | 第一個必須完成的關卡 |
| 詞彙熟悉關卡按鈕 | 按鈕 | 進入詞彙應用練習 | - | 需要先完成詞彙認識 |
| 對話訓練關卡按鈕 | 按鈕 | 進入情境對話練習 | - | 需要先完成前兩個關卡 |
| 限時挑戰按鈕 | 按鈕 | 進入300秒限時模式 | - | 需要額外鑽石消費 |
| 預覽核心詞彙按鈕 | 按鈕 | 查看本劇本重點詞彙 | - | 方便預習準備 |
| 查看劇本背景按鈕 | 按鈕 | 了解劇本情境設定 | - | 增加學習代入感 |
| 關閉彈窗按鈕 | 按鈕 | 關閉選擇彈窗 | 顯示->隱藏 | 返回地圖界面 |

### UI_Level_Locked_Modal - 關卡鎖定提示彈窗

#### 功能說明
- **畫面目的**: 當用戶嘗試進入未解鎖關卡時，說明解鎖條件和提供解決方案
- **進入條件**: 點擊尚未解鎖的關卡節點
- **退出條件**: 了解解鎖條件後關閉，或前往完成前置關卡

#### 畫面欄位細節

| 欄位名稱 | 資料類型 | 必填 | 預設值 | 驗證規則 | 顯示條件 |
|---------|---------|------|--------|----------|----------|
| 鎖定原因 | String | 是 | - | 20-100字 | 始終顯示 |
| 前置關卡名稱 | String | 是 | - | 5-100字 | 始終顯示 |
| 前置關卡進度 | Number | 是 | 0 | 0-100% | 始終顯示 |
| 建議完成時間 | Number | 是 | 30 | 10-180分鐘 | 始終顯示 |
| 解鎖獎勵預覽 | Object | 是 | - | 獎勵物件 | 始終顯示 |

#### 互動元素

| 元素名稱 | 元素類型 | 點擊行為 | 狀態變化 | 備註 |
|---------|---------|----------|----------|------|
| 前往前置關卡按鈕 | 按鈕 | 跳轉到需要完成的關卡 | - | 主要行動按鈕 |
| 查看解鎖條件按鈕 | 按鈕 | 顯示詳細解鎖要求 | - | 提供更多資訊 |
| 了解獎勵按鈕 | 按鈕 | 展示解鎖後的獎勵 | - | 增加動機 |
| 關閉按鈕 | 按鈕 | 關閉提示彈窗 | 顯示->隱藏 | 返回地圖界面 |

## 🔄 完整使用者流程

### 主要流程圖
```
[底部導航/首頁進入]
    ↓
[UI_Level_Map 學習地圖] → [瀏覽當前階段關卡]
    ↓
[點擊關卡節點] → [UI_Level_Selection_Modal 關卡選擇]
    ↓
[選擇關卡類型] → [UI_Cost_Confirm_Popup 成本確認]
    ↓
[確認進入] → [跳轉到對應學習功能]
```

### 分支流程
- **關卡鎖定**: 點擊鎖定關卡 → UI_Level_Locked_Modal → 了解解鎖條件 → 前往前置關卡
- **資源不足**: 確認關卡消費 → UI_Insufficient_Resources → 前往商店購買 → 或等待資源恢復
- **階段切換**: 使用導航按鈕 → 快速跳轉到其他階段 → 查看不同階段內容
- **進度查看**: 點擊統計按鈕 → 跳轉個人中心 → 查看詳細學習分析

### 錯誤流程
- **網路載入失敗**: 顯示載入錯誤 → 提供重試選項 → 或啟用離線模式
- **關卡數據錯誤**: 顯示數據異常 → 自動修復或重新載入 → 記錄錯誤日誌

## 📊 商業邏輯規則

### 關卡解鎖機制
- **順序闖關**: 必須按照 詞彙認識 → 詞彙熟悉 → 對話訓練 的順序完成
- **階段解鎖**: 完成當前階段80%以上關卡才能解鎖下一階段
- **星級獎勵**: 詞彙認識和詞彙熟悉關卡通關自動給予3星，對話訓練根據表現給1-3星

### 學習進度算法
- **完成度計算**: (已完成關卡數 / 當前可用關卡總數) × 100%
- **學習天數判定**: 當日完成至少一個關卡即計為學習一天
- **連續獎勵**: 7天連續、14天連續、30天連續分別給予不同獎勵

### 資源消耗規則
> 詳細命條系統規格請參閱 → **[共同業務規則 - 命條系統](../common/business-rules.md#🎮-命條系統-life-points-system)**

- **詞彙學習**: 啟動關卡消耗1個命條
- **詞彙熟悉**: 啟動關卡消耗1個命條
- **口說練習特別關卡**: 付費進入(5鑽石)，不扣命條，可跳過
- **情境對話**: 啟動關卡消耗1個命條  
- **限時挑戰**: 首次免費，後續50鑽石/次
- **命條不足**: 無法開始新關卡，需要購買或等待恢復

## 🧪 測試要點

### 功能測試
- [ ] 關卡解鎖邏輯正確性驗證
- [ ] 階段切換功能正常運作
- [ ] 進度計算和顯示準確
- [ ] 星級評價系統正確
- [ ] 資源消耗機制正常
- [ ] 連續學習天數統計準確
- [ ] 每日推薦算法有效性

### 介面測試
- [ ] 地圖六角形關卡節點顯示正確
- [ ] 關卡狀態顏色區分清楚
- [ ] 彈窗動畫效果流暢
- [ ] 進度條和統計圖表準確
- [ ] 響應式佈局適配良好

### 整合測試
- [ ] 與情境對話系統跳轉正常
- [ ] 與詞彙學習系統整合無誤
- [ ] 與命條系統扣除邏輯一致
- [ ] 與成就系統觸發機制正確
- [ ] 與訂閱系統權限檢查有效

## 📝 開發注意事項

### 前端開發
- 地圖需要支援平滑滾動和縮放功能
- 六角形關卡節點需要CSS動畫效果
- 進度條需要平滑的填充動畫
- 彈窗需要優雅的彈出和關閉過渡

### 後端開發
- 關卡解鎖邏輯需要嚴格的權限檢查
- 學習進度數據需要即時同步
- 連續學習天數需要準確的時區處理
- 關卡推薦算法需要個人化考量

### 整合注意事項
- 關卡跳轉需要保持用戶狀態
- 進度數據需要跨平台同步
- 離線模式需要支援基本瀏覽功能
- 資源檢查需要防止競態條件

## 📚 參考資源

- **UI截圖**: 
  - `docs/02_design/views/UI_Level_Map.png`
  - `docs/02_design/views/UI_Level_Selection_Modal.png`
  - `docs/02_design/views/UI_Level_Locked_Modal.png`
- **User Flow**: `docs/04_technical/user-flow-specification.md` - 學習地圖導航章節
- **API文檔**: `docs/04_technical/api/learning-content.md`
- **商業規則**: `docs/02_design/business-logic-rules.md` - 關卡結構系統章節
- **設計規範**: `docs/02_design/ui-ux-guidelines.md`

## 📅 版本歷史

| 版本 | 日期 | 修改內容 | 修改者 |
|-----|------|----------|--------|
| v1.0 | 2025-09-08 | 初始版本建立，基於13階段學習架構設計 | Claude AI |

---

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