# 共同數據模型

## 📋 概述

**文檔名稱**: 跨平台數據模型定義  
**建立日期**: 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端功能規格