13 KiB
13 KiB
共同數據模型
📋 概述
文檔名稱: 跨平台數據模型定義
建立日期: 2025-09-09
適用平台: Mobile App / Web App
負責團隊: 後端/數據庫設計
本文檔定義了Drama Ling系統中所有核心數據實體的結構和關係。
👤 用戶相關數據模型
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; // 上次命條恢復時間
// 統計數據
totalStudyDays: number; // 總學習天數
consecutiveStudyDays: number; // 連續學習天數
totalWordsLearned: number; // 總學習詞彙數
totalDialoguesCompleted: number; // 總完成對話數
// 成就數據
achievements: Achievement[];
}
UserProgress - 用戶學習進度
interface UserProgress {
id: string;
userId: string;
// 整體進度
overallProgress: number; // 0-100 整體學習進度
currentPhase: string; // 當前學習階段
// 各技能進度
vocabularyProgress: SkillProgress;
dialogueProgress: SkillProgress;
pronunciationProgress: SkillProgress;
grammarProgress: SkillProgress;
// 學習路徑
completedLevels: string[]; // 已完成關卡ID陣列
unlockedLevels: string[]; // 已解鎖關卡ID陣列
currentLevel: string; // 當前學習關卡ID
// 複習數據
reviewQueue: ReviewItem[]; // 複習佇列
updatedAt: 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';
nextReviewAt: Date; // 下次複習時間
reviewCount: number; // 已複習次數
difficulty: number; // 當前難度 1-5
masteryLevel: number; // 掌握程度 0-100
}
📚 學習內容數據模型
Vocabulary - 詞彙數據
interface Vocabulary {
id: string;
word: string; // 詞彙本體
language: string; // 語言代碼
// 詞彙資訊
pronunciation: string; // IPA音標
partOfSpeech: string; // 詞性
difficulty: number; // 難度等級 1-5
frequency: number; // 使用頻率評分
// 釋義
definitions: Definition[];
examples: Example[];
// 音頻
audioUrl: string; // 標準發音音頻URL
slowAudioUrl?: string; // 慢速發音音頻URL
// 分類
categories: string[]; // 詞彙分類標籤
topics: string[]; // 相關主題
// 關聯
synonyms: string[]; // 同義詞ID陣列
antonyms: string[]; // 反義詞ID陣列
relatedWords: string[]; // 相關詞彙ID陣列
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 - 對話內容
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: 'vocabulary' | 'dialogue' | 'review' | 'challenge';
contentId: string; // 學習內容ID
startTime: Date;
endTime?: Date;
duration?: number; // 實際學習時長(秒)
// 學習結果
completed: boolean;
score: number; // 得分 0-100
accuracy: number; // 準確率 0-100
// 詳細數據
activities: ActivityResult[];
// 獎勵
xpGained: number;
diamondsGained: number;
achievementsUnlocked: string[];
createdAt: Date;
}
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; // 最大堆疊數量
// 元數據
iconUrl: string;
rarity: ItemRarity;
// 購買限制
dailyLimit?: number; // 每日購買限制
requiresSubscription: boolean;
createdAt: Date;
updatedAt: Date;
}
interface ItemEffect {
type: 'restore_life' | 'double_xp' | 'skip_question' | 'extra_hint';
value: number; // 效果數值
duration?: number; // 持續時間(秒)
}
interface Price {
currency: 'diamonds' | 'learning_coins' | 'real_money';
amount: number;
}
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; // 平均會話時長
// 學習效果分析
wordsLearned: number; // 當日學習詞彙數
dialoguesCompleted: number; // 完成對話數
overallAccuracy: number; // 整體準確率
// 技能分析
vocabularyAccuracy: number;
dialogueAccuracy: number;
pronunciationScore: number;
// 學習模式分析
preferredStudyTime: string; // 偏好學習時段
mostActiveHour: number; // 最活躍小時
learningStreak: number; // 連續學習天數
// 困難分析
difficultWords: string[]; // 困難詞彙ID陣列
weakAreas: string[]; // 薄弱領域
improvementSuggestions: string[]; // 改進建議
createdAt: Date;
}
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) ←→ (1) UserInventory
Vocabulary (1) ←→ (*) UserAnswer
Dialogue (1) ←→ (*) StudySession
Achievement (1) ←→ (*) UserAchievement
StudySession (1) ←→ (*) ActivityResult
StudySession (1) ←→ (*) UserAnswer
索引策略
-- 用戶相關索引
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_study_session_user_date ON study_sessions(user_id, 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_language_difficulty ON vocabulary(language, difficulty);
CREATE INDEX idx_dialogue_difficulty_tags ON dialogues(difficulty, tags);
文檔狀態: 🟢 已完成
最後更新: 2025-09-09
版本: v1.0
相關文檔:
業務規則.md- 業務邏輯規則API規格.md- API接口定義../mobile/- 移動端功能規格../web/- Web端功能規格