# 學習地圖功能規格文檔

## 📋 功能概述

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

### 主要功能
- 階段化學習路徑：13階段×20劇本×3關卡的完整學習架構
- 順序解鎖機制：必須按順序完成前置關卡才能解鎖後續內容
- 關卡選擇系統：支援詞彙認識、詞彙熟悉、對話訓練三種關卡類型
- 進度可視化：清楚顯示當前學習進度和成就狀態
- 星級評價系統：基於三維度表現給予1-3星評價

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

### 與其他功能的關聯
- **情境對話系統**: 地圖關卡跳轉到具體對話場景
- **詞彙學習系統**: 地圖關卡跳轉到詞彙練習模組
- **命條系統**: 關卡挑戰前檢查命條資源狀態
- **成就系統**: 關卡完成觸發成就和徽章解鎖
- **訂閱系統**: VIP用戶可解鎖專屬關卡內容

## 📱 涉及的UI畫面

### 主要畫面
1. **UI_Level_Map** - 學習地圖主畫面
2. **UI_Level_Selection_Modal** - 關卡選擇彈窗
3. **UI_Level_Selection_Modal_A** - 基礎關卡選擇界面
4. **UI_Level_Selection_Modal_B** - 進階關卡選擇界面
5. **UI_Level_Locked_Modal** - 關卡鎖定提示彈窗

### 輔助畫面  
1. **UI_Cost_Confirm_Popup** - 關卡成本確認彈窗
2. **UI_Insufficient_Resources** - 資源不足提示頁面
3. **UI_Task_Display** - 任務進度顯示組件

## 🎯 詳細畫面規格

### UI_Level_Map - 學習地圖主畫面

#### 功能說明
- **畫面目的**: 為用戶提供完整的學習路徑導航，清楚展示13階段學習進度和關卡狀態
- **進入條件**: 完成用戶註冊和等級評估，或從底部導航進入
- **退出條件**: 選擇具體關卡進入學習，或切換到其他功能模組

#### 畫面欄位細節

| 欄位名稱 | 資料類型 | 必填 | 預設值 | 驗證規則 | 顯示條件 |
|---------|---------|------|--------|----------|----------|
| 當前階段編號 | Number | 是 | 1 | 1-13 | 始終顯示 |
| 階段名稱 | String | 是 | - | 5-50字 | 始終顯示 |
| 階段背景圖 | Image URL | 是 | - | 有效圖片格式 | 始終顯示 |
| 階段完成度 | Number | 是 | 0 | 0-100% | 始終顯示 |
| 可用劇本數量 | Number | 是 | 0 | 0-20+ | 始終顯示 |
| 已完成關卡數 | Number | 是 | 0 | ≥0 | 始終顯示 |
| 總關卡數 | Number | 是 | 60 | ≥60 | 始終顯示 |
| 累積星數 | Number | 是 | 0 | ≥0 | 始終顯示 |
| 連續學習天數 | Number | 是 | 0 | ≥0 | 始終顯示 |
| 用戶命條數量 | Number | 是 | 5 | 0-5 | 始終顯示 |
| 用戶鑽石數量 | Number | 是 | 0 | ≥0 | 始終顯示 |
| 今日推薦關卡 | Object | 否 | null | 關卡物件 | 有推薦時顯示 |
| 特殊活動關卡 | Array | 否 | [] | 活動陣列 | 有活動時顯示 |

#### 互動元素

| 元素名稱 | 元素類型 | 點擊行為 | 狀態變化 | 備註 |
|---------|---------|----------|----------|------|
| 關卡節點 | 六角形按鈕 | 開啟關卡選擇彈窗 | 正常->選中 | 不同狀態有不同顏色 |
| 上一階段按鈕 | 按鈕 | 切換到上一學習階段 | - | 第1階段時禁用 |
| 下一階段按鈕 | 按鈕 | 切換到下一學習階段 | - | 未解鎖時禁用 |
| 階段選擇下拉 | 下拉選單 | 快速跳轉到指定階段 | - | 只顯示已解鎖階段 |
| 進度總覽按鈕 | 按鈕 | 查看整體學習統計 | - | 跳轉到個人中心 |
| 每日任務按鈕 | 按鈕 | 查看今日學習任務 | - | 跳轉到任務系統 |
| 好友排行按鈕 | 按鈕 | 查看好友學習排名 | - | 跳轉到排行榜 |
| 設定按鈕 | 按鈕 | 開啟學習設定選項 | - | 個人化學習參數 |

#### 使用者操作流程
1. **地圖瀏覽**: 進入地圖 → 查看當前階段 → 瀏覽可用關卡 → 查看學習進度
2. **關卡選擇**: 點擊關卡節點 → 確認關卡類型 → 檢查資源需求 → 確認進入
3. **階段切換**: 使用階段按鈕 → 或下拉選單 → 快速跳轉到目標階段 → 查看新階段內容
4. **進度查看**: 檢查完成度 → 查看星級評價 → 確認下一個目標 → 規劃學習計劃

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

### UI_Level_Selection_Modal - 關卡選擇彈窗

#### 功能說明
- **畫面目的**: 當用戶點擊地圖關卡時，顯示該關卡的詳細資訊和不同類型的學習選項
- **進入條件**: 從學習地圖點擊任意關卡節點
- **退出條件**: 選擇具體關卡類型進入學習，或取消關閉彈窗

#### 畫面欄位細節

| 欄位名稱 | 資料類型 | 必填 | 預設值 | 驗證規則 | 顯示條件 |
|---------|---------|------|--------|----------|----------|
| 劇本名稱 | 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天連續分別給予不同獎勵

### 資源消耗規則
- **詞彙關卡**: 免費進入，答錯扣命條
- **對話訓練**: 免費進入，失敗扣命條
- **限時挑戰**: 首次免費，後續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