# 情境對話功能規格文檔

## 📋 功能概述

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

### 主要功能
- 沉浸式情境對話練習，支援多場景劇本
- 任務導向對話訓練，完成指定溝通目標
- 限時對話挑戰，提升反應速度和流暢度
- AI即時分析回饋，提供個人化學習建議
- 三維度評分系統，全面評估學習成效
- 對話訂正功能，精準糾正語法和表達問題

### 適用場景
- 日常生活情境對話練習（餐廳、購物、工作場合）
- 商務溝通技能訓練（會議、談判、報告）
- 文化交流場景學習（旅遊、社交、學術交流）
- 緊急或特殊場景應對（報警、求助、投訴處理）

### 與其他功能的關聯
- **詞彙學習系統**: 整合指定詞彙到對話情境中
- **學習地圖系統**: 提供情境對話的關卡和進度管理
- **道具商店系統**: 回覆提示道具、加時道具的商業整合
- **命條系統**: 對話失敗消耗命條的生命管理機制
- **排行榜系統**: 限時挑戰成績和社交競爭功能

## 📱 涉及的UI畫面

### 主要畫面
1. **UI_Dialogue_Main** - 情境對話主界面
2. **UI_Dialogue_Analysis** - AI對話分析頁面  
3. **UI_Character_Details** - 角色詳情與背景介紹
4. **UI_Keywords_Details** - 情境關鍵詞預習頁面
5. **UI_Reply_Input** - 進階回覆輸入系統
6. **UI_Reply_Assistance** - 回覆卡關輔助面板

### 輔助畫面  
1. **UI_Cost_Confirm_Popup** - 對話成本確認彈窗
2. **UI_TimeWarp_Cards** - 時光卷道具使用介面
3. **UI_Challenge_Exit_Confirm** - 挑戰退出確認對話框
4. **UI_Task_Display** - 任務完成狀態顯示

## 🎯 詳細畫面規格

### UI_Dialogue_Main - 情境對話主界面

#### 功能說明
- **畫面目的**: 提供沉浸式的情境對話體驗，支援多模態交互和即時反饋
- **進入條件**: 從學習地圖選擇關卡，或通過任務系統進入
- **退出條件**: 完成對話任務、主動退出、或命條歸零失敗

#### 畫面欄位細節

| 欄位名稱 | 資料類型 | 必填 | 預設值 | 驗證規則 | 顯示條件 |
|---------|---------|------|--------|----------|----------|
| 場景背景圖片 | Image URL | 否 | 預設場景圖 | 有效圖片格式 | 始終顯示 |
| 角色頭像 | Image URL | 是 | - | 有效圖片格式 | 始終顯示 |
| 角色對話內容 | String | 是 | - | 1-200字 | 對話進行中 |
| 用戶回覆輸入框 | String | 是 | "請輸入你的回覆..." | 1-500字 | 等待用戶回覆 |
| 劇情任務顯示區 | Object | 是 | - | 任務物件格式 | 有活躍任務時 |
| 指定詞彙顯示區 | Array | 否 | [] | 詞彙陣列 | 有指定詞彙時 |
| 300秒倒數計時器 | Number | 否 | 300 | 0-300秒 | 限時挑戰模式 |
| 命條顯示 | Number | 是 | 用戶當前命條 | 0-5 | 始終顯示 |
| 鑽石數量顯示 | Number | 是 | 用戶當前鑽石 | ≥0 | 始終顯示 |

#### 互動元素

| 元素名稱 | 元素類型 | 點擊行為 | 狀態變化 | 備註 |
|---------|---------|----------|----------|------|
| 發送回覆按鈕 | 按鈕 | 提交用戶回覆，觸發AI分析 | 禁用->啟用 | 輸入內容後可用 |
| 語音輸入按鈕 | 按鈕 | 開啟語音識別輸入 | 正常->錄音中 | 長按錄音，鬆開結束 |
| 回覆輔助按鈕 | 按鈕 | 開啟回覆提示面板 | 正常->彈出面板 | 消耗30鑽石 |
| 角色詳情按鈕 | 按鈕 | 跳轉到角色詳情頁 | - | 提供角色背景資訊 |
| 關鍵詞按鈕 | 按鈕 | 跳轉到關鍵詞詳情頁 | - | 預習場景相關詞彙 |
| 任務提示按鈕 | 按鈕 | 顯示任務完成範例 | - | 免費功能，任務完成後隱藏 |
| 詞彙使用按鈕 | 按鈕 | 展示指定詞彙用法 | - | 免費功能 |
| 中翻英按鈕 | 按鈕 | 將中文翻譯為英文 | - | 免費功能 |
| 退出挑戰按鈕 | 按鈕 | 彈出退出確認對話框 | - | 需要二次確認 |

#### 使用者操作流程
1. **進入對話**: 選擇場景 → 確認消耗資源 → 載入對話環境 → 查看角色開場白
2. **對話互動**: 閱讀角色對話 → 思考回覆內容 → 輸入回覆(文字/語音) → 確認發送
3. **AI分析**: 系統分析回覆 → 即時語法檢查 → 任務完成度評估 → 詞彙使用確認
4. **即時反饋**: 顯示語法正確性 → 任務狀態更新 → 詞彙使用動畫 → 繼續對話或進入下一輪
5. **完成結算**: 對話結束 → 三維度評分 → 獎勵發放 → 跳轉結果頁面

#### 異常狀況處理
- **網路中斷**: 顯示重新連接提示 → 嘗試恢復對話狀態 → 保存當前進度
- **輸入超時**: 限時模式下顯示時間警告 → 自動提交空回覆 → 扣除命條
- **命條歸零**: 顯示失敗畫面 → 提供購買命條選項 → 或返回主畫面
- **語音識別失敗**: 顯示錯誤提示 → 提供重新錄音選項 → 或切換文字輸入
- **鑽石不足**: 回覆輔助功能時顯示不足提示 → 引導到商店購買 → 或提供免費替代方案

#### 資料需求

##### 頁面載入時需要的資料
```json
{
  "api_endpoint": "/api/dialogue/session/start",
  "method": "POST",
  "parameters": {
    "scenario_id": "string",
    "user_id": "string", 
    "difficulty_level": "beginner|intermediate|advanced"
  },
  "response_format": {
    "session_id": "string",
    "scenario_info": {
      "background_image": "url",
      "character": {
        "name": "string",
        "avatar": "url", 
        "personality": "string"
      },
      "keywords": ["string"]
    },
    "tasks": [
      {
        "id": "string",
        "description": "string",
        "status": "pending|completed"
      }
    ],
    "user_resources": {
      "life_points": "number",
      "diamonds": "number"
    }
  }
}
```

##### 用戶操作觸發的API呼叫
```json
{
  "action": "發送回覆",
  "api_endpoint": "/api/dialogue/reply",
  "method": "POST",
  "request_body": {
    "session_id": "string",
    "reply_text": "string",
    "reply_type": "text|voice",
    "timestamp": "datetime"
  }
},
{
  "action": "請求回覆輔助",
  "api_endpoint": "/api/dialogue/assistance",
  "method": "POST", 
  "request_body": {
    "session_id": "string",
    "context": "string",
    "assistance_type": "intention_analysis|thinking_guide|reply_examples"
  }
}
```

#### 視覺設計要求
- **色彩**: 使用主品牌色（青綠色#00E5CC）作為重點強調色，對話氣泡區分用戶和角色
- **字體**: 中文使用PingFang TC，英文使用Inter，對話內容採用16px基準字體大小
- **間距**: 對話氣泡間距24px，輸入區域與對話區域間距40px
- **動畫**: 
  - 對話氣泡出現採用滑入動畫（0.3s ease-out）
  - 詞彙使用成功時觸發慶祝動畫（1.2x放大+發光效果）
  - 任務完成時顯示成就彈窗動畫（彈性彈出+旋轉效果）
- **響應式**: 支援手機豎屏（375px-414px）和平板橫屏（768px+）佈局

#### 技術限制與考量
- **效能要求**: 頁面載入時間<2秒，API回應時間<1秒，語音識別回應<3秒
- **瀏覽器相容**: 支援iOS Safari 14+、Android Chrome 90+、桌面版Chrome/Firefox最新版
- **網路狀況**: 低網路環境下優先載入文字內容，音頻採用延遲載入
- **無障礙**: 支援螢幕閱讀器，提供鍵盤導航，語音輸入按鈕提供視覺和觸覺反饋

### UI_Reply_Assistance - 回覆卡關輔助面板

#### 功能說明
- **畫面目的**: 當用戶在對話中遇到困難時，提供三層式輔助內容，幫助用戶理解情境和組織回覆
- **進入條件**: 用戶點擊"回覆輔助"按鈕，且鑽石數量≥30
- **退出條件**: 用戶選擇使用建議或主動關閉面板

#### 畫面欄位細節

| 欄位名稱 | 資料類型 | 必填 | 預設值 | 驗證規則 | 顯示條件 |
|---------|---------|------|--------|----------|----------|
| 對方意圖分析 | String | 是 | - | 50-200字 | 始終顯示 |
| 回應思緒引導 | String | 是 | - | 50-200字 | 始終顯示 |
| 回覆範例內容 | String | 是 | - | 20-100字 | 始終顯示 |
| 消耗鑽石提示 | Number | 是 | 30 | 固定值30 | 始終顯示 |
| 關閉按鈕 | Button | 是 | - | - | 始終顯示 |
| 使用建議按鈕 | Button | 是 | - | - | 始終顯示 |

#### 互動元素

| 元素名稱 | 元素類型 | 點擊行為 | 狀態變化 | 備註 |
|---------|---------|----------|----------|------|
| 意圖分析展開按鈕 | 按鈕 | 展開/收合詳細分析 | 收合->展開 | 提供更深入的意圖解釋 |
| 思緒引導展開按鈕 | 按鈕 | 展開/收合引導步驟 | 收合->展開 | 分步驟的思考指導 |
| 範例回覆採用按鈕 | 按鈕 | 將範例填入回覆框 | 正常->已採用 | 用戶可進一步修改 |
| 關閉面板按鈕 | 按鈕 | 關閉輔助面板 | 顯示->隱藏 | 不消耗鑽石 |

### UI_Challenge_Exit_Confirm - 挑戰退出確認對話框

#### 功能說明
- **畫面目的**: 在用戶嘗試退出限時挑戰時進行二次確認，避免意外操作
- **進入條件**: 用戶在進行中的挑戰中點擊退出按鈕
- **退出條件**: 用戶確認退出或取消操作

#### 畫面欄位細節

| 欄位名稱 | 資料類型 | 必填 | 預設值 | 驗證規則 | 顯示條件 |
|---------|---------|------|--------|----------|----------|
| 警告標題 | String | 是 | "確認退出挑戰？" | - | 始終顯示 |
| 後果說明 | String | 是 | "退出將失去當前進度並消耗1個命條" | - | 始終顯示 |
| 剩餘時間 | Number | 是 | 當前剩餘秒數 | 0-300 | 限時模式顯示 |
| 確認退出按鈕 | Button | 是 | - | - | 始終顯示 |
| 取消按鈕 | Button | 是 | - | - | 始終顯示 |

## 🔄 完整使用者流程

### 主要流程圖
```
[學習地圖選擇關卡] 
    ↓
[UI_Cost_Confirm_Popup 確認消耗] → [UI_Dialogue_Main 對話界面]
    ↓
[查看角色和任務] → [UI_Character_Details / UI_Keywords_Details]
    ↓
[進行對話互動] → [輸入回覆 / 語音輸入]
    ↓
[AI即時分析] → [UI_Dialogue_Analysis 分析結果]
    ↓
[完成對話任務] → [UI_Task_Display 任務結果]
```

### 分支流程
- **回覆卡關**: 需要輔助 → UI_Reply_Assistance → 獲得引導 → 繼續對話
- **限時挑戰**: 300秒倒數 → 時間不足 → 使用加時道具 → 延長時間
- **命條不足**: 闖關失敗 → 提供購買補命道具 → 或等待自然恢復
- **任務失敗**: 重新嘗試 → 或使用時光卷 → 挑戰前階段關卡

### 錯誤流程
- **網路中斷**: 顯示連接錯誤 → 嘗試重連 → 保存進度 → 提供離線模式
- **語音識別失敗**: 提示重新錄音 → 或切換文字輸入 → 繼續對話
- **支付失敗**: 顯示支付錯誤 → 檢查餘額 → 重新嘗試 → 或選擇其他支付方式

## 📊 商業邏輯規則

### 營收相關
- **回覆提示道具**: 30鑽石/次，提供三層式智慧引導
- **300秒限時挑戰**: 首次免費，後續50鑽石/次入場費
- **加時道具**: 300鑽石，增加63秒挑戰時間
- **命條購買**: 100鑽石/個，最多持有5個命條

### 遊戲化機制  
- **雙重任務系統**: 劇情任務+指定詞彙使用，同時完成獲得雙倍獎勵
- **即時成就反饋**: 任務完成、詞彙使用觸發慶祝動畫
- **三維度評分**: 語意合適性、語法正確性、表達流暢性各100分
- **星級評分**: 基於三維度得分給予1-3顆星評價

### 用戶體驗規則
- **智慧輔助**: 從輔助學習逐步過渡到獨立表達
- **漸進引導**: 免費任務提示→付費深度引導→完全獨立
- **時間壓力管理**: 300秒倒數+警告系統+緊急道具支援

## 🧪 測試要點

### 功能測試
- [ ] 對話輸入和發送功能正常
- [ ] AI分析回饋準確度測試
- [ ] 三維度評分算法驗證
- [ ] 任務完成判定邏輯測試
- [ ] 詞彙使用檢測準確性
- [ ] 命條消耗和恢復機制
- [ ] 道具購買和使用流程
- [ ] 限時模式倒數計時精確性

### 介面測試
- [ ] 響應式佈局在不同螢幕尺寸下正常顯示
- [ ] 對話氣泡動畫流暢性
- [ ] 語音輸入按鈕反應靈敏
- [ ] 回覆輔助面板滑出效果
- [ ] 任務完成慶祝動畫效果
- [ ] 詞彙使用成功反饋動畫

### 整合測試
- [ ] 與詞彙學習系統的數據同步
- [ ] 與道具商店的支付整合
- [ ] 與排行榜系統的成績上傳
- [ ] 與用戶認證系統的資料綁定

## 📝 開發注意事項

### 前端開發
- 語音識別需要處理瀏覽器權限請求
- 對話氣泡需要支援動態內容高度調整
- 限時模式需要精確的倒數計時實現
- 回覆輔助面板需要優雅的滑出動畫

### 後端開發  
- AI對話分析需要即時回應，建議API響應時間<1秒
- 對話會話需要保持狀態，支援斷線重連
- 三維度評分算法需要準確且一致
- 任務完成判定需要支援複雜邏輯

### 整合注意事項
- WebRTC語音功能需要HTTPS環境
- 對話數據需要即時同步到學習記錄
- 道具使用需要防重複消費機制
- 命條系統需要跨模組數據一致性

## 📚 參考資源

- **UI截圖**: 
  - `docs/02_design/views/UI_Dialogue_Main.png`
  - `docs/02_design/views/UI_Reply_Assistance.png`
  - `docs/02_design/views/UI_Character_Details.png`
- **User Flow**: `docs/04_technical/user-flow-specification.md` - 情境對話系統章節
- **API文檔**: `docs/04_technical/api/dialogue-practice.md`
- **設計規範**: `docs/02_design/ui-ux-guidelines.md`

## 📅 版本歷史

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

---

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