1117 lines
35 KiB
Markdown
1117 lines
35 KiB
Markdown
# 共同數據模型
|
||
|
||
## 📋 概述
|
||
|
||
**文檔名稱**: 跨平台數據模型定義
|
||
**建立日期**: 2025-09-09
|
||
**最後更新**: 2025-09-11
|
||
**適用平台**: Mobile App / Web App
|
||
**負責團隊**: 後端/數據庫設計
|
||
|
||
### 整合共用規範
|
||
> 本數據模型基於以下共用模組，請參閱對應規格文件：
|
||
> - **[線性闖關學習系統](progressive-stage-system.md)** - 四關闖關機制數據結構
|
||
> - **[AI算法規格](ai-algorithm-specs.md)** - AI學習支援系統數據
|
||
> - **[口說評分系統](speaking-evaluation-specs.md)** - 五維口說評分數據
|
||
> - **[語用分析系統](pragmatic-analysis-specs.md)** - 六維語用分析數據
|
||
> - **[共同業務規則](business-rules.md)** - 命條系統和道具商店數據
|
||
|
||
本文檔定義了Drama Ling系統中所有核心數據實體的結構和關係，涵蓋四關線性闖關學習、遊戲化機制、AI智能分析等完整功能體系。
|
||
|
||
## 👤 用戶相關數據模型
|
||
|
||
### User - 用戶基本資訊
|
||
```typescript
|
||
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 - 用戶學習進度 (四關線性闖關系統)
|
||
```typescript
|
||
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 - 劇本數據 (四關學習單元)
|
||
```typescript
|
||
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; // 語言代碼
|
||
|
||
// 詞彙資訊
|
||
pronunciation: string; // IPA音標
|
||
partOfSpeech: string; // 詞性
|
||
difficulty: number; // 難度等級 1-5
|
||
frequency: number; // 使用頻率評分
|
||
wordType: 'word' | 'phrase' | 'idiom'; // 詞彙類型
|
||
|
||
// 釋義
|
||
definitions: Definition[];
|
||
examples: Example[];
|
||
|
||
// 音頻
|
||
audioUrl: string; // 標準發音音頻URL
|
||
slowAudioUrl?: string; // 慢速發音音頻URL
|
||
|
||
// 視覺學習輔助
|
||
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; // 被收藏的次數
|
||
|
||
createdAt: Date;
|
||
updatedAt: Date;
|
||
}
|
||
|
||
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 - 對話內容
|
||
```typescript
|
||
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 - 學習會話 (整合四關數據)
|
||
```typescript
|
||
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 - 用戶回答記錄
|
||
```typescript
|
||
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 - 成就系統
|
||
```typescript
|
||
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 - 道具/物品系統 (整合四關和命條系統)
|
||
```typescript
|
||
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 - 學習分析 (四關系統數據)
|
||
```typescript
|
||
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關會話數據
|
||
```
|
||
|
||
### 索引策略 (優化四關查詢)
|
||
```sql
|
||
-- 用戶相關索引
|
||
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操作
|
||
- 前端需要適配新的數據結構和關係
|
||
- 分析服務需要重新設計以支援四關維度統計 |