# 個人化詞彙庫功能規格

## 🎯 功能概述

個人化詞彙庫是一個用戶專屬的詞彙管理系統，允許用戶收集、組織和追蹤自己的學習詞彙，並根據學習表現提供個人化的學習建議。

## 📋 核心功能需求

### 1. 詞彙收集功能

#### 1.1 手動添加詞彙
- **功能描述**：用戶可以手動輸入新詞彙到個人詞彙庫
- **輸入欄位**：
  - 英文詞彙（必填）
  - 詞性（可選，下拉選單）
  - 發音（可選，自動生成或手動輸入）
  - 定義（可選，自動生成或手動輸入）
  - 中文翻譯（可選，自動生成或手動輸入）
  - 個人筆記（可選，用戶自訂）
- **自動補全**：系統自動查詢並填入詞彙資訊
- **重複檢查**：避免添加重複詞彙

#### 1.2 學習中收集
- **學習頁面收藏**：在任何測驗模式中點擊「收藏」按鈕
- **困難詞彙標記**：答錯的詞彙自動標記為需要加強
- **快速收集**：一鍵添加當前學習的詞彙到個人庫

#### 1.3 批量導入
- **文字檔導入**：支援 .txt 格式的詞彙列表
- **CSV 導入**：支援結構化的詞彙資料
- **從學習記錄導入**：將過往答錯的詞彙批量加入

### 2. 詞彙組織功能

#### 2.1 分類管理
- **預設分類**：
  - 新學詞彙（New）
  - 學習中（Learning）
  - 熟悉（Familiar）
  - 精通（Mastered）
  - 困難詞彙（Difficult）
- **自訂分類**：用戶可創建自己的分類標籤
- **多重分類**：單一詞彙可屬於多個分類

#### 2.2 標籤系統
- **難度標籤**：A1, A2, B1, B2, C1, C2
- **主題標籤**：商業、旅遊、學術、日常等
- **來源標籤**：書籍、電影、新聞、會話等
- **自訂標籤**：用戶可創建個人標籤

#### 2.3 優先級管理
- **高優先級**：急需掌握的詞彙
- **中優先級**：重要但不緊急的詞彙
- **低優先級**：選擇性學習的詞彙

### 3. 學習追蹤功能

#### 3.1 熟悉度評分
- **評分機制**：0-100 分的熟悉度評分
- **多維度評估**：
  - 認識度（Recognition）：看到詞彙能理解
  - 回想度（Recall）：能主動想起詞彙
  - 應用度（Application）：能在語境中正確使用
- **動態調整**：根據測驗表現自動調整評分

#### 3.2 學習歷史
- **學習次數**：詞彙被學習的總次數
- **正確率**：各種測驗模式的正確率統計
- **最後學習時間**：記錄最近一次學習時間
- **學習軌跡**：詳細的學習歷程記錄

#### 3.3 遺忘曲線追蹤
- **複習提醒**：基於遺忘曲線的智能提醒
- **複習間隔**：動態調整複習時間間隔
- **記憶強度**：評估詞彙在記憶中的鞏固程度

### 4. 個人化學習功能

#### 4.1 智能推薦
- **弱點分析**：識別用戶的學習弱點
- **相似詞彙**：推薦語義相關的詞彙
- **同根詞擴展**：推薦同詞根的相關詞彙
- **搭配詞推薦**：推薦常見的詞彙搭配

#### 4.2 個人化測驗
- **客製化題組**：根據個人詞彙庫生成測驗
- **弱點加強**：針對困難詞彙的專門訓練
- **複習模式**：基於遺忘曲線的複習測驗
- **混合練習**：結合不同來源詞彙的綜合測驗

#### 4.3 學習計劃
- **每日目標**：設定每日學習詞彙數量
- **週期計劃**：制定短期和長期學習目標
- **進度追蹤**：視覺化顯示學習進度
- **成就系統**：學習里程碑和獎勵機制

## 🗃️ 資料結構設計

### 個人詞彙資料模型
```typescript
interface PersonalVocabulary {
  id: string;
  userId: string;
  word: string;
  partOfSpeech?: string;
  pronunciation?: string;
  definition?: string;
  translation?: string;
  personalNotes?: string;

  // 分類和標籤
  categories: string[];
  tags: string[];
  priority: 'high' | 'medium' | 'low';

  // 學習追蹤
  familiarityScore: number; // 0-100
  recognitionScore: number; // 0-100
  recallScore: number; // 0-100
  applicationScore: number; // 0-100

  // 學習統計
  totalPractices: number;
  correctAnswers: number;
  incorrectAnswers: number;
  lastPracticed: Date;
  nextReview: Date;

  // 測驗模式統計
  flipMemoryStats: TestModeStats;
  vocabChoiceStats: TestModeStats;
  sentenceFillStats: TestModeStats;
  // ... 其他測驗模式

  // 元資料
  createdAt: Date;
  updatedAt: Date;
  source?: string; // 詞彙來源
}

interface TestModeStats {
  attempts: number;
  correct: number;
  averageTime: number; // 平均回答時間（秒）
  lastAttempt: Date;
}
```

### 學習會話記錄
```typescript
interface LearningSession {
  id: string;
  userId: string;
  startTime: Date;
  endTime: Date;
  mode: string;
  vocabulariesPracticed: string[]; // 詞彙 IDs
  totalQuestions: number;
  correctAnswers: number;
  timeSpent: number; // 秒
  performance: SessionPerformance;
}

interface SessionPerformance {
  accuracy: number; // 正確率
  speed: number; // 平均回答速度
  improvement: number; // 相對上次的進步
  weakWords: string[]; // 表現較差的詞彙
  strongWords: string[]; // 表現較好的詞彙
}
```

## 🔧 技術實現方案

### 前端實現

#### 1. 狀態管理
```typescript
// 使用 Context API 或 Zustand
interface PersonalVocabStore {
  vocabularies: PersonalVocabulary[];
  currentSession: LearningSession | null;
  filters: VocabFilters;

  // Actions
  addVocabulary: (vocab: Partial<PersonalVocabulary>) => void;
  updateVocabulary: (id: string, updates: Partial<PersonalVocabulary>) => void;
  deleteVocabulary: (id: string) => void;
  updateFamiliarity: (id: string, testResult: TestResult) => void;
  // ...
}
```

#### 2. 本地儲存策略
- **IndexedDB**：大量詞彙資料的本地儲存
- **localStorage**：用戶偏好和設定
- **同步機制**：與伺服器的雙向同步

#### 3. UI 組件結構
```
/components/PersonalVocab/
├── VocabLibrary.tsx          # 詞彙庫主頁面
├── VocabCard.tsx             # 單一詞彙卡片
├── VocabForm.tsx             # 新增/編輯詞彙表單
├── VocabFilters.tsx          # 篩選和搜尋
├── VocabStats.tsx            # 學習統計
├── CategoryManager.tsx       # 分類管理
├── TagManager.tsx            # 標籤管理
└── ReviewScheduler.tsx       # 複習排程
```

### 後端實現

#### 1. API 端點設計
```
GET    /api/personal-vocab          # 獲取用戶詞彙庫
POST   /api/personal-vocab          # 新增詞彙
PUT    /api/personal-vocab/:id      # 更新詞彙
DELETE /api/personal-vocab/:id      # 刪除詞彙
POST   /api/personal-vocab/batch    # 批量操作

GET    /api/personal-vocab/stats    # 獲取學習統計
POST   /api/personal-vocab/practice # 記錄練習結果
GET    /api/personal-vocab/review   # 獲取需要複習的詞彙

GET    /api/learning-sessions       # 獲取學習會話記錄
POST   /api/learning-sessions       # 記錄學習會話
```

#### 2. 資料庫設計
```sql
-- 個人詞彙表
CREATE TABLE personal_vocabularies (
  id UUID PRIMARY KEY,
  user_id UUID REFERENCES users(id),
  word VARCHAR(100) NOT NULL,
  part_of_speech VARCHAR(20),
  pronunciation VARCHAR(200),
  definition TEXT,
  translation TEXT,
  personal_notes TEXT,
  familiarity_score INTEGER DEFAULT 0,
  recognition_score INTEGER DEFAULT 0,
  recall_score INTEGER DEFAULT 0,
  application_score INTEGER DEFAULT 0,
  total_practices INTEGER DEFAULT 0,
  correct_answers INTEGER DEFAULT 0,
  incorrect_answers INTEGER DEFAULT 0,
  last_practiced TIMESTAMP,
  next_review TIMESTAMP,
  priority VARCHAR(10) DEFAULT 'medium',
  source VARCHAR(100),
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

-- 詞彙分類表
CREATE TABLE vocab_categories (
  id UUID PRIMARY KEY,
  user_id UUID REFERENCES users(id),
  name VARCHAR(50) NOT NULL,
  color VARCHAR(7), -- HEX color
  description TEXT,
  created_at TIMESTAMP DEFAULT NOW()
);

-- 詞彙-分類關聯表
CREATE TABLE vocab_category_relations (
  vocab_id UUID REFERENCES personal_vocabularies(id),
  category_id UUID REFERENCES vocab_categories(id),
  PRIMARY KEY (vocab_id, category_id)
);

-- 學習會話表
CREATE TABLE learning_sessions (
  id UUID PRIMARY KEY,
  user_id UUID REFERENCES users(id),
  mode VARCHAR(50) NOT NULL,
  start_time TIMESTAMP NOT NULL,
  end_time TIMESTAMP,
  total_questions INTEGER DEFAULT 0,
  correct_answers INTEGER DEFAULT 0,
  time_spent INTEGER DEFAULT 0, -- 秒
  created_at TIMESTAMP DEFAULT NOW()
);

-- 詞彙練習記錄表
CREATE TABLE vocab_practice_records (
  id UUID PRIMARY KEY,
  session_id UUID REFERENCES learning_sessions(id),
  vocab_id UUID REFERENCES personal_vocabularies(id),
  test_mode VARCHAR(50) NOT NULL,
  is_correct BOOLEAN NOT NULL,
  response_time INTEGER, -- 毫秒
  user_answer TEXT,
  created_at TIMESTAMP DEFAULT NOW()
);
```

## 🎨 使用者介面設計

### 主要頁面結構

#### 1. 詞彙庫總覽頁面 (`/personal-vocab`)
```
┌─────────────────────────────────────┐
│ 🏠 個人詞彙庫 (1,247 個詞彙)         │
├─────────────────────────────────────┤
│ [搜尋框] [篩選] [排序] [新增詞彙]     │
├─────────────────────────────────────┤
│ 📊 學習統計                          │
│ • 今日學習：12 個詞彙                │
│ • 本週進度：85% 完成                 │
│ • 平均正確率：78%                    │
├─────────────────────────────────────┤
│ 📚 詞彙分類                          │
│ [新學詞彙 124] [學習中 89] [熟悉 856] │
│ [困難詞彙 45] [我的收藏 67]          │
├─────────────────────────────────────┤
│ 📝 詞彙列表                          │
│ ┌─────────────────────────────────┐  │
│ │ brought (動詞) ⭐⭐⭐⭐☆         │  │
│ │ 發音: /brɔːt/ | 熟悉度: 80%      │  │
│ │ 定義: Past tense of bring...     │  │
│ │ [編輯] [練習] [刪除]              │  │
│ └─────────────────────────────────┘  │
│ (更多詞彙卡片...)                    │
└─────────────────────────────────────┘
```

#### 2. 詞彙詳情頁面 (`/personal-vocab/:id`)
```
┌─────────────────────────────────────┐
│ ← 返回詞彙庫                         │
├─────────────────────────────────────┤
│ 📝 brought                          │
│ 動詞 | 難度: B1 | 優先級: 高        │
├─────────────────────────────────────┤
│ 🔊 發音: /brɔːt/ [播放]             │
│ 📖 定義: Past tense of bring...     │
│ 🈲 翻譯: 提出、帶來                  │
│ 📝 個人筆記: [編輯區域]              │
├─────────────────────────────────────┤
│ 📊 學習統計                          │
│ • 熟悉度: ████████░░ 80%            │
│ • 總練習: 25 次                      │
│ • 正確率: 85%                        │
│ • 上次練習: 2 小時前                 │
│ • 下次複習: 明天 14:00              │
├─────────────────────────────────────┤
│ 🎯 各模式表現                        │
│ • 翻卡記憶: 90% (15/15)             │
│ • 詞彙選擇: 75% (12/16)             │
│ • 例句填空: 80% (8/10)              │
├─────────────────────────────────────┤
│ 🏷️ 分類標籤                         │
│ [學習中] [商業英語] [重要詞彙]       │
│ [+ 添加標籤]                        │
├─────────────────────────────────────┤
│ 🎮 快速練習                          │
│ [翻卡記憶] [詞彙選擇] [例句填空]     │
└─────────────────────────────────────┘
```

#### 3. 新增詞彙頁面 (`/personal-vocab/add`)
```
┌─────────────────────────────────────┐
│ ➕ 新增詞彙到個人庫                  │
├─────────────────────────────────────┤
│ 📝 英文詞彙: [輸入框] *必填          │
│ 🔍 [智能查詢] - 自動填入詞彙資訊      │
├─────────────────────────────────────┤
│ 📖 詞彙資訊                          │
│ • 詞性: [下拉選單]                   │
│ • 發音: [輸入框] [生成]              │
│ • 定義: [文字區域] [自動生成]        │
│ • 翻譯: [輸入框] [自動翻譯]          │
├─────────────────────────────────────┤
│ 🏷️ 分類設定                         │
│ • 分類: [多選下拉] [新增分類]        │
│ • 標籤: [標籤選擇器] [新增標籤]      │
│ • 優先級: ⚫ 高 ⚪ 中 ⚪ 低          │
├─────────────────────────────────────┤
│ 📝 個人筆記                          │
│ [多行文字輸入區域]                   │
├─────────────────────────────────────┤
│ [取消] [儲存詞彙]                    │
└─────────────────────────────────────┘
```

## 🔄 學習流程整合

### 1. 學習中的詞彙收集
- **收藏按鈕**：每個測驗頁面都有收藏功能
- **自動收集**：答錯的詞彙自動標記為需要加強
- **學習後提醒**：學習會話結束後推薦收藏的詞彙

### 2. 個人化測驗生成
- **我的詞彙測驗**：從個人庫選取詞彙生成測驗
- **弱點強化**：針對低熟悉度詞彙的專門練習
- **混合模式**：結合系統詞彙和個人詞彙的測驗

### 3. 複習提醒系統
- **智能排程**：基於遺忘曲線安排複習時間
- **推送通知**：瀏覽器通知提醒複習時間
- **複習優化**：根據表現調整複習頻率

## 📱 響應式設計考量

### 桌面版 (>= 1024px)
- **三欄布局**：側邊欄（分類）+ 詞彙列表 + 詳情面板
- **拖拉操作**：支援拖拉詞彙到不同分類
- **快速鍵**：鍵盤快速鍵支援

### 平板版 (768px - 1023px)
- **兩欄布局**：詞彙列表 + 詳情面板
- **觸控優化**：適合觸控操作的按鈕尺寸

### 手機版 (< 768px)
- **單欄布局**：全螢幕顯示當前頁面
- **底部導航**：快速切換功能
- **手勢支援**：滑動操作和長按功能

## 🚀 實施階段規劃

### 階段 1：基礎詞彙管理 (第 1-2 週)
- [ ] 資料庫設計和建立
- [ ] 基本 CRUD API 開發
- [ ] 詞彙列表頁面
- [ ] 新增/編輯詞彙功能
- [ ] 基本搜尋和篩選

### 階段 2：學習追蹤系統 (第 3-4 週)
- [ ] 熟悉度評分系統
- [ ] 學習歷史記錄
- [ ] 測驗結果整合
- [ ] 學習統計儀表板

### 階段 3：智能化功能 (第 5-6 週)
- [ ] 遺忘曲線算法
- [ ] 複習提醒系統
- [ ] 個人化推薦
- [ ] 弱點分析

### 階段 4：高級功能 (第 7-8 週)
- [ ] 批量導入/導出
- [ ] 學習計劃制定
- [ ] 成就系統
- [ ] 社交分享功能

## 📊 成功指標

### 用戶行為指標
- **詞彙庫使用率**：> 80% 用戶建立個人詞彙庫
- **收藏率**：> 60% 學習中的詞彙被收藏
- **複習完成率**：> 70% 的複習提醒被完成
- **熟悉度提升**：平均熟悉度每週提升 5%

### 學習效果指標
- **記憶保持率**：複習詞彙的正確率 > 85%
- **學習效率**：個人詞彙的學習時間縮短 30%
- **長期記憶**：30 天後的詞彙記憶率 > 70%

### 系統性能指標
- **回應時間**：詞彙庫載入時間 < 2 秒
- **同步效率**：資料同步成功率 > 99%
- **儲存效率**：本地儲存空間使用 < 50MB

## 🔐 隱私和安全考量

### 資料隱私
- **用戶授權**：明確的隱私政策和使用條款
- **資料加密**：敏感資料的端到端加密
- **匿名化**：學習統計資料的匿名化處理

### 資料安全
- **備份機制**：定期備份用戶資料
- **版本控制**：資料變更的版本記錄
- **災難恢復**：資料遺失的恢復機制

## 🔮 未來擴展功能

### 社交學習功能
- **詞彙分享**：分享個人詞彙庫給其他用戶
- **學習小組**：創建詞彙學習小組
- **競賽模式**：與朋友的詞彙學習競賽

### AI 智能功能
- **智能生成**：AI 生成個人化例句
- **發音評估**：AI 評估發音準確度
- **學習建議**：AI 提供個人化學習建議

### 多媒體功能
- **語音筆記**：錄音形式的個人筆記
- **圖片聯想**：為詞彙添加個人化圖片
- **影片連結**：連結相關的學習影片

---

## 📝 附註

本規格文件為個人化詞彙庫功能的完整設計，包含前後端實現細節和用戶體驗考量。實際開發時可根據優先級和資源情況分階段實施。

**建議優先實施階段 1 和階段 2**，建立穩固的基礎功能，再逐步添加智能化和高級功能。

---

*最後更新：2025-09-20*
*版本：v1.0*