# 共同數據模型

## 📋 概述

**文檔名稱**: 跨平台數據模型定義  
**建立日期**: 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;             // 語言代碼
  
  // 詞彙基本資訊
  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 - 對話內容
```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操作
- 前端需要適配新的數據結構和關係
- 分析服務需要重新設計以支援四關維度統計