36 KiB
36 KiB
共同數據模型
📋 概述
文檔名稱: 跨平台數據模型定義
建立日期: 2025-09-09
最後更新: 2025-09-11
適用平台: Mobile App / Web App
負責團隊: 後端/數據庫設計
整合共用規範
本數據模型基於以下共用模組，請參閱對應規格文件：
本文檔定義了Drama Ling系統中所有核心數據實體的結構和關係，涵蓋四關線性闖關學習、遊戲化機制、AI智能分析等完整功能體系。
👤 用戶相關數據模型
User - 用戶基本資訊
interface User {
id: string; // UUID用戶唯一標識符
email: string; // 登入用電子郵件
username: string; // 用戶顯示名稱
passwordHash: string; // 密碼雜湊 (bcrypt)
// 個人資料
profile: UserProfile;
// 學習相關
nativeLanguage: string; // 母語 (ISO 639-1)
learningLanguages: string[]; // 學習語言陣列
learningLevel: string; // 整體學習程度
// 系統相關
role: UserRole; // 用戶角色
subscriptionStatus: SubscriptionStatus;
createdAt: Date;
updatedAt: Date;
lastLoginAt: Date;
// 遊戲化數據
gameStats: UserGameStats;
}
interface UserProfile {
firstName?: string;
lastName?: string;
avatar?: string; // 頭像URL
bio?: string; // 個人簡介
timezone: string; // 時區
preferredStudyTime?: string; // 偏好學習時間
}
interface UserGameStats {
totalXP: number; // 總經驗值
currentLevel: number; // 當前等級
diamonds: number; // 鑽石數量 (付費貨幣)
learningCoins: number; // 學習幣數量 (免費貨幣)
lifePoints: number; // 當前命條數
maxLifePoints: number; // 命條上限 (基於用戶等級)
lastLifePointRestore: Date; // 上次命條恢復時間
lifePointRestoreRate: number; // 命條恢復速率(分鐘/點)
// 四關線性闖關統計
totalStagesCompleted: number; // 總完成關卡數 (跨所有劇本)
totalScriptsUnlocked: number; // 已解鎖劇本數量
currentScript: string; // 當前進行中的劇本ID
// 詳細學習統計
totalStudyDays: number; // 總學習天數
consecutiveStudyDays: number; // 連續學習天數
totalWordsLearned: number; // 總學習詞彙數
totalDialoguesCompleted: number; // 總完成對話數
totalSpeakingPractices: number; // 總口說練習次數
// 四關詳細統計
stage1Completions: number; // 第1關完成次數
stage2Completions: number; // 第2關完成次數
stage2PlusCompletions: number; // 第2+關完成次數
stage3Completions: number; // 第3關完成次數
// 付費相關統計
totalDiamondsSpent: number; // 總消費鑽石數
speakingPracticeRevenue: number; // 口說練習收益
// 成就數據
achievements: Achievement[];
favoriteWords: string[]; // 收藏詞彙ID陣列
}
UserProgress - 用戶學習進度 (四關線性闖關系統)
interface UserProgress {
id: string;
userId: string;
// 整體進度
overallProgress: number; // 0-100 整體學習進度
currentScript: string; // 當前劇本ID
currentStage: number; // 當前關卡 (1-3)
// 四關線性闖關進度
scriptProgress: ScriptProgress[]; // 各劇本四關進度
// 各技能進度 (整合四關數據)
vocabularyProgress: SkillProgress;
dialogueProgress: SkillProgress;
pronunciationProgress: SkillProgress;
grammarProgress: SkillProgress;
// 學習路徑 (基於四關系統)
completedScripts: string[]; // 已完成劇本ID陣列
unlockedScripts: string[]; // 已解鎖劇本ID陣列
// 複習數據 (整合四關學習內容)
reviewQueue: ReviewItem[]; // 複習佇列
updatedAt: Date;
}
// 劇本四關進度追蹤
interface ScriptProgress {
scriptId: string; // 劇本ID
title: string; // 劇本標題
// 四關完成狀態
stage1: StageProgress; // 第1關：詞彙學習
stage2: StageProgress; // 第2關：詞彙熟悉
stage2Plus: StagePlusProgress; // 第2+關：口說練習 (付費)
stage3: StageProgress; // 第3關：情境對話
// 整體劇本狀態
isCompleted: boolean; // 是否完成整個劇本
completedAt?: Date; // 完成時間
totalAttempts: number; // 總嘗試次數
bestScore: number; // 最佳成績
// 學習詞彙
targetVocabulary: string[]; // 5個目標詞彙ID
masteredVocabulary: string[]; // 已掌握詞彙ID
lastPlayedAt: Date;
}
// 標準關卡進度
interface StageProgress {
isUnlocked: boolean; // 是否解鎖
isCompleted: boolean; // 是否完成
attempts: number; // 嘗試次數
bestScore: number; // 最佳分數 (0-100)
stars: number; // 星級評價 (1-3)
completedAt?: Date; // 完成時間
avgResponseTime: number; // 平均回應時間(秒)
hintsUsed: number; // 使用提示次數
}
// 第2+關付費口說練習進度
interface StagePlusProgress extends StageProgress {
diamondsSpent: number; // 消費鑽石數
diamondsEarned: number; // 獲得鑽石數
netRevenue: number; // 淨收益
speakingScores: SpeakingScore[]; // 歷史口說評分
}
// 五維口說評分記錄
interface SpeakingScore {
overall: number; // 總體分數
pronunciation: number; // 發音分數
fluency: number; // 流暢度分數
rhythm: number; // 韻律分數
completeness: number; // 完整度分數
accuracy: number; // 準確度分數
timestamp: Date;
}
interface SkillProgress {
level: number; // 技能等級 1-10
xp: number; // 該技能經驗值
accuracy: number; // 準確率 0-100
fluency: number; // 流暢度 0-100
lastPracticed: Date; // 上次練習時間
}
interface ReviewItem {
contentId: string; // 內容ID (詞彙/對話等)
contentType: 'vocabulary' | 'dialogue' | 'grammar' | 'speaking';
sourceScript: string; // 來源劇本ID
sourceStage: number; // 來源關卡 (1-3)
// 複習排程 (基於遺忘曲線)
nextReviewAt: Date; // 下次複習時間
reviewCount: number; // 已複習次數
difficulty: number; // 當前難度 1-5
masteryLevel: number; // 掌握程度 0-100
// 複習表現追蹤
lastReviewScore: number; // 上次複習分數
averageScore: number; // 平均複習分數
consecutiveCorrect: number; // 連續正確次數
// 間隔複習算法參數
easinessFactor: number; // 簡易因子 (1.3-2.5)
interval: number; // 複習間隔(天)
repetitions: number; // 重複次數
createdAt: Date;
updatedAt: Date;
}
📚 學習內容數據模型 (四關線性闖關系統)
Script - 劇本數據 (四關學習單元)
interface Script {
id: string;
title: string; // 劇本標題
description: string; // 劇本描述
// 情境設定
scenario: ScriptScenario;
// 四關學習內容
targetVocabulary: Vocabulary[]; // 5個目標詞彙
stage1Content: Stage1Content; // 第1關：詞彙學習內容
stage2Content: Stage2Content; // 第2關：詞彙熟悉內容
stage2PlusContent: Stage2PlusContent; // 第2+關：口說練習內容
stage3Content: Stage3Content; // 第3關：情境對話內容
// 解鎖條件和順序
unlockRequirements: string[]; // 前置劇本要求
orderIndex: number; // 劇本順序
isHidden: boolean; // 是否為隱藏劇本
// 元數據
difficulty: number; // 整體難度等級 1-5
estimatedDuration: number; // 預估完成時間(分鐘)
tags: string[]; // 標籤
// 統計數據
completionCount: number; // 完成人數統計
averageScore: number; // 平均分數
averageCompletionTime: number; // 平均完成時間
createdAt: Date;
updatedAt: Date;
}
interface ScriptScenario {
setting: string; // 場景設定
situation: string; // 具體情況
culturalContext?: string; // 文化背景
illustrationUrl?: string; // 情境插圖
backgroundMusicUrl?: string; // 背景音樂
}
// 第1關：詞彙學習內容
interface Stage1Content {
vocabularyItems: VocabularyLearningItem[]; // 5個詞彙學習項目
passingScore: number; // 通關分數 (預設70)
timeLimit?: number; // 時間限制(秒)
questionsPerWord: number; // 每個詞彙的題目數 (預設1)
}
interface VocabularyLearningItem {
vocabularyId: string; // 詞彙ID
questionType: 'multiple_choice' | 'fill_blank' | 'matching';
question: string; // 題目內容
options: string[]; // 選項 (4選1)
correctAnswer: number; // 正確答案索引
explanation: string; // 解題說明
}
// 第2關：詞彙熟悉內容
interface Stage2Content {
reconstructionExercises: SentenceReconstruction[]; // 例句重組
matchingExercises: VocabularyMatching[]; // 詞彙配對
passingScore: number; // 通關分數 (預設80)
}
interface SentenceReconstruction {
targetSentence: string; // 目標句子
translation: string; // 中文翻譯
wordPool: string[]; // 單字池
hints?: string[]; // 提示信息
}
interface VocabularyMatching {
items: MatchingPair[]; // 配對項目
shuffled: boolean; // 是否隨機排序
}
interface MatchingPair {
vocabularyId: string; // 詞彙ID
imageUrl: string; // 對應圖片
description: string; // 圖片描述
}
// 第2+關：口說練習內容 (付費)
interface Stage2PlusContent {
speakingExercises: SpeakingExercise[]; // 口說練習項目
costInDiamonds: number; // 消費鑽石數 (預設5)
passingScore: number; // 通關分數 (預設70)
rewardTiers: RewardTier[]; // 獎勵階梯
}
interface SpeakingExercise {
vocabularyId: string; // 詞彙ID
promptText: string; // 提示文字
exampleSentence: string; // 例句
expectedDuration: number; // 預期錄音時長(秒)
evaluationCriteria: string[]; // 評估標準
}
interface RewardTier {
minScore: number; // 最低分數
diamondReward: number; // 鑽石獎勵
xpReward: number; // 經驗值獎勵
}
// 第3關：情境對話內容
interface Stage3Content {
dialogue: Dialogue; // 對話內容
taskRequirements: DialogueTask[]; // 雙重任務要求
evaluationCriteria: EvaluationCriteria; // 三星評分標準
timeLimit: number; // 時間限制 (預設300秒)
}
interface DialogueTask {
type: 'intent_completion' | 'vocabulary_usage';
description: string; // 任務描述
requirements: any; // 具體要求
weight: number; // 權重 (0-1)
}
interface EvaluationCriteria {
taskStar: TaskStarCriteria; // ⭐ 任務星標準
grammarStar: GrammarStarCriteria; // ⭐ 語法星標準
speakingStar: SpeakingStarCriteria; // ⭐ 口說星標準
}
### Vocabulary - 詞彙數據 (增強版多媒體詞彙學習)
```typescript
interface Vocabulary {
id: string;
word: string; // 詞彙本體 (原形)
language: string; // 語言代碼
// 詞彙基本資訊
level: string; // CEFR等級 (A1/A2/B1/B2/C1/C2)
phonetic: string; // IPA音標 (如 "/ˌrek.əˈmend/")
partOfSpeech: string; // 詞性
difficulty: number; // 難度等級 1-5
frequency: number; // 使用頻率評分
wordType: 'word' | 'phrase' | 'idiom'; // 詞彙類型
// 多媒體詞彙學習數據結構 (基於增強版原型)
definition: string; // 英文定義 (主要定義)
originalSentence: string; // Source句子 (學習者遇到的真實語境)
originalHighlight: string; // Source句子中要標註的詞 (支援變形)
exampleSentence: string; // Example句子 (教學例句)
exampleHighlight: string; // Example句子中要標註的詞 (支援變形)
// 音頻系統 (支援多種音頻)
audioFiles: VocabularyAudioFiles;
// 視覺輔助 (例句配圖)
imageUrl?: string; // Example句子配圖URL
imageDescription?: string; // 圖片描述
// 傳統釋義系統 (向下相容)
definitions: Definition[];
examples: Example[];
// 視覺學習輔助 (傳統)
illustrationUrl?: string; // 示意圖URL
illustrationEmoji?: string; // 表情符號表示
// 分類
categories: string[]; // 詞彙分類標籤
topics: string[]; // 相關主題
// 關聯
synonyms: string[]; // 同義詞ID陣列
antonyms: string[]; // 反義詞ID陣列
relatedWords: string[]; // 相關詞彙ID陣列
// 四關系統整合
appearsInScripts: string[]; // 出現在哪些劇本中
learningOrder: number; // 在劇本中的學習順序 (1-5)
masteryCount: number; // 被掌握的用戶數量
favoriteCount: number; // 被收藏的次數
// 學習統計 (基於增強版使用數據)
viewCount: number; // 被瀏覽次數
audioPlayCount: number; // 音頻播放次數
averageViewTime: number; // 平均瀏覽時間(秒)
createdAt: Date;
updatedAt: Date;
}
// 詞彙音頻文件結構 (增強版多媒體支援)
interface VocabularyAudioFiles {
normal: string; // 詞彙正常速度音檔URL
slow: string; // 詞彙慢速音檔URL
example: string; // Example句子音檔URL
// 注意: 不包含original (Source句子音檔)，因為Source不提供音頻
}
interface Definition {
id: string;
definition: string; // 定義文字
language: string; // 定義語言
context?: string; // 使用情境
formality?: 'formal' | 'informal' | 'neutral';
}
interface Example {
id: string;
sentence: string; // 例句
translation?: string; // 翻譯
audioUrl?: string; // 例句音頻
context?: string; // 使用情境
}
Dialogue - 對話內容
interface Dialogue {
id: string;
title: string; // 對話標題
description: string; // 對話描述
// 情境設定
scenario: DialogueScenario;
// 對話內容
messages: DialogueMessage[];
// 學習目標
learningObjectives: string[]; // 學習目標陣列
targetVocabulary: string[]; // 目標詞彙ID陣列
grammarPoints: string[]; // 語法重點
// 元數據
difficulty: number; // 難度等級
estimatedDuration: number; // 預估完成時間(分鐘)
tags: string[]; // 標籤
createdAt: Date;
updatedAt: Date;
}
interface DialogueScenario {
setting: string; // 場景設定
characters: Character[]; // 角色資訊
culturalContext?: string; // 文化背景
situation: string; // 具體情況
}
interface Character {
id: string;
name: string;
role: string; // 角色定位
personality: string; // 性格特點
background: string; // 背景設定
avatarUrl?: string; // 角色頭像
}
interface DialogueMessage {
id: string;
characterId: string; // 說話角色ID
content: string; // 對話內容
translation?: string; // 翻譯
audioUrl?: string; // 語音檔URL
// AI分析數據
intent?: string; // 對話意圖
emotion?: string; // 情感色彩
formalityLevel?: string; // 正式程度
// 學習提示
hints?: string[]; // 提示信息
alternatives?: string[]; // 替代回答
}
🎯 學習活動數據模型 (四關線性闖關系統)
StudySession - 學習會話 (整合四關數據)
interface StudySession {
id: string;
userId: string;
// 四關會話資訊
type: 'stage1' | 'stage2' | 'stage2plus' | 'stage3' | 'review' | 'challenge';
scriptId: string; // 劇本ID
stage: number; // 關卡編號 (1-3, 2+ 表示為 2.5)
contentId: string; // 學習內容ID
// 時間追蹤
startTime: Date;
endTime?: Date;
duration?: number; // 實際學習時長(秒)
// 四關學習結果
completed: boolean;
score: number; // 得分 0-100
accuracy: number; // 準確率 0-100
stars: number; // 星級評價 (1-3)
// 詳細活動數據
activities: ActivityResult[];
// 四關特定數據
stage1Data?: Stage1SessionData; // 第1關特定數據
stage2Data?: Stage2SessionData; // 第2關特定數據
stage2PlusData?: Stage2PlusSessionData; // 第2+關特定數據
stage3Data?: Stage3SessionData; // 第3關特定數據
// 獎勵系統
xpGained: number;
diamondsGained: number; // 可為負數 (第2+關消費)
achievementsUnlocked: string[];
// 輔助使用記錄
hintsUsed: number;
timeExtensionsUsed: number;
itemsUsed: ItemUsage[]; // 使用的道具記錄
createdAt: Date;
}
// 第1關會話特定數據
interface Stage1SessionData {
vocabularyResults: VocabularyResult[]; // 5個詞彙的結果
totalQuestions: number; // 總題目數
correctAnswers: number; // 正確答案數
averageResponseTime: number; // 平均回答時間
favoriteWordsAdded: string[]; // 新增收藏的詞彙
}
interface VocabularyResult {
vocabularyId: string;
isCorrect: boolean;
responseTime: number;
hintsUsed: number;
attempts: number;
}
// 第2關會話特定數據
interface Stage2SessionData {
reconstructionResults: ReconstructionResult[]; // 例句重組結果
matchingResults: MatchingResult[]; // 配對結果
totalReconstructionTime: number; // 重組總時間
totalMatchingTime: number; // 配對總時間
dragDropAccuracy: number; // 拖拽準確率
}
interface ReconstructionResult {
sentenceId: string;
completed: boolean;
attempts: number;
timeSpent: number;
wordOrder: string[]; // 用戶的單字順序
}
interface MatchingResult {
correctMatches: number;
totalMatches: number;
mistakes: MatchingMistake[];
}
interface MatchingMistake {
vocabularyId: string;
userSelection: string; // 用戶選擇的配對
correctSelection: string; // 正確配對
}
// 第2+關會話特定數據 (付費口說練習)
interface Stage2PlusSessionData {
diamondsSpent: number; // 消費鑽石
speakingResults: SpeakingResult[]; // 每個詞彙的口說結果
overallSpeakingScore: number; // 整體口說分數
diamondReward: number; // 獲得的鑽石獎勵
netDiamondChange: number; // 淨鑽石變化
aiPronunciationFeedback: string[]; // AI發音反饋
}
interface SpeakingResult {
vocabularyId: string;
audioFileUrl: string; // 錄音檔URL
speakingScore: SpeakingScore; // 五維口說評分
attempts: number;
durationSeconds: number;
transcription?: string; // 語音辨識結果
}
// 第3關會話特定數據 (情境對話)
interface Stage3SessionData {
dialogueMessages: DialogueMessage[]; // 對話訊息記錄
taskCompletionStatus: TaskCompletion[]; // 雙重任務完成狀態
threeStarEvaluation: ThreeStarEvaluation; // 三星評分結果
vocabularyUsage: VocabularyUsage[]; // 詞彙使用情況
aiGrammarFeedback: string[]; // AI語法反饋
aiPragmaticFeedback: string[]; // AI語用反饋
totalTurns: number; // 對話回合數
timeRemaining: number; // 剩餘時間
}
interface TaskCompletion {
taskType: 'intent_completion' | 'vocabulary_usage';
completed: boolean;
completionRate: number; // 完成度 0-100
evidence: string[]; // 完成證據
}
interface ThreeStarEvaluation {
taskStar: boolean; // ⭐ 任務星
grammarStar: boolean; // ⭐ 語法星
speakingStar: boolean; // ⭐ 口說星
taskStarScore: number; // 任務完成分數
grammarStarScore: number; // 語法分數
speakingStarScore: number; // 口說分數
}
interface VocabularyUsage {
vocabularyId: string;
used: boolean;
usageContext: string; // 使用情境
appropriateness: number; // 使用適切性 0-100
}
// 道具使用記錄
interface ItemUsage {
itemId: string;
itemName: string;
quantityUsed: number;
useTimestamp: Date;
effectDescription: string;
}
interface ActivityResult {
id: string;
type: 'choice_question' | 'matching' | 'dialogue_turn' | 'pronunciation';
contentId: string;
// 回答數據
userAnswer: any; // 用戶回答
correctAnswer: any; // 正確答案
isCorrect: boolean;
responseTime: number; // 回答時間(秒)
// 分析數據
difficulty: number; // 題目難度
hintUsed: boolean; // 是否使用提示
skipCount: number; // 跳過次數
timestamp: Date;
}
UserAnswer - 用戶回答記錄
interface UserAnswer {
id: string;
userId: string;
sessionId: string;
// 問題資訊
questionId: string;
questionType: string;
content: any; // 問題內容
// 回答資訊
answer: any; // 用戶回答
isCorrect: boolean;
responseTime: number; // 回答時間(毫秒)
attempts: number; // 嘗試次數
// 輔助使用
hintsUsed: number; // 使用提示次數
timeExtensions: number; // 延時次數
// AI評估 (針對開放性回答)
aiScore?: number; // AI評分 0-100
feedback?: string; // AI反饋
createdAt: Date;
}
🏆 遊戲化數據模型
Achievement - 成就系統
interface Achievement {
id: string;
name: string; // 成就名稱
description: string; // 成就描述
category: AchievementCategory;
// 達成條件
requirements: AchievementRequirement[];
// 獎勵
rewards: Reward[];
// 元數據
iconUrl: string; // 成就圖標
rarity: 'common' | 'rare' | 'epic' | 'legendary';
isHidden: boolean; // 是否為隱藏成就
createdAt: Date;
}
interface AchievementRequirement {
type: string; // 要求類型
target: number; // 目標數值
description: string; // 要求描述
}
interface Reward {
type: 'xp' | 'diamonds' | 'title' | 'avatar' | 'theme';
amount?: number; // 數量 (針對XP/鑽石)
itemId?: string; // 物品ID (針對稱號/頭像/主題)
}
interface UserAchievement {
id: string;
userId: string;
achievementId: string;
progress: number; // 進度 0-100
completed: boolean;
completedAt?: Date;
createdAt: Date;
updatedAt: Date;
}
Item - 道具/物品系統 (整合四關和命條系統)
interface Item {
id: string;
name: string;
description: string;
category: ItemCategory;
// 效果 (整合四關系統)
effects: ItemEffect[];
// 購買/使用
price: Price[]; // 多種貨幣價格
consumable: boolean; // 是否為消耗品
stackable: boolean; // 是否可堆疊
maxStack?: number; // 最大堆疊數量
// 四關系統適用性
applicableStages: number[]; // 適用關卡 [1, 2, 3]
effectiveness: StageEffectiveness; // 各關卡效果
// 元數據
iconUrl: string;
iconEmoji?: string; // 表情符號圖示
rarity: ItemRarity;
// 購買限制
dailyLimit?: number; // 每日購買限制
requiresSubscription: boolean;
// 統計數據
purchaseCount: number; // 購買次數統計
usageCount: number; // 使用次數統計
createdAt: Date;
updatedAt: Date;
}
interface ItemEffect {
type: ItemEffectType;
value: number; // 效果數值
duration?: number; // 持續時間(秒)
description: string; // 效果描述
}
type ItemEffectType =
| 'restore_life' // 恢復命條
| 'double_xp' // 雙倍經驗
| 'skip_question' // 跳過題目
| 'extra_hint' // 額外提示
| 'slow_audio' // 慢速音頻
| 'extend_time' // 延長時間
| 'auto_correct' // 自動糾錯
| 'vocabulary_hint' // 詞彙提示
| 'dialogue_suggestion' // 對話建議
| 'speaking_retry' // 口說重試
| 'star_guarantee' // 星級保證
| 'diamond_multiplier'; // 鑽石倍增
interface StageEffectiveness {
stage1: number; // 第1關效果 (0-1)
stage2: number; // 第2關效果 (0-1)
stage2Plus: number; // 第2+關效果 (0-1)
stage3: number; // 第3關效果 (0-1)
}
interface Price {
currency: 'diamonds' | 'learning_coins' | 'real_money';
amount: number;
}
// 道具分類
type ItemCategory =
| 'life_management' // 命條管理
| 'learning_boost' // 學習增強
| 'stage_assistance' // 關卡輔助
| 'speaking_tools' // 口說工具
| 'dialogue_helpers' // 對話幫手
| 'premium_features' // 進階功能
| 'cosmetic'; // 裝飾道具
type ItemRarity = 'common' | 'uncommon' | 'rare' | 'epic' | 'legendary';
// 預定義道具範例
const PREDEFINED_ITEMS: Partial<Item>[] = [
{
id: 'life_potion',
name: '命條藥水',
description: '立即恢復1個命條',
category: 'life_management',
effects: [{ type: 'restore_life', value: 1, description: '恢復1個命條' }],
price: [{ currency: 'diamonds', amount: 2 }],
rarity: 'common',
applicableStages: [1, 2, 3],
iconEmoji: '❤️🩹'
},
{
id: 'xp_doubler',
name: '經驗雙倍卡',
description: '接下來60分鐘內獲得雙倍經驗值',
category: 'learning_boost',
effects: [{ type: 'double_xp', value: 2, duration: 3600, description: '雙倍經驗值持續60分鐘' }],
price: [{ currency: 'diamonds', amount: 5 }],
rarity: 'uncommon',
applicableStages: [1, 2, 3],
iconEmoji: '⭐'
},
{
id: 'vocabulary_hint_card',
name: '詞彙提示卡',
description: '在第1關或第2關中獲得額外的詞彙提示',
category: 'stage_assistance',
effects: [{ type: 'vocabulary_hint', value: 3, description: '提供3次額外詞彙提示' }],
price: [{ currency: 'learning_coins', amount: 50 }],
rarity: 'common',
applicableStages: [1, 2],
iconEmoji: '💡'
},
{
id: 'speaking_retry_token',
name: '口說重試幣',
description: '在第2+關口說練習中免費重新錄音',
category: 'speaking_tools',
effects: [{ type: 'speaking_retry', value: 1, description: '免費重新錄音1次' }],
price: [{ currency: 'diamonds', amount: 1 }],
rarity: 'common',
applicableStages: [2.5], // 第2+關
iconEmoji: '🎤'
},
{
id: 'dialogue_suggestion_orb',
name: '對話建議球',
description: '在第3關中獲得AI智能回覆建議',
category: 'dialogue_helpers',
effects: [{ type: 'dialogue_suggestion', value: 5, description: '提供5次AI對話建議' }],
price: [{ currency: 'diamonds', amount: 3 }],
rarity: 'rare',
applicableStages: [3],
iconEmoji: '🔮'
},
{
id: 'time_warp_scroll',
name: '時光卷軸',
description: '在第3關限時對話中延長60秒',
category: 'stage_assistance',
effects: [{ type: 'extend_time', value: 60, description: '延長時間60秒' }],
price: [{ currency: 'diamonds', amount: 4 }],
rarity: 'uncommon',
applicableStages: [3],
iconEmoji: '⏰'
}
];
interface UserInventory {
id: string;
userId: string;
itemId: string;
quantity: number;
// 使用記錄
totalUsed: number;
lastUsed?: Date;
createdAt: Date;
updatedAt: Date;
}
📊 分析數據模型
LearningAnalytics - 學習分析 (四關系統數據)
interface LearningAnalytics {
id: string;
userId: string;
date: Date; // 分析日期
// 四關學習時間分析
totalStudyTime: number; // 總學習時間(分鐘)
sessionCount: number; // 學習會話數
averageSessionLength: number; // 平均會話時長
// 四關分布時間
stage1Time: number; // 第1關學習時間
stage2Time: number; // 第2關學習時間
stage2PlusTime: number; // 第2+關學習時間
stage3Time: number; // 第3關學習時間
// 四關學習效果分析
scriptsAttempted: number; // 嘗試劇本數
scriptsCompleted: number; // 完成劇本數
overallAccuracy: number; // 整體準確率
// 各關卡表現
stage1Performance: StagePerformance;
stage2Performance: StagePerformance;
stage2PlusPerformance: StagePlusPerformance;
stage3Performance: StagePerformance;
// 學習模式分析
preferredStudyTime: string; // 偏好學習時段
mostActiveHour: number; // 最活躍小時
learningStreak: number; // 連續學習天數
preferredStage: number; // 偏好關卡
// 困難分析 (基於四關數據)
difficultVocabulary: string[]; // 困難詞彙ID陣列
difficultScripts: string[]; // 困難劇本ID陣列
weakStages: number[]; // 薄弱關卡
improvementSuggestions: string[]; // 改進建議
// 付費分析
diamondsSpent: number; // 當日鑽石消費
diamondsEarned: number; // 當日鑽石收益
speakingPracticeROI: number; // 口說練習投資報酬率
createdAt: Date;
}
interface StagePerformance {
attempts: number; // 嘗試次數
completions: number; // 完成次數
averageScore: number; // 平均分數
averageTime: number; // 平均完成時間
accuracy: number; // 準確率
hintsUsed: number; // 使用提示次數
improvementRate: number; // 改善幅度
}
interface StagePlusPerformance extends StagePerformance {
totalSpent: number; // 總消費鑽石
totalEarned: number; // 總獲得鑽石
netRevenue: number; // 淨收益
averageSpeakingScore: number; // 平均口說分數
speakingImprovement: number; // 口說進步幅度
}
interface SystemMetrics {
id: string;
date: Date;
// 用戶活躍度
activeUsers: number;
newUsers: number;
returningUsers: number;
// 學習數據
totalSessions: number;
averageSessionLength: number;
completionRate: number;
// 內容熱門度
popularDialogues: string[];
popularVocabulary: string[];
// 系統效能
averageResponseTime: number;
errorRate: number;
createdAt: Date;
}
🔗 數據關係定義 (四關線性闖關系統)
主要實體關係
User (1) ←→ (1) UserProgress
User (1) ←→ (*) StudySession
User (1) ←→ (*) UserAnswer
User (1) ←→ (*) UserAchievement
User (1) ←→ (*) UserInventory
Script (1) ←→ (*) StudySession // 劇本與學習會話
Script (1) ←→ (5) Vocabulary // 劇本包含5個目標詞彙
Script (1) ←→ (*) ScriptProgress // 劇本進度追蹤
UserProgress (1) ←→ (*) ScriptProgress // 用戶進度包含多個劇本進度
UserProgress (1) ←→ (*) ReviewItem // 複習項目關聯
Vocabulary (1) ←→ (*) UserAnswer // 詞彙與用戶回答
Dialogue (1) ←→ (*) StudySession // 對話與學習會話
Achievement (1) ←→ (*) UserAchievement // 成就與用戶成就
Item (1) ←→ (*) UserInventory // 道具與用戶庫存
StudySession (1) ←→ (*) ActivityResult // 會話與活動結果
StudySession (1) ←→ (*) UserAnswer // 會話與用戶回答
StudySession (1) ←→ (*) ItemUsage // 會話與道具使用
LearningAnalytics (1) ←→ (1) User // 學習分析與用戶
四關系統特定關係
Script (1) ←→ (1) Stage1Content // 第1關內容
Script (1) ←→ (1) Stage2Content // 第2關內容
Script (1) ←→ (1) Stage2PlusContent // 第2+關內容
Script (1) ←→ (1) Stage3Content // 第3關內容
ScriptProgress (1) ←→ (4) StageProgress // 劇本進度包含四關進度
StudySession ←→ Stage1SessionData // 第1關會話數據
StudySession ←→ Stage2SessionData // 第2關會話數據
StudySession ←→ Stage2PlusSessionData // 第2+關會話數據
StudySession ←→ Stage3SessionData // 第3關會話數據
索引策略 (優化四關查詢)
-- 用戶相關索引
CREATE INDEX idx_user_email ON users(email);
CREATE INDEX idx_user_role ON users(role);
CREATE INDEX idx_user_subscription ON users(subscription_status);
CREATE INDEX idx_user_current_script ON users(current_script);
-- 四關系統索引
CREATE INDEX idx_script_order ON scripts(order_index);
CREATE INDEX idx_script_difficulty ON scripts(difficulty);
CREATE INDEX idx_script_progress_user_script ON script_progress(user_id, script_id);
CREATE INDEX idx_script_progress_stage ON script_progress(user_id, current_stage);
-- 學習數據索引 (優化四關查詢)
CREATE INDEX idx_study_session_user_script_stage ON study_sessions(user_id, script_id, stage);
CREATE INDEX idx_study_session_type_date ON study_sessions(type, start_time);
CREATE INDEX idx_user_answer_session ON user_answers(session_id);
CREATE INDEX idx_user_progress_user ON user_progress(user_id);
-- 內容相關索引
CREATE INDEX idx_vocabulary_script ON vocabulary(appears_in_scripts);
CREATE INDEX idx_vocabulary_learning_order ON vocabulary(learning_order);
CREATE INDEX idx_vocabulary_language_difficulty ON vocabulary(language, difficulty);
-- 複習系統索引
CREATE INDEX idx_review_item_user_next_review ON review_items(user_id, next_review_at);
CREATE INDEX idx_review_item_source ON review_items(source_script, source_stage);
-- 道具系統索引
CREATE INDEX idx_item_category_rarity ON items(category, rarity);
CREATE INDEX idx_item_applicable_stages ON items(applicable_stages);
CREATE INDEX idx_user_inventory_user_item ON user_inventory(user_id, item_id);
-- 分析數據索引
CREATE INDEX idx_learning_analytics_user_date ON learning_analytics(user_id, date);
CREATE INDEX idx_learning_analytics_date ON learning_analytics(date);
-- 效能優化組合索引
CREATE INDEX idx_session_user_script_stage_date ON study_sessions(user_id, script_id, stage, start_time);
CREATE INDEX idx_progress_completion ON script_progress(user_id, is_completed, completed_at);
📊 數據模型變更記錄
v2.0 更新內容 (2025-09-11)
- ✅ 整合四關線性闖關系統: 新增 Script、ScriptProgress、Stage*Content 數據模型
- ✅ 增強用戶遊戲化數據: 擴展 UserGameStats，增加四關統計和付費數據追蹤
- ✅ 完善學習會話模型: StudySession 支援四關特定數據，增加各關卡詳細記錄
- ✅ 優化復習系統: ReviewItem 整合遺忘曲線算法和四關來源追蹤
- ✅ 升級道具系統: Item 支援四關適用性和效果分級，新增預定義道具
- ✅ 強化分析數據: LearningAnalytics 增加四關表現分析和付費行為追蹤
- ✅ 完善數據關係: 建立四關系統完整的實體關係和索引策略
v2.0 技術改進
- 🎯 四關特定數據結構: 每個關卡都有專門的數據模型和會話記錄
- 💰 付費機制整合: 完整的鑽石經濟和第2+關付費數據追蹤
- 🔄 複習系統升級: 基於SM-2算法的間隔複習參數和表現追蹤
- 📊 分析維度擴展: 四關維度的學習分析和用戶行為洞察
- 🛡️ 索引優化: 針對四關查詢模式的數據庫索引策略
文檔狀態: 🟢 已完成 (v2.0 - 整合四關線性闖關系統)
建立日期: 2025-09-09
最後更新: 2025-09-11
版本: v2.0
更新者: Claude Code Assistant
相關文檔:
progressive-stage-system.md- 線性闖關學習系統規格ai-algorithm-specs.md- AI算法規格speaking-evaluation-specs.md- 口說評分系統規格pragmatic-analysis-specs.md- 語用分析系統規格business-rules.md- 共同業務規則api-specifications.md- API接口定義../mobile/- 移動端功能規格../web/- Web端功能規格
開發注意事項:
- 數據庫遷移腳本需同步更新所有新增字段和索引
- API層需要支援四關數據的CRUD操作
- 前端需要適配新的數據結構和關係
- 分析服務需要重新設計以支援四關維度統計