522 lines
13 KiB
Markdown
522 lines
13 KiB
Markdown
# 共同數據模型
|
|
|
|
## 📋 概述
|
|
|
|
**文檔名稱**: 跨平台數據模型定義
|
|
**建立日期**: 2025-09-09
|
|
**適用平台**: Mobile App / Web App
|
|
**負責團隊**: 後端/數據庫設計
|
|
|
|
本文檔定義了Drama Ling系統中所有核心數據實體的結構和關係。
|
|
|
|
## 👤 用戶相關數據模型
|
|
|
|
### 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; // 上次命條恢復時間
|
|
|
|
// 統計數據
|
|
totalStudyDays: number; // 總學習天數
|
|
consecutiveStudyDays: number; // 連續學習天數
|
|
totalWordsLearned: number; // 總學習詞彙數
|
|
totalDialoguesCompleted: number; // 總完成對話數
|
|
|
|
// 成就數據
|
|
achievements: Achievement[];
|
|
}
|
|
```
|
|
|
|
### UserProgress - 用戶學習進度
|
|
```typescript
|
|
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 - 詞彙數據
|
|
```typescript
|
|
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 - 對話內容
|
|
```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: '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 - 用戶回答記錄
|
|
```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; // 最大堆疊數量
|
|
|
|
// 元數據
|
|
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 - 學習分析
|
|
```typescript
|
|
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
|
|
```
|
|
|
|
### 索引策略
|
|
```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_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端功能規格 |