From 58162183e89e6f9a4b562fa916c6d3937c31b932 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=84=AD=E6=B2=9B=E8=BB=92?= Date: Fri, 5 Sep 2025 22:16:48 +0800 Subject: [PATCH] docs: add Chinese documentation guide and update structure MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add comprehensive Chinese README.md for /docs directory - Update .gitignore to exclude docs/05_views/ directory - Include new documentation structure with organized directories - Provide detailed guidance for different team roles and use cases 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .gitignore | 2 +- docs/00_starter/README.md | 162 +++ docs/00_starter/{READ.md => start.md} | 0 docs/02_design/ai-algorithm-specs.md | 183 ++++ docs/02_design/business-logic-rules.md | 298 ++++++ docs/02_design/content-management-specs.md | 395 +++++++ docs/02_design/gamification-mechanics.md | 268 +++++ docs/02_design/ui-ux-guidelines.md | 521 +++++++++ docs/03_development/coding-standards.md | 993 +++++++++++++++++ docs/03_development/development-workflow.md | 796 ++++++++++++++ docs/03_development/project-roadmap.md | 471 +++++++++ docs/04_technical/api-specifications.md | 998 ++++++++++++++++++ docs/04_technical/database-schema.md | 822 +++++++++++++++ .../flutter-dotnet-integration.md | 811 ++++++++++++++ docs/04_technical/tech-stack-decision.md | 582 ++++++++++ 15 files changed, 7301 insertions(+), 1 deletion(-) create mode 100644 docs/00_starter/README.md rename docs/00_starter/{READ.md => start.md} (100%) create mode 100644 docs/02_design/ai-algorithm-specs.md create mode 100644 docs/02_design/business-logic-rules.md create mode 100644 docs/02_design/content-management-specs.md create mode 100644 docs/02_design/gamification-mechanics.md create mode 100644 docs/02_design/ui-ux-guidelines.md create mode 100644 docs/03_development/coding-standards.md create mode 100644 docs/03_development/development-workflow.md create mode 100644 docs/03_development/project-roadmap.md create mode 100644 docs/04_technical/api-specifications.md create mode 100644 docs/04_technical/database-schema.md create mode 100644 docs/04_technical/flutter-dotnet-integration.md create mode 100644 docs/04_technical/tech-stack-decision.md diff --git a/.gitignore b/.gitignore index dc431d8..0e8758a 100644 --- a/.gitignore +++ b/.gitignore @@ -483,4 +483,4 @@ secrets/ *.pem *.p12 *.p8 -*.mobileprovision \ No newline at end of file +*.mobileprovisiondocs/05_views/ diff --git a/docs/00_starter/README.md b/docs/00_starter/README.md new file mode 100644 index 0000000..f9ac386 --- /dev/null +++ b/docs/00_starter/README.md @@ -0,0 +1,162 @@ +# 📚 文檔指南 + +本文檔提供 Drama Ling 專案文檔結構的完整說明。 + +## 📁 目錄結構 + +``` +docs/ +├── 00_starter/ # 專案初始化和模板 +├── 01_requirement/ # 專案需求和規格說明 +├── design/ # 設計和使用者體驗文檔 +├── technical/ # 技術架構和規格說明 +├── development/ # 開發指南和工作流程 +└── README.md # 本文件 - 文檔總覽 +``` + +--- + +## 📂 目錄詳細說明 + +### 🚀 `/00_starter` - 專案基礎 +**用途**: 包含專案初始化和AI輔助開發所使用的基礎模板和提示詞。 + +| 檔案名稱 | 用途 | +|------|---------| +| `CLAUDE_TEMPLATE.md` | Claude AI 互動模板和專案設置 | +| `READ.md` | 使用入門模板的說明指引 | +| `business_function_design_prompt.md` | 生成業務功能設計的 AI 提示詞 | +| `generate_requirements_prompt.md` | 創建專案需求的 AI 提示詞 | +| `generate_system_structure_prompt.md` | 系統架構生成的 AI 提示詞 | +| `system_detail_prompt.md` | 詳細系統規格的 AI 提示詞 | +| `system_structured_schema.json` | 結構化系統設計輸出的 JSON 架構 | + +**使用時機**: 這些檔案主要在專案初始化時使用，以及與 AI 助手協作生成文檔和程式碼結構時使用。 + +--- + +### 📋 `/01_requirement` - 專案需求 +**用途**: 包含核心專案需求、規格說明和系統設計文檔。 + +| 檔案名稱 | 用途 | +|------|---------| +| `founding_pitch.md` | 初始專案提案和商業案例 | +| `requirements.md` | **主要需求文檔** - 詳細的產品規格、功能和使用者故事 | +| `system_structure_design.json` | **結構化系統設計** - 從需求生成，包含模組、功能和UI視圖的JSON格式 | + +**關鍵文檔**: `requirements.md` 是產品應該做什麼以及如何運作的唯一真實來源。 + +--- + +### 🎨 `/design` - 設計規格 +**用途**: 涵蓋使用者體驗、視覺設計和互動模式的文檔。 + +| 檔案名稱 | 用途 | +|------|---------| +| `ai-algorithm-specs.md` | AI 分析演算法和語言處理規格 | +| `business-logic-rules.md` | 核心商業規則和邏輯流程定義 | +| `content-management-specs.md` | 內容創建、策劃和管理工作流程 | +| `gamification-mechanics.md` | 遊戲元素、成就和獎勵系統設計 | +| `ui-ux-guidelines.md` | 視覺設計標準、組件庫和使用者介面指南 | + +**目標讀者**: 設計師、前端開發人員和產品經理。 + +--- + +### ⚙️ `/technical` - 技術架構 +**用途**: 技術實作細節、系統架構和整合規格說明。 + +| 檔案名稱 | 用途 | +|------|---------| +| `api-specifications.md` | **REST API 文檔** - 端點、請求/回應格式、認證 | +| `database-schema.md` | 資料庫設計、資料表、關聯和資料模型 | +| `flutter-dotnet-integration.md` | Flutter 前端與 .NET Core 後端的整合指南 | +| `tech-stack-decision.md` | 技術選擇、理由和架構決策 | + +**關鍵文檔**: `api-specifications.md` 作為前端和後端團隊之間的契約。 + +--- + +### 👨‍💻 `/development` - 開發指南 +**用途**: 為開發人員提供編碼標準、工作流程和專案路線圖的指南。 + +| 檔案名稱 | 用途 | +|------|---------| +| `coding-standards.md` | Flutter/Dart 和 .NET/C# 的程式碼風格指南、命名慣例和最佳實踐 | +| `development-workflow.md` | Git 工作流程、分支策略、程式碼審查流程和開發生命週期 | +| `project-roadmap.md` | **開發時程表** - 階段、里程碑和功能交付時程 | + +**目標讀者**: 所有參與專案的開發人員。 + +--- + +## 🎯 如何使用這個文檔 + +### 新團隊成員 +1. **從這裡開始**: 閱讀這個 `README.md` 文檔總覽 +2. **了解產品**: 閱讀 `/01_requirement/requirements.md` +3. **學習技術棧**: 查看 `/technical/tech-stack-decision.md` +4. **遵循開發流程**: 學習 `/development/development-workflow.md` +5. **遵守編碼標準**: 查看 `/development/coding-standards.md` + +### 前端開發人員 +- 主要文檔: `/design/ui-ux-guidelines.md`, `/technical/flutter-dotnet-integration.md` +- API 契約: `/technical/api-specifications.md` +- 編碼標準: `/development/coding-standards.md` + +### 後端開發人員 +- 主要文檔: `/technical/api-specifications.md`, `/technical/database-schema.md` +- 整合指南: `/technical/flutter-dotnet-integration.md` +- 商業邏輯: `/design/business-logic-rules.md` + +### 產品經理 +- 主要文檔: `/01_requirement/requirements.md`, `/development/project-roadmap.md` +- 設計規格: `/design/` 目錄下的所有檔案 +- 進度追蹤: `/development/project-roadmap.md` + +### 設計師 +- 主要文檔: `/design/ui-ux-guidelines.md`, `/design/gamification-mechanics.md` +- 內容策略: `/design/content-management-specs.md` + +--- + +## 🔄 文檔維護 + +### 何時更新 +- **需求變更**: 更新 `/01_requirement/requirements.md` 並重新生成 `system_structure_design.json` +- **API 變更**: 更新 `/technical/api-specifications.md` +- **設計更新**: 更新 `/design/` 目錄中相關檔案 +- **新功能**: 更新 `/development/project-roadmap.md` 中的路線圖 + +### 責任歸屬 +- **產品團隊**: `/01_requirement/` 和 `/design/` 目錄 +- **工程團隊**: `/technical/` 和 `/development/` 目錄 +- **AI/DevOps**: `/00_starter/` 目錄（模板維護） + +--- + +## 🔍 快速參考 + +| 尋找... | 前往... | +|----------------|----------| +| 要建構什麼功能 | `/01_requirement/requirements.md` | +| API 端點和資料格式 | `/technical/api-specifications.md` | +| 資料庫結構 | `/technical/database-schema.md` | +| UI 設計標準 | `/design/ui-ux-guidelines.md` | +| 如何貢獻程式碼 | `/development/development-workflow.md` | +| 開發時程表 | `/development/project-roadmap.md` | +| 系統架構 | `/01_requirement/system_structure_design.json` | + +--- + +## 📞 技術支援 + +如果您需要任何文檔的說明： +- 📧 Email: dev@dramaling.com +- 💬 Slack: #dev-support +- 📱 Issues: [GitHub Issues](https://github.com/JettCheng/DramaLingApp/issues) + +--- + +**最後更新**: 2025-01-05 +**版本**: 1.0.0 \ No newline at end of file diff --git a/docs/00_starter/READ.md b/docs/00_starter/start.md similarity index 100% rename from docs/00_starter/READ.md rename to docs/00_starter/start.md diff --git a/docs/02_design/ai-algorithm-specs.md b/docs/02_design/ai-algorithm-specs.md new file mode 100644 index 0000000..76893ed --- /dev/null +++ b/docs/02_design/ai-algorithm-specs.md @@ -0,0 +1,183 @@ +# AI 對話分析算法規格 + +## 概述 +定義 Drama Ling 應用中 AI 對話分析系統的具體實現方案，包含語法、語意、流暢度三維度評分邏輯。 + +## 核心評分維度 + +### 1. 語法評分 (Grammar Score) +**目標**: 評估用戶對話的語法正確性 + +#### 評分標準 (0-100分) +- [ ] **基礎語法** (40分) + - 主詞動詞一致性 + - 時態使用正確性 + - 詞序結構正確性 + +- [ ] **進階語法** (35分) + - 複句結構使用 + - 介系詞使用準確性 + - 語法變化形式正確性 + +- [ ] **高級語法** (25分) + - 複雜句型運用 + - 條件句、被動語態等 + - 語法多樣性展現 + +#### 實現技術方案 +- [ ] **技術選擇**: 待決定 (GPT-4/Claude/自建模型) +- [ ] **API整合方式**: 待定義 +- [ ] **錯誤分類系統**: 待建立 +- [ ] **即時分析響應時間**: 目標 < 2秒 + +### 2. 語意評分 (Semantic Score) +**目標**: 評估對話內容的語意適切性和情境理解 + +#### 評分標準 (0-100分) +- [ ] **情境理解** (45分) + - 場景適應性 + - 對話目標達成度 + - 上下文連貫性 + +- [ ] **詞彙選擇** (35分) + - 詞彙準確性 + - 語域適當性 + - 表達豐富度 + +- [ ] **邏輯性** (20分) + - 推理合理性 + - 回應關聯性 + - 論述完整性 + +#### 實現技術方案 +- [ ] **語意理解模型**: 待選擇 +- [ ] **情境知識庫**: 待建立 +- [ ] **評分權重配置**: 待調整 +- [ ] **多語言支援策略**: 待規劃 + +### 3. 流暢度評分 (Fluency Score) +**目標**: 評估對話的自然度和表達流暢性 + +#### 評分標準 (0-100分) +- [ ] **表達自然度** (40分) + - 語言節奏感 + - 慣用表達使用 + - 母語使用習慣 + +- [ ] **對話連接** (35分) + - 轉接詞使用 + - 對話銜接流暢性 + - 互動反應適時性 + +- [ ] **整體表現** (25分) + - 整段對話完整性 + - 表達信心度 + - 溝通效果達成 + +#### 實現技術方案 +- [ ] **流暢度檢測算法**: 待開發 +- [ ] **對話品質指標**: 待定義 +- [ ] **即時反饋機制**: 待設計 +- [ ] **學習進度追蹤**: 待實現 + +## AI 對話訂正功能 + +### 訂正類型 +- [ ] **語法訂正**: 直接糾錯並提供正確表達 +- [ ] **語意優化**: 建議更貼切的表達方式 +- [ ] **流暢度改善**: 提供更自然的表達替代方案 +- [ ] **文化適應性**: 符合目標語言文化的表達建議 + +### 訂正展示方式 +- [ ] **即時高亮**: 標示問題部分 +- [ ] **建議面板**: 顯示改進方案 +- [ ] **解釋說明**: 提供訂正原因 +- [ ] **學習建議**: 相關學習資源推薦 + +### 技術實現細節 +- [ ] **訂正算法選擇**: 待決定 +- [ ] **多層次訂正邏輯**: 待設計 +- [ ] **用戶接受度追蹤**: 待建立 +- [ ] **訂正準確度評估**: 待實現 + +## 即時分析與回覆建議 + +### 分析觸發機制 +- [ ] **即時觸發**: 用戶輸入完成後立即分析 +- [ ] **按需觸發**: 用戶主動請求分析 +- [ ] **階段性觸發**: 對話段落結束後分析 +- [ ] **綜合評估**: 整次對話結束後完整分析 + +### 回覆建議系統 +- [ ] **情境適應建議**: 基於場景的回覆選項 +- [ ] **難度分級建議**: 符合用戶程度的表達方式 +- [ ] **個人化建議**: 基於學習記錄的客製化建議 +- [ ] **文化脈絡建議**: 考量文化背景的表達建議 + +### 建議展示格式 +- [ ] **候選回覆**: 3-5個建議回覆選項 +- [ ] **難度標示**: 標明建議的語言難度等級 +- [ ] **使用情境**: 說明適用場合和語境 +- [ ] **學習重點**: 強調該建議的學習價值 + +## 技術架構設計 + +### AI 模型整合 +- [ ] **主要AI服務商**: 待選擇 (OpenAI/Anthropic/Google/其他) +- [ ] **備用方案**: 多供應商容錯機制 +- [ ] **本地化處理**: 敏感資料保護方案 +- [ ] **成本控制**: API使用量管理策略 + +### 效能優化 +- [ ] **響應時間**: 目標全流程 < 3秒 +- [ ] **並發處理**: 支援多用戶同時分析 +- [ ] **快取策略**: 常見分析結果快取 +- [ ] **負載平衡**: 分散式處理架構 + +### 資料隱私 +- [ ] **用戶對話保護**: 資料加密和存取控制 +- [ ] **AI訓練資料**: 不使用用戶資料訓練 +- [ ] **資料保留政策**: 對話記錄管理規則 +- [ ] **合規要求**: GDPR等隱私法規遵循 + +## 評估與優化 + +### 算法效果評估 +- [ ] **準確度指標**: 各維度評分準確性測量 +- [ ] **用戶滿意度**: 評分結果接受度調查 +- [ ] **學習效果**: 長期學習成效追蹤 +- [ ] **對比實驗**: A/B測試不同算法方案 + +### 持續優化機制 +- [ ] **模型微調**: 基於用戶回饋調整算法 +- [ ] **權重優化**: 動態調整各維度評分權重 +- [ ] **新功能實驗**: 漸進式功能測試上線 +- [ ] **效能監控**: 系統性能持續監測 + +--- + +## 待完成任務 + +### 高優先級 +1. [ ] 確定主要AI技術供應商和API方案 +2. [ ] 設計三維度評分的具體算法邏輯 +3. [ ] 建立即時分析的技術架構 +4. [ ] 定義訂正功能的實現方式 + +### 中優先級 +1. [ ] 建立評分準確度的測試基準 +2. [ ] 設計個人化建議的推薦算法 +3. [ ] 規劃多語言支援的技術方案 +4. [ ] 建立用戶回饋收集機制 + +### 低優先級 +1. [ ] 研究進階AI功能的可行性 +2. [ ] 探索本地化AI模型的部署方案 +3. [ ] 調研語言學習領域的最新AI技術 +4. [ ] 建立與學術機構的合作評估機制 + +--- + +**最後更新**: 2024年9月5日 +**負責人**: 待分配 +**審查週期**: 每兩週檢討一次 \ No newline at end of file diff --git a/docs/02_design/business-logic-rules.md b/docs/02_design/business-logic-rules.md new file mode 100644 index 0000000..59ea811 --- /dev/null +++ b/docs/02_design/business-logic-rules.md @@ -0,0 +1,298 @@ +# 商業邏輯與營收規則 + +## 概述 +定義 Drama Ling 應用的完整商業模式實現，包含訂閱制、內購、廣告等營收機制的具體規則和邏輯。 + +## 訂閱制服務 + +### 訂閱方案設計 + +#### 免費版 (Free Tier) +**功能範圍**: +- [ ] **基礎對話練習**: 每日限制 5 次對話 +- [ ] **基礎場景**: 僅開放日常生活場景 (共10個) +- [ ] **AI分析功能**: 每日限制 3 次使用 +- [ ] **排行榜**: 僅顯示好友排行榜 +- [ ] **成就系統**: 僅開放基礎成就 (30%) +- [ ] **廣告觀看**: 觀看廣告可獲得額外使用次數 + +**限制條件**: +- [ ] 對話練習冷卻時間: 4小時 +- [ ] 不支援離線下載 +- [ ] 廣告頻率: 每3次操作顯示1次 +- [ ] 不支援匯出學習記錄 + +#### 基礎版 (Basic Plan) - 月費 NT$199 +**解鎖功能**: +- [ ] **無限對話練習**: 移除每日次數限制 +- [ ] **擴展場景**: 開放社交互動場景 (額外12個) +- [ ] **無廣告體驗**: 完全移除廣告干擾 +- [ ] **進階AI分析**: 無限制使用三維度評分 +- [ ] **詳細學習報告**: 週報和月報功能 +- [ ] **雲端同步**: 跨設備學習進度同步 + +**優惠政策**: +- [ ] 年付優惠: NT$1,980 (相當於月付83折) +- [ ] 學生優惠: 憑學生證享7折優惠 +- [ ] 首月體驗: 新用戶首月 NT$99 + +#### 進階版 (Premium Plan) - 月費 NT$399 +**解鎖功能**: +- [ ] **全場景開放**: 包含應急處理和專業場景 +- [ ] **個人化學習計劃**: AI客製化學習路徑 +- [ ] **優先客服**: 24小時內回覆保證 +- [ ] **專屬成就**: 解鎖所有成就和徽章 +- [ ] **語音辨識**: 口說練習和發音評估 +- [ ] **離線模式**: 下載內容供離線學習 +- [ ] **學習數據匯出**: 完整學習歷程匯出 + +**年付優惠**: NT$3,999 (相當於月付83折) + +#### 專業版 (Professional Plan) - 月費 NT$799 +**解鎖功能**: +- [ ] **企業場景**: 商務、面試、簡報等專業場景 +- [ ] **一對一AI導師**: 個人化指導和建議 +- [ ] **多語言支援**: 支援5種目標語言學習 +- [ ] **競賽特權**: 參與高級競賽和獲得實體獎勵 +- [ ] **API存取**: 開發者可整合學習數據 +- [ ] **白標服務**: 企業客戶客製化版本 +- [ ] **專屬社群**: 高級用戶專屬討論區 + +### 訂閱管理機制 + +#### 訂閱流程 +- [ ] **免費試用**: 所有付費方案提供7天免費試用 +- [ ] **自動續約**: 到期前24小時自動扣款續約 +- [ ] **取消政策**: 隨時可取消，當期使用到期為止 +- [ ] **升級降級**: 即時生效，費用按比例計算 +- [ ] **暫停功能**: 最多可暫停3個月 (保留資料) + +#### 付費方式整合 +- [ ] **信用卡**: 支援 Visa、MasterCard、JCB +- [ ] **數位支付**: Apple Pay、Google Pay、Samsung Pay +- [ ] **電信帳單**: 與電信商合作代收 +- [ ] **第三方支付**: 街口支付、LINE Pay、悠遊付 +- [ ] **銀行轉帳**: 提供虛擬帳號轉帳 +- [ ] **禮品卡**: 實體和數位禮品卡購買 + +#### 計費邏輯 +- [ ] **按月計費**: 每月同一日期扣款 +- [ ] **按年計費**: 年付享折扣優惠 +- [ ] **比例退款**: 降級時退還剩餘天數費用 +- [ ] **暫停計費**: 暫停期間停止扣款 +- [ ] **逾期處理**: 扣款失敗後7天緩衝期 + +## 內容付費機制 + +### 付費內容類型 + +#### 特殊場景包 (每包 NT$99-299) +- [ ] **主題場景包**: + - 旅遊場景包 (機場、飯店、觀光) - NT$149 + - 醫療場景包 (看病、急救、藥局) - NT$199 + - 法律場景包 (法庭、律師、契約) - NT$299 + - 學術場景包 (論文、研究、會議) - NT$249 + +- [ ] **文化場景包**: + - 節日慶典場景 (聖誕、新年、婚禮) - NT$129 + - 運動場景包 (健身、比賽、戶外) - NT$149 + - 美食場景包 (料理、品酒、米其林) - NT$179 + - 藝術場景包 (博物館、畫展、音樂會) - NT$199 + +#### 專業對話包 (每包 NT$199-499) +- [ ] **商務專業包**: + - 國際商務談判包 - NT$399 + - 跨國會議包 - NT$299 + - 企業簡報包 - NT$249 + - 客戶關係包 - NT$199 + +- [ ] **考試準備包**: + - IELTS口說包 - NT$499 + - TOEFL口說包 - NT$499 + - 多益口說包 - NT$399 + - 全民英檢包 - NT$299 + +#### 名師課程包 (每包 NT$599-1,299) +- [ ] **語言專家系列**: 知名語言學習專家錄製 +- [ ] **母語人士系列**: 道地母語人士對話示範 +- [ ] **文化導師系列**: 深度文化背景解析 +- [ ] **商務導師系列**: 商界菁英實戰經驗 + +### 內購邏輯設計 + +#### 購買流程 +- [ ] **預覽功能**: 購買前可試用第一個場景 +- [ ] **一鍵購買**: 整合系統支付，無需跳轉 +- [ ] **批次購買**: 購買多個內容包享組合折扣 +- [ ] **心願清單**: 加入心願清單，降價時通知 +- [ ] **禮品贈送**: 可購買贈送給好友 + +#### 定價策略 +- [ ] **動態定價**: 根據用戶程度和偏好調整價格 +- [ ] **限時優惠**: 新內容上線限時特價 +- [ ] **組合折扣**: 相關內容包組合購買享折扣 +- [ ] **會員折扣**: 訂閱用戶享內購9折優惠 +- [ ] **活動促銷**: 節日和特殊活動期間折扣 + +#### 內容保護機制 +- [ ] **DRM保護**: 防止內容被盜用或分享 +- [ ] **帳號綁定**: 購買內容綁定特定帳號 +- [ ] **設備限制**: 最多可在3台設備上使用 +- [ ] **離線保護**: 離線內容定期需要驗證授權 +- [ ] **盜版檢測**: 偵測和防範非法分享行為 + +## 廣告系統設計 + +### 廣告展示策略 + +#### 免費用戶廣告頻率 +- [ ] **啟動廣告**: App開啟時展示 (5秒，可跳過) +- [ ] **練習間廣告**: 每3次對話練習後展示 +- [ ] **功能解鎖廣告**: 使用進階功能前觀看廣告 +- [ ] **退出廣告**: 結束學習階段時展示 +- [ ] **獎勵廣告**: 主動觀看獲得獎勵 + +#### 廣告類型與時長 +- [ ] **影片廣告**: 15-30秒影片廣告，教育、遊戲類優先 +- [ ] **互動廣告**: 可互動的廣告內容，增加參與度 +- [ ] **原生廣告**: 融入介面設計的原生廣告內容 +- [ ] **橫幅廣告**: 螢幕底部或頂部的橫幅展示 +- [ ] **全螢幕廣告**: 在自然暫停點展示的全螢幕廣告 + +### 廣告獎勵機制 + +#### 觀看獎勵類型 +- [ ] **額外練習次數**: 觀看廣告獲得2次額外對話機會 +- [ ] **AI分析次數**: 獲得1次額外AI分析機會 +- [ ] **積分獎勵**: 觀看廣告獲得25-50積分 +- [ ] **內容試用**: 獲得付費場景1小時試用權 +- [ ] **社交功能**: 獲得好友排行榜查看權限 + +#### 獎勵發放規則 +- [ ] **每日上限**: 每種獎勵每日最多獲得5次 +- [ ] **冷卻時間**: 同類獎勵需間隔30分鐘 +- [ ] **觀看驗證**: 需完整觀看才能獲得獎勵 +- [ ] **獎勵疊加**: 不同類型獎勵可以疊加使用 +- [ ] **有效期限**: 獎勵需在獲得後24小時內使用 + +### 廣告品質控制 + +#### 廣告內容審核 +- [ ] **教育相關**: 優先顯示教育、學習相關廣告 +- [ ] **年齡適宜**: 確保廣告內容適合目標用戶年齡層 +- [ ] **文化敏感**: 避免文化衝突或敏感內容 +- [ ] **品牌安全**: 排除有害品牌和不當內容 +- [ ] **用戶回饋**: 建立廣告品質回饋機制 + +#### 廣告效果最佳化 +- [ ] **個人化投放**: 基於用戶興趣和行為投放相關廣告 +- [ ] **A/B測試**: 測試不同廣告格式和時機的效果 +- [ ] **頻率控制**: 避免相同廣告過度曝光造成反感 +- [ ] **時段優化**: 在用戶活躍時段投放高價值廣告 +- [ ] **轉換追蹤**: 追蹤廣告點擊和轉換效果 + +## 企業客戶方案 + +### B2B 服務方案 + +#### 企業培訓版 (客製化報價) +**服務內容**: +- [ ] **員工帳號管理**: 批次開設和管理員工學習帳號 +- [ ] **學習進度追蹤**: 管理者可查看員工學習狀況 +- [ ] **客製化內容**: 根據企業需求開發專屬學習場景 +- [ ] **培訓報告**: 定期提供企業培訓成效報告 +- [ ] **專屬客服**: 指派專人負責企業客戶服務 +- [ ] **API整合**: 與企業現有系統整合 + +#### 教育機構版 (年費制) +**服務內容**: +- [ ] **學生管理系統**: 教師可管理學生學習進度 +- [ ] **課程規劃工具**: 協助教師規劃語言學習課程 +- [ ] **成績管理**: 整合學習成果到既有成績系統 +- [ ] **教學資源**: 提供教師專用教學資源和指南 +- [ ] **大量授權**: 支援數百到數千學生同時使用 +- [ ] **教育折扣**: 相較個人版享有大幅優惠 + +### 定價模式 + +#### 企業培訓版定價 +- [ ] **基礎方案**: NT$200/人/月 (最少50人) +- [ ] **標準方案**: NT$350/人/月 (包含客製化內容) +- [ ] **高級方案**: NT$500/人/月 (包含專屬客服和API) +- [ ] **設定費**: 一次性 NT$50,000 系統設定費 +- [ ] **客製化開發**: 另外報價，通常 NT$100,000 起跳 + +#### 教育機構版定價 +- [ ] **小型機構** (≤100學生): NT$8,000/月 +- [ ] **中型機構** (101-500學生): NT$25,000/月 +- [ ] **大型機構** (501-2000學生): NT$80,000/月 +- [ ] **超大型機構** (>2000學生): 客製化報價 + +## 數據服務營收 + +### 匿名化數據分析服務 +- [ ] **學習趨勢報告**: 提供語言學習趨勢分析報告 +- [ ] **教育機構諮詢**: 協助教育機構優化教學方法 +- [ ] **語言能力評估**: 提供標準化語言能力評估服務 +- [ ] **內容效果分析**: 分析不同學習內容的效果差異 +- [ ] **技術授權**: 授權AI分析技術給其他教育平台 + +### 數據隱私保護 +- [ ] **完全匿名化**: 移除所有可識別個人身份的資訊 +- [ ] **聚合數據**: 僅提供統計性聚合數據，不提供個人資料 +- [ ] **用戶同意**: 明確告知並取得用戶同意才收集分析數據 +- [ ] **法規遵循**: 完全遵守GDPR和相關隱私法規 +- [ ] **安全傳輸**: 使用最高等級加密保護數據傳輸 + +--- + +## 技術實現考量 + +### 支付系統整合 +- [ ] **第三方支付串接**: 整合多種支付方式API +- [ ] **交易安全**: PCI DSS合規的支付安全機制 +- [ ] **退款處理**: 自動化退款處理流程 +- [ ] **發票開立**: 整合電子發票開立系統 +- [ ] **帳務對帳**: 自動化帳務對帳和財務報告 + +### 訂閱管理系統 +- [ ] **自動續約**: 智慧續約提醒和自動扣款機制 +- [ ] **方案升降級**: 即時生效的方案變更處理 +- [ ] **使用量監控**: 即時監控用戶使用量和限制 +- [ ] **帳號暫停復原**: 自動化帳號狀態管理 +- [ ] **客戶生命週期**: 完整的客戶生命週期管理 + +### 廣告平台整合 +- [ ] **廣告SDK整合**: 整合主流廣告平台SDK +- [ ] **廣告投放優化**: 智慧廣告投放和最佳化 +- [ ] **收益最大化**: 動態調整廣告格式和頻率 +- [ ] **廣告屏蔽檢測**: 檢測並應對廣告屏蔽軟體 +- [ ] **廣告效果追蹤**: 精確的廣告效果分析和報告 + +--- + +## 待完成任務 + +### 高優先級 +1. [ ] 確定各訂閱方案的具體定價和功能範圍 +2. [ ] 設計付費內容的具體場景和定價策略 +3. [ ] 建立廣告獎勵機制的平衡性測試 +4. [ ] 規劃企業客戶的銷售和服務流程 + +### 中優先級 +1. [ ] 設計支付流程的使用者體驗 +2. [ ] 建立客戶服務的標準作業程序 +3. [ ] 規劃數據分析服務的產品化方案 +4. [ ] 設計會員等級和忠誠度計劃 + +### 低優先級 +1. [ ] 研究新興支付方式的整合可能性 +2. [ ] 探索NFT或區塊鏈技術的應用場景 +3. [ ] 建立合作夥伴的收益分成機制 +4. [ ] 設計社群變現的創新模式 + +--- + +**最後更新**: 2024年9月5日 +**負責人**: 待分配 +**審查週期**: 每兩週檢討一次 \ No newline at end of file diff --git a/docs/02_design/content-management-specs.md b/docs/02_design/content-management-specs.md new file mode 100644 index 0000000..4e8935c --- /dev/null +++ b/docs/02_design/content-management-specs.md @@ -0,0 +1,395 @@ +# 內容管理規格文件 + +## 概述 +定義 Drama Ling 應用中所有學習內容的創作標準、管理架構和品質控制機制。 + +## 劇本創作標準 + +### 劇本結構規格 + +#### 基本劇本架構 +```json +{ + "scenario_id": "SC_Restaurant_01", + "scenario_name": "餐廳訂位", + "category": "daily_life", + "difficulty_level": "A2", + "estimated_duration": "5-8分鐘", + "learning_objectives": ["預約用餐", "詢問菜單", "表達偏好"], + "target_vocabulary": ["reservation", "available", "preference"], + "cultural_context": "西式餐廳用餐禮儀", + "dialogue_flow": {...} +} +``` + +#### 對話流程設計原則 +- [ ] **情境設定**: 清楚的場景背景和角色身份 +- [ ] **目標導向**: 每個劇本都有明確的溝通目標 +- [ ] **循序漸進**: 難度由淺入深，符合學習曲線 +- [ ] **互動性強**: 提供多種對話分支選擇 +- [ ] **實用性高**: 貼近真實生活溝通需求 + +### 劇本分類體系 + +#### 按難度分級 (CEFR標準) +- [ ] **A1 初學者**: 基礎日常對話 (自我介紹、購物等) +- [ ] **A2 初級**: 簡單社交對話 (餐廳、交通等) +- [ ] **B1 中級**: 複雜情境對話 (工作會議、申訴等) +- [ ] **B2 中高級**: 專業場景對話 (面試、簡報等) +- [ ] **C1 高級**: 抽象議題討論 (辯論、學術等) +- [ ] **C2 精通級**: 專業領域深度對話 + +#### 按場景主題分類 +**日常生活類** (20個場景) +- [ ] 自我介紹與問候 +- [ ] 購物和消費 +- [ ] 餐廳用餐 +- [ ] 交通出行 +- [ ] 醫療保健 +- [ ] 住宿安排 +- [ ] 銀行金融 +- [ ] 郵政服務 +- [ ] 娛樂休閒 +- [ ] 家庭生活 + +**社交互動類** (15個場景) +- [ ] 朋友聚會 +- [ ] 約會戀愛 +- [ ] 鄰里互動 +- [ ] 社團活動 +- [ ] 節慶慶祝 +- [ ] 運動健身 +- [ ] 興趣愛好 +- [ ] 旅遊規劃 +- [ ] 文化交流 +- [ ] 志工服務 + +**應急處理類** (12個場景) +- [ ] 車禍事故處理 +- [ ] 醫療急救 +- [ ] 報警求助 +- [ ] 投訴申訴 +- [ ] 設備故障 +- [ ] 迷路求助 +- [ ] 金融詐騙 +- [ ] 自然災害 +- [ ] 法律諮詢 +- [ ] 心理諮商 + +**專業場景類** (18個場景) +- [ ] 商務談判 +- [ ] 工作面試 +- [ ] 會議簡報 +- [ ] 客戶服務 +- [ ] 技術討論 +- [ ] 學術研究 +- [ ] 教育培訓 +- [ ] 醫療諮詢 +- [ ] 法律程序 +- [ ] 媒體採訪 + +### 劇本創作指南 + +#### 對話編寫原則 +- [ ] **自然流暢**: 符合目標語言的自然表達習慣 +- [ ] **文化適切**: 考量目標語言的文化背景和習俗 +- [ ] **語法重點**: 每個劇本強調特定語法結構 +- [ ] **詞彙密度**: 新詞彙密度控制在15-25%之間 +- [ ] **重複強化**: 重要詞彙和句型在對話中多次出現 + +#### 角色設計規範 +- [ ] **角色背景**: 明確的年齡、職業、性格設定 +- [ ] **對話風格**: 符合角色身份的語言使用風格 +- [ ] **情緒表達**: 透過語言展現角色情緒變化 +- [ ] **互動動機**: 每個角色都有清楚的對話動機 +- [ ] **文化代表性**: 角色設定體現多元文化背景 + +#### 分支劇情設計 +- [ ] **多重選擇**: 提供3-5個對話選項供用戶選擇 +- [ ] **後果差異**: 不同選擇導向不同的對話發展 +- [ ] **學習重點**: 每個分支突出不同的學習重點 +- [ ] **複雜度漸增**: 後續分支難度逐漸提升 +- [ ] **回歸主線**: 分支最終回歸主要學習目標 + +### 品質檢核標準 + +#### 語言準確性檢查 +- [ ] **母語人士審核**: 至少一位母語專家審核 +- [ ] **語法正確性**: 確保語法使用完全正確 +- [ ] **用詞準確性**: 詞彙使用符合情境和語域 +- [ ] **發音標註**: 提供正確的發音指導 +- [ ] **語調標記**: 標註語調變化和重音位置 + +#### 教學效果驗證 +- [ ] **學習目標對應**: 內容與學習目標完全對應 +- [ ] **難度適中性**: 透過測試驗證難度合適性 +- [ ] **參與度測試**: 確保內容能維持學習者興趣 +- [ ] **記憶效果**: 驗證詞彙和句型的記憶留存效果 +- [ ] **實用性驗證**: 確認內容在實際情境中的適用性 + +## 詞彙庫組織架構 + +### 詞彙分類系統 + +#### 按頻率分級 +- [ ] **核心詞彙** (1-1000): 最常用的基礎詞彙 +- [ ] **重要詞彙** (1001-3000): 日常溝通必備詞彙 +- [ ] **進階詞彙** (3001-6000): 中級學習者詞彙 +- [ ] **專業詞彙** (6000+): 特定領域專業詞彙 + +#### 按主題領域分類 +**生活主題詞彙** +- [ ] 家庭與人際關係 (300詞) +- [ ] 食物與飲料 (400詞) +- [ ] 衣著與時尚 (250詞) +- [ ] 住房與家具 (350詞) +- [ ] 交通與旅行 (300詞) +- [ ] 健康與醫療 (400詞) +- [ ] 購物與消費 (250詞) +- [ ] 娛樂與休閒 (350詞) + +**學術主題詞彙** +- [ ] 教育與學習 (400詞) +- [ ] 科學與技術 (500詞) +- [ ] 商業與經濟 (450詞) +- [ ] 政治與社會 (350詞) +- [ ] 文化與藝術 (300詞) +- [ ] 環境與自然 (400詞) + +#### 按語法功能分類 +- [ ] **動詞類**: 行為動詞、狀態動詞、助動詞 +- [ ] **名詞類**: 可數名詞、不可數名詞、專有名詞 +- [ ] **形容詞類**: 描述性、評價性、比較級形容詞 +- [ ] **副詞類**: 時間、地點、方式、程度副詞 +- [ ] **連接詞**: 因果、對比、順序連接詞 +- [ ] **介系詞**: 時間、地點、方式介系詞 + +### 詞彙條目規格 + +#### 基本詞彙資訊 +```json +{ + "vocabulary_id": "VOC_0001", + "word": "restaurant", + "phonetic": "/ˈrestərɑːnt/", + "part_of_speech": "noun", + "difficulty_level": "A2", + "frequency_rank": 1250, + "definition": "A place where people pay to sit and eat meals", + "chinese_translation": "餐廳", + "example_sentences": [...], + "collocations": [...], + "related_words": [...], + "usage_notes": "..." +} +``` + +#### 學習輔助資訊 +- [ ] **記憶提示**: 詞根分析、聯想記憶法 +- [ ] **易混淆詞**: 相似詞彙的辨析說明 +- [ ] **使用場景**: 適用的具體溝通場景 +- [ ] **語域標註**: 正式/非正式/口語/書面語標註 +- [ ] **文化背景**: 詞彙使用的文化背景說明 + +#### 多媒體資源 +- [ ] **發音音檔**: 標準發音示範錄音 +- [ ] **情境圖片**: 詞彙概念的視覺化圖片 +- [ ] **使用影片**: 實際使用情境的短影片 +- [ ] **手勢動作**: 相關的肢體語言或手勢說明 +- [ ] **文化圖像**: 體現文化背景的相關圖像 + +### 間隔複習演算法 + +#### 複習間隔計算 +```python +# SuperMemo 2 演算法改良版 +def calculate_next_review(quality_rating, repetition_count, previous_interval, ef_factor): + """ + quality_rating: 1-5 (用戶回答品質) + repetition_count: 複習次數 + previous_interval: 上次複習間隔(天) + ef_factor: 容易程度因子 (1.3-2.5) + """ + # 實際計算邏輯待實現 + pass +``` + +#### 掌握度評估指標 +- [ ] **即時評分** (0-5分): 當次複習的回答品質 +- [ ] **累積掌握度** (0-100%): 基於多次複習的綜合評估 +- [ ] **遺忘曲線預測**: 預測遺忘時間點 +- [ ] **複習緊急度**: 基於遺忘風險的複習優先級 +- [ ] **長期記憶轉化**: 評估是否已轉入長期記憶 + +#### 個人化複習策略 +- [ ] **學習節奏適應**: 根據個人學習速度調整間隔 +- [ ] **弱項強化**: 對掌握度低的詞彙增加複習頻率 +- [ ] **關聯複習**: 相關詞彙組合複習提升效果 +- [ ] **情境複習**: 在相關對話情境中複習詞彙 +- [ ] **多感官複習**: 結合視覺、聽覺、觸覺的複習方式 + +## 多語言支援策略 + +### 支援語言規劃 + +#### 第一階段語言 (MVP版本) +- [ ] **英語** (主要目標語言) + - 美式英語為主，英式英語為輔 + - 涵蓋日常、商務、學術各領域 + - 支援多種口音和方言 + +#### 第二階段語言 (6個月後) +- [ ] **日語**: 考量台灣日語學習需求量大 +- [ ] **韓語**: 韓流文化帶動的學習需求 +- [ ] **西班牙語**: 全球第二大使用人口 + +#### 第三階段語言 (12個月後) +- [ ] **法語**: 歐洲商務和文化需求 +- [ ] **德語**: 工程和學術領域需求 +- [ ] **中文**: 針對外國人學中文的需求 + +### 本地化內容策略 + +#### 文化適應性內容 +- [ ] **節日慶典**: 各文化重要節日的對話場景 +- [ ] **社交禮儀**: 不同文化的禮貌用語和行為規範 +- [ ] **商務文化**: 各國商務溝通的文化差異 +- [ ] **飲食文化**: 各地美食和用餐文化的對話場景 +- [ ] **生活習俗**: 日常生活中的文化差異體現 + +#### 語言變體處理 +- [ ] **方言支援**: 主要方言和口音的識別和教學 +- [ ] **語域差異**: 正式/非正式語言使用的區別 +- [ ] **世代差異**: 不同年齡層的語言使用習慣 +- [ ] **專業用語**: 各行業專業術語的本地化 +- [ ] **網路語言**: 當代網路流行語和俚語 + +### 翻譯品質控制 + +#### 翻譯標準流程 +1. [ ] **專業翻譯**: 母語專家進行初譯 +2. [ ] **交叉審核**: 另一位專家進行審核 +3. [ ] **文化檢查**: 文化顧問檢查文化適切性 +4. [ ] **教學驗證**: 語言教師驗證教學適用性 +5. [ ] **用戶測試**: 目標用戶群測試使用體驗 + +#### 翻譯一致性維護 +- [ ] **術語庫管理**: 建立統一的專業術語翻譯 +- [ ] **風格指南**: 制定各語言的翻譯風格指南 +- [ ] **版本控制**: 追蹤所有翻譯版本和修改歷程 +- [ ] **同步更新**: 原文修改時所有語言版本同步更新 +- [ ] **品質監控**: 定期檢查翻譯品質和一致性 + +## 內容品質控制系統 + +### 內容審核流程 + +#### 創作階段審核 +1. [ ] **需求確認**: 確認內容符合教學需求 +2. [ ] **大綱審核**: 審核內容架構和學習目標 +3. [ ] **初稿創作**: 專業編劇和語言專家創作 +4. [ ] **專家審核**: 語言學習專家審核教學效果 +5. [ ] **母語審核**: 母語專家審核語言準確性 + +#### 測試階段驗證 +1. [ ] **內部測試**: 團隊內部試用和回饋 +2. [ ] **專家測試**: 外部語言專家測試評估 +3. [ ] **用戶測試**: 目標用戶群小規模測試 +4. [ ] **數據分析**: 分析測試數據和學習效果 +5. [ ] **迭代優化**: 基於測試結果優化內容 + +#### 上線後監控 +- [ ] **使用數據追蹤**: 監控內容使用率和完成率 +- [ ] **用戶回饋收集**: 收集用戶對內容的評價和建議 +- [ ] **學習效果分析**: 分析內容對學習成效的影響 +- [ ] **定期更新**: 基於數據和回饋定期更新內容 +- [ ] **版本控制**: 記錄所有內容變更和版本歷史 + +### 內容評分標準 + +#### 語言品質評分 (1-10分) +- [ ] **準確性** (25%): 語法和用詞準確性 +- [ ] **流暢性** (25%): 語言表達的自然流暢度 +- [ ] **適切性** (25%): 符合情境和語域要求 +- [ ] **豐富性** (25%): 語言表達的多樣性和豐富度 + +#### 教學效果評分 (1-10分) +- [ ] **目標對應** (30%): 內容與學習目標的對應程度 +- [ ] **難度適中** (25%): 難度設計的合理性 +- [ ] **參與度** (25%): 內容的趣味性和參與度 +- [ ] **實用性** (20%): 實際應用價值 + +#### 技術品質評分 (1-10分) +- [ ] **系統相容** (30%): 與系統功能的相容性 +- [ ] **載入效能** (25%): 內容載入速度和效能 +- [ ] **互動設計** (25%): 互動元素的設計品質 +- [ ] **錯誤率** (20%): 技術錯誤和bug數量 + +### 持續改進機制 + +#### 內容效果分析 +- [ ] **學習成效追蹤**: 追蹤用戶學習成效變化 +- [ ] **完成率分析**: 分析不同內容的完成率差異 +- [ ] **重複使用率**: 分析內容的重複學習率 +- [ ] **推薦效果**: 分析推薦內容的接受度 +- [ ] **用戶留存影響**: 分析內容對用戶留存的影響 + +#### 最佳化策略 +- [ ] **數據驅動優化**: 基於使用數據優化內容設計 +- [ ] **A/B測試**: 測試不同版本內容的效果差異 +- [ ] **用戶回饋整合**: 將用戶建議整合到內容改進中 +- [ ] **專家建議**: 定期邀請專家評估和建議改進 +- [ ] **技術創新**: 整合新技術提升內容品質和體驗 + +--- + +## 技術實現架構 + +### 內容管理系統 (CMS) +- [ ] **創作工具**: 提供編劇和專家使用的內容創作工具 +- [ ] **審核流程**: 支援多階段審核流程的工作流系統 +- [ ] **版本控制**: 完整的內容版本管理和回溯功能 +- [ ] **多語言支援**: 支援多語言內容的統一管理 +- [ ] **權限管理**: 不同角色的內容存取和編輯權限 + +### 內容發布系統 +- [ ] **內容打包**: 自動化內容打包和壓縮 +- [ ] **CDN部署**: 全球內容分發網路部署 +- [ ] **版本發布**: 支援段階式發布和回滾機制 +- [ ] **快取管理**: 智慧內容快取和更新策略 +- [ ] **效能監控**: 內容載入效能和使用情況監控 + +### 學習數據分析 +- [ ] **使用行為追蹤**: 詳細追蹤用戶學習行為 +- [ ] **效果評估**: 自動化學習效果評估和報告 +- [ ] **個人化推薦**: AI驅動的個人化內容推薦 +- [ ] **預測分析**: 預測學習趨勢和內容需求 +- [ ] **即時優化**: 基於即時數據調整內容策略 + +--- + +## 待完成任務 + +### 高優先級 +1. [ ] 建立劇本創作的具體範本和指導原則 +2. [ ] 設計詞彙庫的資料結構和管理系統 +3. [ ] 實現間隔複習演算法的具體邏輯 +4. [ ] 建立內容品質控制的評估機制 + +### 中優先級 +1. [ ] 設計內容管理系統的使用者介面 +2. [ ] 建立多語言內容的同步管理機制 +3. [ ] 規劃內容創作團隊的工作流程 +4. [ ] 設計用戶回饋的收集和分析系統 + +### 低優先級 +1. [ ] 研究AI輔助內容創作的可行性 +2. [ ] 探索虛擬實境內容的創作可能性 +3. [ ] 建立與外部內容供應商的合作機制 +4. [ ] 設計內容智慧財產權保護方案 + +--- + +**最後更新**: 2024年9月5日 +**負責人**: 待分配 +**審查週期**: 每兩週檢討一次 \ No newline at end of file diff --git a/docs/02_design/gamification-mechanics.md b/docs/02_design/gamification-mechanics.md new file mode 100644 index 0000000..d49df2f --- /dev/null +++ b/docs/02_design/gamification-mechanics.md @@ -0,0 +1,268 @@ +# 遊戲化機制設計規格 + +## 概述 +定義 Drama Ling 應用中的完整遊戲化系統，包含排行榜、成就系統、闖關機制等，提升用戶學習動機和留存率。 + +## 排行榜競爭機制 + +### 排行榜類型 +- [ ] **全球排行榜**: 所有用戶的總體排名 +- [ ] **週排行榜**: 每週重置的短期競爭 +- [ ] **月排行榜**: 月度學習成就排名 +- [ ] **好友排行榜**: 僅顯示好友間的排名比較 +- [ ] **等級分組排行榜**: 依語言程度分組競爭 +- [ ] **地區排行榜**: 基於地理位置的本地競爭 + +### 積分計算規則 +#### 基礎積分來源 (總分 = 基礎分 × 難度係數 × 連擊加成) + +**對話練習積分** +- [ ] **完成對話**: 10分/次 +- [ ] **使用目標詞彙**: +5分/個詞彙 +- [ ] **達成任務目標**: +15分/任務 +- [ ] **流暢完成對話**: +10分 (無需AI提示) + +**評分積分轉換** +- [ ] **語法評分**: 0.3 × 語法分數 +- [ ] **語意評分**: 0.3 × 語意分數 +- [ ] **流暢度評分**: 0.4 × 流暢度分數 +- [ ] **綜合優秀**: 三維度均 > 85分時 +50分獎勵 + +**特殊活動積分** +- [ ] **限時挑戰完成**: 基礎分 × 1.5倍 +- [ ] **首次嘗試新場景**: +25分 +- [ ] **連續學習天數**: +5分/天 (上限 +100分) +- [ ] **幫助其他用戶**: +20分 (回答問題、分享經驗) + +#### 難度係數設定 +- [ ] **初級場景 (A1-A2)**: 1.0倍 +- [ ] **中級場景 (B1-B2)**: 1.3倍 +- [ ] **高級場景 (C1-C2)**: 1.6倍 +- [ ] **專業場景 (商務、醫療等)**: 1.8倍 +- [ ] **即興對話場景**: 2.0倍 + +#### 連擊加成機制 +- [ ] **連續成功對話**: 2-5次 (+10%), 6-10次 (+20%), 11+次 (+30%) +- [ ] **每日連擊**: 連續天數 × 2% 加成 (上限 +60%) +- [ ] **完美表現**: 當日所有對話評分 > 90分時 +50% 加成 +- [ ] **挑戰連擊**: 連續完成限時挑戰 +25% 加成/次 + +### 排行榜更新機制 +- [ ] **即時更新**: 積分變化立即反映 +- [ ] **排名快取**: 5分鐘更新一次排名顯示 +- [ ] **歷史記錄**: 保存每日/週/月排名變化 +- [ ] **排名爭議處理**: 異常分數檢測和處理機制 + +## 成就系統設計 + +### 成就分類 + +#### 學習里程碑類 +- [ ] **初學者**: 完成首次對話 +- [ ] **勤奮學習者**: 連續學習 7/30/100 天 +- [ ] **場景探索家**: 完成 5/15/50 個不同場景 +- [ ] **詞彙大師**: 掌握 100/500/2000 個詞彙 +- [ ] **對話達人**: 完成 50/200/1000 次對話練習 +- [ ] **完美主義者**: 獲得 10/50/200 次滿分評價 + +#### 技能提升類 +- [ ] **語法專家**: 語法評分達到 90+ 分 10/50/200 次 +- [ ] **語意高手**: 語意評分達到 90+ 分 10/50/200 次 +- [ ] **流暢達人**: 流暢度評分達到 90+ 分 10/50/200 次 +- [ ] **全能選手**: 三維度同時達到 85+ 分 5/20/100 次 +- [ ] **快速反應**: 限時挑戰中 10/50/200 次快速完成 + +#### 社交互動類 +- [ ] **樂於助人**: 幫助其他用戶 10/50/200 次 +- [ ] **人氣王**: 獲得 50/200/1000 個好友讚賞 +- [ ] **分享達人**: 分享學習成果 20/100/500 次 +- [ ] **導師**: 指導新用戶學習 5/20/100 次 +- [ ] **社群領袖**: 在討論區發表優質內容 30/150/500 次 + +#### 挑戰征服類 +- [ ] **勇敢嘗試**: 嘗試高難度場景 5/20/100 次 +- [ ] **速度之王**: 在時限內完成對話 20/100/500 次 +- [ ] **堅持不懈**: 從失敗中重新挑戰 10/50/200 次 +- [ ] **創新思維**: 使用創意表達方式 15/75/300 次 +- [ ] **極限挑戰**: 完成最高難度場景 1/5/20 次 + +#### 特殊節日類 +- [ ] **新年決心**: 新年期間連續學習 7 天 +- [ ] **情人節浪漫**: 完成浪漫場景對話 10 次 +- [ ] **萬聖節驚奇**: 完成恐怖/驚悚場景 5 次 +- [ ] **聖誕精神**: 12月完成 25 次學習任務 +- [ ] **生日慶祝**: 生日當天完成特殊挑戰 + +### 成就獎勵機制 +- [ ] **徽章收藏**: 每個成就對應獨特徽章設計 +- [ ] **積分獎勵**: 不同等級成就給予 50/200/500 積分獎勵 +- [ ] **稱號系統**: 解鎖專屬稱號在排行榜顯示 +- [ ] **內容解鎖**: 解鎖新場景、新功能或專屬內容 +- [ ] **實體獎勵**: 高級成就獲得實體紀念品 (限量版) + +### 成就進度追蹤 +- [ ] **視覺化進度條**: 清楚顯示完成進度 +- [ ] **階段性提醒**: 接近完成時的推送通知 +- [ ] **成就預告**: 即將解鎖的成就提示 +- [ ] **統計面板**: 個人成就完成統計概覽 +- [ ] **好友比較**: 與好友的成就完成度比較 + +## 闖關系統設計 + +### 關卡結構 + +#### 主線關卡 (情境導向) +- [ ] **第一章: 日常生活** (10關) + - 自我介紹、購物、餐廳、交通等基礎場景 + - 解鎖條件: 無 (新手引導) + - 完成獎勵: 100積分 + 基礎徽章 + +- [ ] **第二章: 社交互動** (12關) + - 朋友聚會、約會、工作會議、電話對話等 + - 解鎖條件: 第一章通過率 ≥ 80% + - 完成獎勵: 150積分 + 社交徽章 + +- [ ] **第三章: 應急處理** (15關) + - 醫療急救、車禍處理、投訴申訴、緊急求助等 + - 解鎖條件: 第二章通過率 ≥ 75% + 總積分 ≥ 1000 + - 完成獎勵: 200積分 + 危機處理徽章 + +- [ ] **第四章: 專業場景** (18關) + - 商務談判、學術討論、技術交流、面試等 + - 解鎖條件: 第三章通過率 ≥ 70% + 連續學習 ≥ 30天 + - 完成獎勵: 300積分 + 專業徽章 + +#### 支線關卡 (技能導向) +- [ ] **語法強化關**: 專注語法訓練的特殊關卡 +- [ ] **詞彙擴展關**: 大量新詞彙學習關卡 +- [ ] **發音矯正關**: 語音識別和發音練習關卡 +- [ ] **文化理解關**: 目標語言文化背景學習關卡 +- [ ] **考試準備關**: 針對語言檢定考試的專門關卡 + +#### 每日挑戰關 +- [ ] **每日一題**: 精選對話場景每日更新 +- [ ] **週題挑戰**: 週末特殊難題挑戰 +- [ ] **月度任務**: 整月累積完成的大型任務 +- [ ] **季節活動**: 配合節日的限時特殊關卡 +- [ ] **突發事件**: 隨機出現的緊急情境關卡 + +### 關卡評價系統 +- [ ] **三星評級**: 基於綜合表現的 1-3 星評價 + - ⭐ 通過: 綜合評分 ≥ 60分 + - ⭐⭐ 良好: 綜合評分 ≥ 80分 + - ⭐⭐⭐ 優秀: 綜合評分 ≥ 95分 + +- [ ] **完成條件**: + - 達成主要對話目標 + - 使用指定關鍵詞彙 (如有) + - 在時間限制內完成 (如有) + - 維持角色扮演一致性 + +- [ ] **重複挑戰**: 允許重複挑戰提升星級評價 +- [ ] **額外目標**: 每關設定 2-3 個額外挑戰目標 + +### 解鎖機制 +- [ ] **順序解鎖**: 主線關卡需按順序完成 +- [ ] **條件解鎖**: 滿足特定條件才能解鎖新內容 +- [ ] **付費解鎖**: 部分高級內容需要付費或達到VIP等級 +- [ ] **社交解鎖**: 邀請好友或達到社交成就解鎖 +- [ ] **時間解鎖**: 某些內容在特定時間開放 + +## 進度追蹤系統 + +### 個人進度面板 +- [ ] **整體進度**: 所有關卡完成百分比 +- [ ] **各章節進度**: 每章節詳細完成情況 +- [ ] **技能雷達圖**: 語法/語意/流暢度能力視覺化 +- [ ] **學習軌跡**: 每日/週/月學習時間和強度變化 +- [ ] **成長曲線**: 長期能力提升趨勢圖 + +### 統計資訊 +- [ ] **累計學習時間**: 總學習時長統計 +- [ ] **對話完成數**: 累計完成對話次數 +- [ ] **詞彙掌握量**: 已學習和熟練掌握詞彙統計 +- [ ] **場景體驗數**: 體驗過的不同情境場景統計 +- [ ] **AI互動次數**: 與AI分析系統的互動統計 + +### 學習建議 +- [ ] **弱項分析**: 基於表現數據識別學習弱點 +- [ ] **推薦關卡**: 個性化推薦適合的下一個關卡 +- [ ] **學習計劃**: AI生成的個人化學習進度安排 +- [ ] **複習提醒**: 基於遺忘曲線的複習內容建議 +- [ ] **目標設定**: 協助用戶設定並追蹤學習目標 + +## 社交競爭機制 + +### 好友系統 +- [ ] **好友邀請**: 通過ID、QR碼、聯絡人邀請好友 +- [ ] **好友動態**: 查看好友的學習進度和成就 +- [ ] **互相鼓勵**: 為好友的成就點讚和留言 +- [ ] **學習PK**: 與好友進行一對一學習競賽 +- [ ] **組隊學習**: 多人協作完成團體挑戰 + +### 學習群組 +- [ ] **主題群組**: 按學習主題或程度分組 +- [ ] **地區群組**: 同地區學習者交流群組 +- [ ] **學習夥伴**: 匹配相似程度的學習夥伴 +- [ ] **導師制度**: 高級用戶指導初學者 +- [ ] **學習俱樂部**: 定期舉辦線上/線下學習活動 + +### 競賽活動 +- [ ] **週賽**: 每週主題競賽活動 +- [ ] **月度錦標賽**: 月度大型競賽活動 +- [ ] **季度總決賽**: 季度最高榮譽競賽 +- [ ] **特殊賽事**: 節日或紀念日特別賽事 +- [ ] **團體戰**: 群組間的團體競賽活動 + +--- + +## 技術實現考量 + +### 資料存儲 +- [ ] **積分記錄**: 用戶積分變化歷史記錄 +- [ ] **成就狀態**: 各項成就的完成狀態和進度 +- [ ] **關卡進度**: 關卡完成狀態和評級記錄 +- [ ] **排行榜快取**: 高效的排行榜查詢和更新機制 +- [ ] **統計數據**: 各種學習統計數據的存儲結構 + +### 效能優化 +- [ ] **排行榜快取策略**: Redis快取熱門排行榜數據 +- [ ] **積分批次更新**: 避免頻繁數據庫寫入 +- [ ] **成就檢查優化**: 高效的成就觸發檢測機制 +- [ ] **統計數據預計算**: 定期預計算複雜統計數據 +- [ ] **分散式處理**: 大量用戶同時更新的處理策略 + +### 防作弊機制 +- [ ] **異常檢測**: 識別異常高分或快速完成的可疑行為 +- [ ] **行為分析**: 分析用戶學習行為模式的合理性 +- [ ] **時間驗證**: 驗證完成任務的時間合理性 +- [ ] **IP限制**: 防止同一IP多帳號刷分 +- [ ] **人工審核**: 對可疑高分進行人工審核機制 + +--- + +## 待完成任務 + +### 高優先級 +1. [ ] 確定積分計算的具體數值和平衡性 +2. [ ] 設計成就系統的徽章視覺設計 +3. [ ] 規劃關卡內容的具體場景劇本 +4. [ ] 建立防作弊機制的技術方案 + +### 中優先級 +1. [ ] 設計社交功能的互動介面 +2. [ ] 規劃競賽活動的舉辦週期和規則 +3. [ ] 建立學習數據的分析和建議算法 +4. [ ] 設計個性化推薦系統 + +### 低優先級 +1. [ ] 研究遊戲化的心理學原理應用 +2. [ ] 探索AR/VR技術在闖關系統的應用 +3. [ ] 建立與外部平台的積分兌換機制 +4. [ ] 設計線下活動與線上系統的結合 + +--- + +**最後更新**: 2024年9月5日 +**負責人**: 待分配 +**審查週期**: 每兩週檢討一次 \ No newline at end of file diff --git a/docs/02_design/ui-ux-guidelines.md b/docs/02_design/ui-ux-guidelines.md new file mode 100644 index 0000000..ee2c82b --- /dev/null +++ b/docs/02_design/ui-ux-guidelines.md @@ -0,0 +1,521 @@ +# UI/UX 設計規範 + +## 概述 +定義 Drama Ling 應用的完整使用者介面和使用者體驗設計標準，確保整體設計的一致性和使用性。 + +## 設計原則 + +### 核心設計理念 +- [ ] **沉浸式學習**: 創造身歷其境的語言學習環境 +- [ ] **簡潔直觀**: 界面設計簡潔明瞭，操作直觀易懂 +- [ ] **鼓勵互動**: 透過視覺設計鼓勵用戶積極參與學習 +- [ ] **成就感驅動**: 設計元素突出學習進步和成就感 +- [ ] **文化包容**: 設計考量多元文化背景用戶需求 + +### 使用者體驗原則 +- [ ] **學習導向**: 所有設計決策以提升學習效果為優先 +- [ ] **減少阻力**: 消除學習過程中不必要的操作阻力 +- [ ] **即時回饋**: 提供即時的視覺和互動回饋 +- [ ] **個人化體驗**: 基於用戶偏好和程度調整介面 +- [ ] **無障礙設計**: 確保不同能力用戶都能順利使用 + +## 視覺設計系統 + +### 色彩規範 + +#### 主要色彩 (Primary Colors) +```css +:root { + /* 主要品牌色 - 學習藍 */ + --primary-blue: #2196F3; + --primary-blue-light: #64B5F6; + --primary-blue-dark: #1976D2; + + /* 輔助色 - 成功綠 */ + --success-green: #4CAF50; + --success-green-light: #81C784; + --success-green-dark: #388E3C; + + /* 強調色 - 活力橙 */ + --accent-orange: #FF9800; + --accent-orange-light: #FFB74D; + --accent-orange-dark: #F57C00; +} +``` + +#### 功能性色彩 (Functional Colors) +```css +:root { + /* 錯誤和警告 */ + --error-red: #F44336; + --warning-yellow: #FFC107; + + /* 資訊提示 */ + --info-cyan: #00BCD4; + + /* 中性色調 */ + --text-primary: #212121; + --text-secondary: #757575; + --background-primary: #FFFFFF; + --background-secondary: #FAFAFA; + --divider: #E0E0E0; +} +``` + +#### 遊戲化色彩 (Gamification Colors) +```css +:root { + /* 等級和成就 */ + --bronze: #CD7F32; + --silver: #C0C0C0; + --gold: #FFD700; + --platinum: #E5E4E2; + + /* 排行榜 */ + --rank-1st: #FFD700; + --rank-2nd: #C0C0C0; + --rank-3rd: #CD7F32; + --rank-other: #90A4AE; +} +``` + +### 字體系統 + +#### 中文字體 +- [ ] **主要字體**: Noto Sans TC (Google Fonts) +- [ ] **備用字體**: PingFang TC, Microsoft JhengHei, sans-serif +- [ ] **特殊用途**: 標題可使用 Noto Serif TC 增加正式感 + +#### 英文字體 +- [ ] **主要字體**: Inter (現代、易讀) +- [ ] **備用字體**: -apple-system, BlinkMacSystemFont, Roboto, sans-serif +- [ ] **等寬字體**: JetBrains Mono (程式碼、發音標記) + +#### 字體大小規範 +```css +:root { + /* 移動設備字體大小 */ + --text-xs: 12px; /* 提示文字 */ + --text-sm: 14px; /* 輔助資訊 */ + --text-base: 16px; /* 正文內容 */ + --text-lg: 18px; /* 重要文字 */ + --text-xl: 20px; /* 小標題 */ + --text-2xl: 24px; /* 標題 */ + --text-3xl: 30px; /* 大標題 */ + + /* 桌面設備字體大小 */ + --text-desktop-base: 18px; + --text-desktop-lg: 20px; + --text-desktop-xl: 22px; +} +``` + +### 間距系統 + +#### 標準間距單位 +```css +:root { + --space-1: 4px; /* 超小間距 */ + --space-2: 8px; /* 小間距 */ + --space-3: 12px; /* 中小間距 */ + --space-4: 16px; /* 標準間距 */ + --space-5: 20px; /* 中間距 */ + --space-6: 24px; /* 大間距 */ + --space-8: 32px; /* 超大間距 */ + --space-10: 40px; /* 區塊間距 */ + --space-12: 48px; /* 頁面間距 */ +} +``` + +#### 佈局間距規範 +- [ ] **元件內邊距**: 16px (--space-4) +- [ ] **元件間間距**: 24px (--space-6) +- [ ] **區塊間間距**: 40px (--space-10) +- [ ] **頁面邊距**: 20px (mobile) / 32px (desktop) +- [ ] **列表項目間距**: 12px (--space-3) + +### 圓角和陰影 + +#### 圓角規範 +```css +:root { + --radius-sm: 4px; /* 小元件 */ + --radius-md: 8px; /* 標準元件 */ + --radius-lg: 12px; /* 卡片元件 */ + --radius-xl: 16px; /* 模態視窗 */ + --radius-full: 50%; /* 圓形元素 */ +} +``` + +#### 陰影系統 +```css +:root { + --shadow-sm: 0 1px 2px 0 rgba(0, 0, 0, 0.05); + --shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1); + --shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.1); + --shadow-xl: 0 20px 25px -5px rgba(0, 0, 0, 0.1); +} +``` + +## 元件設計規範 + +### 按鈕組件 + +#### 主要按鈕 (Primary Button) +```css +.btn-primary { + background: var(--primary-blue); + color: white; + padding: 12px 24px; + border-radius: var(--radius-md); + font-weight: 600; + font-size: var(--text-base); + border: none; + cursor: pointer; + transition: all 0.2s ease; +} + +.btn-primary:hover { + background: var(--primary-blue-dark); + transform: translateY(-1px); + box-shadow: var(--shadow-md); +} +``` + +#### 按鈕狀態設計 +- [ ] **正常狀態**: 標準顏色和樣式 +- [ ] **懸停狀態**: 顏色加深，輕微上移效果 +- [ ] **按下狀態**: 顏色更深，無上移效果 +- [ ] **禁用狀態**: 透明度50%，不可點擊 +- [ ] **載入狀態**: 顯示載入動畫 + +#### 按鈕尺寸變體 +- [ ] **大型按鈕**: 48px高度，主要行動按鈕 +- [ ] **標準按鈕**: 40px高度，一般操作按鈕 +- [ ] **小型按鈕**: 32px高度，次要操作按鈕 +- [ ] **迷你按鈕**: 24px高度，標籤或圖示按鈕 + +### 輸入框組件 + +#### 文字輸入框設計 +```css +.input-field { + width: 100%; + padding: 12px 16px; + border: 2px solid var(--divider); + border-radius: var(--radius-md); + font-size: var(--text-base); + transition: border-color 0.2s ease; +} + +.input-field:focus { + outline: none; + border-color: var(--primary-blue); + box-shadow: 0 0 0 3px rgba(33, 150, 243, 0.1); +} +``` + +#### 輸入框狀態 +- [ ] **正常狀態**: 灰色邊框，清楚標示輸入區域 +- [ ] **聚焦狀態**: 藍色邊框，外圍藍色光暈 +- [ ] **錯誤狀態**: 紅色邊框，搭配錯誤訊息 +- [ ] **成功狀態**: 綠色邊框，表示輸入正確 +- [ ] **禁用狀態**: 灰色背景，無法互動 + +### 卡片組件 + +#### 基礎卡片設計 +```css +.card { + background: var(--background-primary); + border-radius: var(--radius-lg); + padding: var(--space-6); + box-shadow: var(--shadow-sm); + border: 1px solid var(--divider); + transition: all 0.2s ease; +} + +.card:hover { + transform: translateY(-2px); + box-shadow: var(--shadow-md); +} +``` + +#### 特殊卡片變體 +- [ ] **場景卡片**: 包含圖片、標題、難度標籤 +- [ ] **成就卡片**: 徽章圖示、成就名稱、進度條 +- [ ] **排行榜卡片**: 排名、用戶頭像、分數 +- [ ] **學習記錄卡片**: 日期、學習時長、完成項目 + +### 導航組件 + +#### 底部導航列 +```css +.bottom-navigation { + position: fixed; + bottom: 0; + left: 0; + right: 0; + background: var(--background-primary); + border-top: 1px solid var(--divider); + display: flex; + justify-content: space-around; + padding: var(--space-2) 0; +} + +.nav-item { + display: flex; + flex-direction: column; + align-items: center; + padding: var(--space-2); + color: var(--text-secondary); + transition: color 0.2s ease; +} + +.nav-item.active { + color: var(--primary-blue); +} +``` + +#### 導航項目設計 +- [ ] **首頁**: 家圖示，學習概覽 +- [ ] **練習**: 對話氣泡圖示，對話練習 +- [ ] **進度**: 圖表圖示，學習進度 +- [ ] **排行榜**: 獎盃圖示，競爭排名 +- [ ] **個人**: 用戶圖示，個人資料 + +## 互動設計規範 + +### 動畫效果 + +#### 頁面轉場動畫 +```css +/* 頁面進入動畫 */ +.page-enter { + animation: slideInRight 0.3s ease-out forwards; +} + +@keyframes slideInRight { + from { + transform: translateX(100%); + opacity: 0; + } + to { + transform: translateX(0); + opacity: 1; + } +} +``` + +#### 互動回饋動畫 +- [ ] **點擊回饋**: 輕微縮放效果 (scale 0.95) +- [ ] **載入動畫**: 旋轉或脈衝效果 +- [ ] **成功動畫**: 綠色勾選圖示彈出 +- [ ] **錯誤動畫**: 紅色搖擺效果 +- [ ] **進度動畫**: 平滑的進度條填充 + +#### 遊戲化動畫 +- [ ] **獲得積分**: 積分數字向上飛出效果 +- [ ] **解鎖成就**: 徽章閃爍和彈出動畫 +- [ ] **等級提升**: 光芒四射的升級特效 +- [ ] **連擊效果**: 連續成功時的視覺強化 +- [ ] **排名變化**: 排名上升或下降的動態效果 + +### 觸控互動 + +#### 手勢支援 +- [ ] **輕觸 (Tap)**: 選擇、確認操作 +- [ ] **長按 (Long Press)**: 顯示詳細資訊或選單 +- [ ] **滑動 (Swipe)**: 頁面導航、項目操作 +- [ ] **雙擊 (Double Tap)**: 快速操作或放大 +- [ ] **捏放 (Pinch)**: 縮放內容 (如文字大小) + +#### 觸控回饋 +- [ ] **視覺回饋**: 觸控時的顏色變化或陰影 +- [ ] **觸覺回饋**: 重要操作提供震動回饋 +- [ ] **音效回饋**: 成功、錯誤、點擊的音效 +- [ ] **狀態回饋**: 清楚顯示操作結果和狀態變化 + +## 響應式設計 + +### 斷點設計 +```css +:root { + /* 響應式斷點 */ + --breakpoint-sm: 640px; /* 小型平板 */ + --breakpoint-md: 768px; /* 平板 */ + --breakpoint-lg: 1024px; /* 小型筆電 */ + --breakpoint-xl: 1280px; /* 桌面 */ +} +``` + +### 設備適配策略 + +#### 手機版 (< 640px) +- [ ] **單欄布局**: 垂直排列所有內容 +- [ ] **大觸控目標**: 最小44x44px觸控區域 +- [ ] **簡化導航**: 隱藏次要功能，突出主要操作 +- [ ] **全螢幕模式**: 充分利用螢幕空間 +- [ ] **拇指友好**: 重要操作放在拇指易達區域 + +#### 平板版 (640px-1024px) +- [ ] **混合布局**: 部分內容可並排顯示 +- [ ] **侧邊導航**: 利用寬螢幕顯示更多導航選項 +- [ ] **多欄內容**: 列表和詳細資訊可同時顯示 +- [ ] **適中字體**: 在可讀性和螢幕利用間平衡 + +#### 桌面版 (> 1024px) +- [ ] **多欄布局**: 充分利用寬螢幕空間 +- [ ] **懸停效果**: 支援滑鼠懸停互動 +- [ ] **快捷鍵**: 提供鍵盤快捷鍵支援 +- [ ] **多工視窗**: 支援多個內容區域同時顯示 + +### 內容適配原則 +- [ ] **內容優先**: 根據內容重要性調整佈局 +- [ ] **漸進增強**: 基礎功能在所有設備可用，進階功能在大螢幕優化 +- [ ] **一致體驗**: 核心功能在各設備保持一致 +- [ ] **效能考量**: 小螢幕設備優化載入速度和流量使用 + +## 可用性設計 + +### 無障礙設計 (Accessibility) + +#### 視覺無障礙 +- [ ] **色彩對比**: 確保文字和背景對比度 ≥ 4.5:1 +- [ ] **色彩獨立**: 重要資訊不僅依賴顏色傳達 +- [ ] **字體大小**: 支援系統字體大小設定 +- [ ] **高對比模式**: 提供高對比度主題選項 +- [ ] **暗黑模式**: 提供護眼的暗色主題 + +#### 操作無障礙 +- [ ] **鍵盤導航**: 所有功能可透過鍵盤操作 +- [ ] **焦點指示**: 清楚的鍵盤焦點視覺指示 +- [ ] **語意標籤**: 正確使用HTML語意標籤 +- [ ] **螢幕閱讀器**: 支援VoiceOver、TalkBack等 +- [ ] **操作時間**: 提供充足的操作反應時間 + +#### 認知無障礙 +- [ ] **簡潔介面**: 避免認知負擔過重的複雜介面 +- [ ] **一致性**: 保持操作和佈局的一致性 +- [ ] **錯誤預防**: 設計防止用戶犯錯的機制 +- [ ] **幫助資訊**: 提供易懂的使用說明和幫助 +- [ ] **進度提示**: 清楚顯示當前位置和進度 + +### 國際化考量 + +#### 多語言支援 +- [ ] **文字長度**: 考量不同語言文字長度差異 +- [ ] **文字方向**: 支援從右到左的語言 (如阿拉伯文) +- [ ] **字體支援**: 確保各語言字體正確顯示 +- [ ] **文化色彩**: 考量不同文化對色彩的認知差異 +- [ ] **符號理解**: 使用全球通用的圖示和符號 + +#### 本地化介面 +- [ ] **日期格式**: 依據地區顯示適當的日期格式 +- [ ] **數字格式**: 支援不同的數字和貨幣格式 +- [ ] **時區處理**: 正確處理不同時區的時間顯示 +- [ ] **節日活動**: 配合當地節日調整介面元素 +- [ ] **法規遵循**: 遵循各地區的法規和標準 + +## 品牌視覺規範 + +### Logo 使用規範 + +#### Logo 變體 +- [ ] **完整Logo**: 包含圖示和文字的完整版本 +- [ ] **圖示版**: 僅包含圖示的簡化版本 +- [ ] **文字版**: 僅包含文字的橫式版本 +- [ ] **單色版**: 單色版本適用於特殊情況 +- [ ] **反白版**: 深色背景使用的反白版本 + +#### Logo 使用規則 +- [ ] **最小尺寸**: Logo最小顯示尺寸24x24px +- [ ] **安全空間**: Logo周圍保持至少等於Logo高度的空白 +- [ ] **背景限制**: 避免在複雜背景上使用Logo +- [ ] **變形禁止**: 不得任意拉伸、旋轉或變形Logo +- [ ] **色彩規範**: 僅使用官方指定的Logo色彩 + +### 圖示系統 + +#### 圖示風格 +- [ ] **線性風格**: 使用2px線寬的線性圖示 +- [ ] **圓角設計**: 圖示轉角使用2px圓角 +- [ ] **一致比例**: 所有圖示使用24x24px網格設計 +- [ ] **視覺重量**: 保持圖示視覺重量的一致性 +- [ ] **識別性**: 確保圖示意義清楚易懂 + +#### 圖示分類 +- [ ] **導航圖示**: 首頁、練習、進度、排行榜、個人 +- [ ] **功能圖示**: 播放、暫停、設定、搜尋、分享 +- [ ] **狀態圖示**: 正確、錯誤、警告、資訊、載入 +- [ ] **遊戲圖示**: 積分、成就、等級、排名、獎勵 +- [ ] **學習圖示**: 詞彙、對話、複習、分析、進度 + +### 插圖風格 + +#### 插圖設計原則 +- [ ] **友善風格**: 使用溫和、友善的插圖風格 +- [ ] **多元包容**: 插圖人物體現多元文化和包容性 +- [ ] **情境相關**: 插圖內容與學習情境密切相關 +- [ ] **色彩和諧**: 插圖色彩與整體設計系統和諧統一 +- [ ] **簡潔明瞭**: 避免過於複雜的插圖設計 + +#### 插圖應用場景 +- [ ] **空狀態**: 無內容時的友善提示插圖 +- [ ] **載入畫面**: 載入過程中的趣味插圖 +- [ ] **成功慶祝**: 完成學習任務的慶祝插圖 +- [ ] **引導教學**: 功能介紹和使用教學插圖 +- [ ] **情境場景**: 對話練習場景的背景插圖 + +--- + +## 設計工具與資源 + +### 設計系統管理 +- [ ] **設計令牌**: 使用設計令牌統一管理設計變數 +- [ ] **組件庫**: 建立可重複使用的UI組件庫 +- [ ] **圖示庫**: 統一管理和更新所有圖示資源 +- [ ] **色彩面板**: 提供設計師和開發者共用的色彩規範 +- [ ] **間距指南**: 視覺化的間距和佈局指南 + +### 原型和測試工具 +- [ ] **原型工具**: 使用Figma或Sketch製作高保真原型 +- [ ] **互動原型**: 製作可點擊的互動原型進行用戶測試 +- [ ] **設計規範**: 自動生成開發者所需的設計規範 +- [ ] **版本控制**: 設計檔案的版本管理和協作機制 +- [ ] **回饋收集**: 設計評審和用戶回饋的收集機制 + +### 效能最佳化 +- [ ] **圖片最佳化**: 使用WebP格式和適當壓縮比例 +- [ ] **字體載入**: 最佳化字體載入策略和fallback機制 +- [ ] **動畫效能**: 使用CSS transform和opacity製作高效動畫 +- [ ] **懶載入**: 圖片和非關鍵內容的懶載入機制 +- [ ] **快取策略**: 靜態資源的快取和更新策略 + +--- + +## 待完成任務 + +### 高優先級 +1. [ ] 完成主要UI組件的詳細設計規範 +2. [ ] 建立完整的設計系統和組件庫 +3. [ ] 製作各個核心頁面的高保真原型 +4. [ ] 進行用戶體驗測試和最佳化 + +### 中優先級 +1. [ ] 設計遊戲化元素的視覺效果和動畫 +2. [ ] 建立多語言介面的本地化設計規範 +3. [ ] 規劃無障礙設計的實施細節 +4. [ ] 設計響應式佈局的各個斷點版本 + +### 低優先級 +1. [ ] 研究最新的UI/UX設計趨勢和最佳實踐 +2. [ ] 探索VR/AR介面設計的可能性 +3. [ ] 建立設計系統的自動化更新機制 +4. [ ] 設計品牌延伸應用的視覺規範 + +--- + +**最後更新**: 2024年9月5日 +**負責人**: 待分配 +**審查週期**: 每兩週檢討一次 \ No newline at end of file diff --git a/docs/03_development/coding-standards.md b/docs/03_development/coding-standards.md new file mode 100644 index 0000000..7acfe8b --- /dev/null +++ b/docs/03_development/coding-standards.md @@ -0,0 +1,993 @@ +# 程式碼規範與開發標準 + +## 概述 +建立統一的程式碼撰寫規範和開發流程標準，確保團隊協作效率和代碼品質。 + +## 通用開發原則 + +### 代碼品質原則 +- [ ] **可讀性優先**: 代碼應該容易閱讀和理解 +- [ ] **一致性**: 遵循統一的命名和格式規範 +- [ ] **簡潔性**: 避免過度複雜的解決方案 +- [ ] **可測試性**: 代碼結構便於單元測試 +- [ ] **可維護性**: 考慮未來修改和擴展的便利性 + +### SOLID原則遵循 +- [ ] **單一職責**: 每個函數/類只負責一個明確的功能 +- [ ] **開放封閉**: 對擴展開放，對修改封閉 +- [ ] **里氏替換**: 子類應該能夠替換父類 +- [ ] **介面隔離**: 不應該依賴不需要的介面 +- [ ] **依賴倒置**: 依賴抽象而非具體實現 + +## C# (.NET Core) 規範 + +### 基本格式規則 + +#### EditorConfig 配置 +```ini +# .editorconfig +root = true + +[*] +charset = utf-8 +end_of_line = crlf +insert_final_newline = true +indent_style = space +indent_size = 4 +trim_trailing_whitespace = true + +[*.{cs,csx,vb,vbx}] +indent_size = 4 +insert_final_newline = true + +[*.{json,js,ts,tsx,css,scss,yml,yaml}] +indent_size = 2 +``` + +#### .NET 分析器規則 +```xml + + + + net8.0 + enable + true + + CS1591 + true + + + + + all + runtime; build; native; contentfiles; analyzers + + + +``` + +### 命名規範 + +#### C# 命名慣例 +```csharp +// ✅ 類別和方法使用PascalCase +public class UserService +{ + public async Task GetUserProfileAsync(Guid userId) + { + // 方法實現 + } + + public decimal CalculateMonthlyInterestRate(decimal principal, decimal rate) + { + return principal * rate / 12; + } +} + +// ✅ 變數和參數使用camelCase +private readonly IUserRepository _userRepository; +private const int MaxRetryAttempts = 3; + +public async Task ValidateUserAsync(string email, string password) +{ + var isValidEmail = IsValidEmailFormat(email); + var hashedPassword = HashPassword(password); + + return isValidEmail && await _userRepository.ValidateCredentialsAsync(email, hashedPassword); +} + +// ❌ 避免的命名 +private string data; // 太泛化 +private int u; // 太簡短 +private async Task GetUserProfileDataAsync() {} // 冗餘的Data後綴 +``` + +#### 常數和列舉 +```typescript +// ✅ 常數使用SCREAMING_SNAKE_CASE +const API_ENDPOINTS = { + USER_PROFILE: '/api/v1/users/profile', + DIALOGUE_START: '/api/v1/dialogues/start', +} as const; + +const MAX_DIALOGUE_DURATION_MINUTES = 30; +const DEFAULT_PAGINATION_LIMIT = 20; + +// ✅ 列舉使用PascalCase +enum DialogueStatus { + InProgress = 'in_progress', + Completed = 'completed', + Abandoned = 'abandoned', +} + +enum UserSubscriptionPlan { + Free = 'free', + Basic = 'basic', + Premium = 'premium', + Professional = 'professional', +} +``` + +#### 類型定義 +```typescript +// ✅ 介面使用PascalCase，以I開頭(可選) +interface UserProfile { + userId: string; + username: string; + email: string; + createdAt: Date; + subscription: UserSubscriptionPlan; +} + +interface ApiResponse { + success: boolean; + data: T | null; + message?: string; + error?: ApiError; +} + +// ✅ 類型別名使用PascalCase +type DialogueAnalysis = { + grammarScore: number; + semanticScore: number; + fluencyScore: number; + overallScore: number; + feedback: string[]; +}; + +type CreateDialogueRequest = { + scenarioId: string; + difficultyOverride?: string; + targetVocabulary?: string[]; +}; +``` + +### 函數撰寫規範 + +#### 函數設計原則 +```typescript +// ✅ 函數應該小巧、單一職責 +const validateEmailFormat = (email: string): boolean => { + const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/; + return emailRegex.test(email); +}; + +const calculateDialogueScore = ( + grammarScore: number, + semanticScore: number, + fluencyScore: number +): number => { + const weights = { grammar: 0.3, semantic: 0.4, fluency: 0.3 }; + + return Math.round( + grammarScore * weights.grammar + + semanticScore * weights.semantic + + fluencyScore * weights.fluency + ); +}; + +// ✅ 使用純函數優於副作用函數 +const createUserSlug = (username: string): string => { + return username + .toLowerCase() + .replace(/[^a-z0-9]/g, '-') + .replace(/-+/g, '-') + .trim(); +}; + +// ✅ 錯誤處理明確 +const fetchUserProfile = async (userId: string): Promise => { + try { + const response = await api.get(`/users/${userId}`); + + if (!response.data) { + throw new Error('User profile not found'); + } + + return response.data; + } catch (error) { + logger.error('Failed to fetch user profile', { userId, error }); + throw error; + } +}; +``` + +#### 異步處理規範 +```typescript +// ✅ 使用async/await而非Promise.then +const processDialogueAnalysis = async ( + dialogueId: string +): Promise => { + const dialogue = await getDialogue(dialogueId); + const analysis = await analyzeDialogueWithAI(dialogue.messages); + const savedAnalysis = await saveAnalysisResults(dialogueId, analysis); + + return savedAnalysis; +}; + +// ✅ 適當的錯誤處理和重試機制 +const retryOperation = async ( + operation: () => Promise, + maxRetries: number = 3, + delayMs: number = 1000 +): Promise => { + for (let attempt = 1; attempt <= maxRetries; attempt++) { + try { + return await operation(); + } catch (error) { + if (attempt === maxRetries) { + throw error; + } + + await new Promise(resolve => setTimeout(resolve, delayMs * attempt)); + } + } + + throw new Error('All retry attempts failed'); +}; +``` + +### React/React Native 組件規範 + +#### 組件結構 +```tsx +// ✅ 組件檔案結構標準 +import React, { useState, useEffect, useCallback } from 'react'; +import { View, Text, StyleSheet } from 'react-native'; + +import { useAppDispatch, useAppSelector } from '@/hooks/redux'; +import { Button } from '@/components/ui'; +import { DialogueService } from '@/services'; +import { updateDialogueProgress } from '@/store/slices/dialogueSlice'; + +import type { Dialogue, DialogueMessage } from '@/types'; + +// ✅ Props介面定義 +interface DialogueChatProps { + dialogueId: string; + onDialogueComplete: (dialogue: Dialogue) => void; + isVisible: boolean; +} + +// ✅ 組件主體 +export const DialogueChat: React.FC = ({ + dialogueId, + onDialogueComplete, + isVisible, +}) => { + // State declarations + const [inputText, setInputText] = useState(''); + const [isLoading, setIsLoading] = useState(false); + + // Redux selectors + const dialogue = useAppSelector(state => + state.dialogue.currentDialogue + ); + const dispatch = useAppDispatch(); + + // Effects + useEffect(() => { + if (isVisible && dialogueId) { + loadDialogue(); + } + }, [isVisible, dialogueId]); + + // Handlers + const handleSendMessage = useCallback(async () => { + if (!inputText.trim()) return; + + setIsLoading(true); + try { + const response = await DialogueService.sendMessage(dialogueId, inputText); + dispatch(updateDialogueProgress(response)); + setInputText(''); + } catch (error) { + // Error handling + } finally { + setIsLoading(false); + } + }, [dialogueId, inputText, dispatch]); + + const loadDialogue = useCallback(async () => { + // Load dialogue logic + }, [dialogueId]); + + // Early returns + if (!dialogue) { + return ; + } + + // Main render + return ( + + {dialogue.scenarioTitle} + {/* Component content */} +