# LinguaForge MVP 功能規格書

## 1. 產品概述

**產品名稱**：LinguaForge MVP
**版本**：0.1.0
**目標用戶**：想要高效學習英文詞彙的台灣用戶
**核心價值**：AI 自動生成個人化詞卡 + 科學化間隔複習

## 2. 用戶故事 (User Stories)

### 2.1 核心用戶故事（P0 - 必做）

```gherkin
Feature: 用戶註冊與登入
  As a 新用戶
  I want to 創建帳號並登入
  So that 我可以保存我的學習進度

  Scenario: Email 註冊
    Given 我是新用戶
    When 我輸入 email 和密碼
    Then 系統創建帳號並自動登入

Feature: AI 詞卡生成
  As a 用戶
  I want to 從句子中生成詞卡
  So that 我可以學習新單字

  Scenario: 生成詞卡
    Given 我輸入一個英文句子
    When 我選擇要學習的單字
    Then AI 生成包含定義和例句的詞卡

Feature: 間隔重複複習
  As a 用戶
  I want to 按照科學方法複習
  So that 我可以長期記住單字

  Scenario: 每日複習
    Given 我有待複習的詞卡
    When 我打開 App
    Then 我看到今日需要複習的詞卡列表
```

### 2.2 次要用戶故事（P1 - 可選）

```gherkin
Feature: 學習統計
  As a 用戶
  I want to 查看我的學習進度
  So that 我可以了解學習成效

Feature: 詞卡管理
  As a 用戶
  I want to 管理我的詞卡
  So that 我可以整理學習內容
```

## 3. 功能規格詳述

### 3.1 用戶系統

#### 註冊流程
```yaml
輸入欄位:
  - Email (必填，驗證格式)
  - 密碼 (必填，最少 8 字元)
  - 暱稱 (選填)

流程:
  1. 用戶填寫表單
  2. 前端驗證
  3. 發送到 Firebase Auth
  4. 創建 Supabase 用戶資料
  5. 自動登入
  6. 導向首頁

錯誤處理:
  - Email 已存在
  - 密碼太弱
  - 網路錯誤
```

#### 登入流程
```yaml
輸入欄位:
  - Email
  - 密碼

功能:
  - 記住我 (選項)
  - 忘記密碼 (連結)

流程:
  1. 輸入憑證
  2. Firebase Auth 驗證
  3. 取得 Token
  4. 載入用戶資料
  5. 導向首頁
```

### 3.2 AI 詞卡生成

#### 生成介面
```yaml
步驟一: 輸入句子
  - 文字輸入框 (最多 200 字元)
  - 範例句子提示
  - 清除按鈕

步驟二: 選擇單字
  - 自動標記可選單字
  - 點擊選擇 (最多 5 個)
  - 已選單字列表

步驟三: 生成詞卡
  - 生成按鈕
  - 載入動畫 (預估 3-5 秒)
  - 錯誤重試

步驟四: 預覽確認
  - 顯示生成結果
  - 編輯選項
  - 儲存/放棄
```

#### 詞卡資料結構
```json
{
  "id": "uuid",
  "word": "abandon",
  "pronunciation": "/əˈbændən/",
  "definition": "停止支持或照顧；放棄",
  "partOfSpeech": "verb",
  "examples": [
    {
      "english": "He abandoned his car in the snow.",
      "chinese": "他把車遺棄在雪地裡。"
    }
  ],
  "sourceSentence": "原始句子",
  "difficulty": "intermediate",
  "createdAt": "2024-01-15T10:00:00Z",
  "nextReviewDate": "2024-01-16T10:00:00Z",
  "reviewCount": 0,
  "easinessFactor": 2.5
}
```

### 3.3 複習系統

#### 複習流程
```yaml
進入複習:
  - 顯示待複習數量
  - 開始複習按鈕

複習介面:
  第一步: 顯示單字
    - 單字
    - 發音
    - 思考時間

  第二步: 顯示答案
    - 翻轉卡片動畫
    - 完整定義
    - 例句

  第三步: 自評難度
    - 完全不記得 (1)
    - 有點印象 (2)
    - 想了一下 (3)
    - 記得 (4)
    - 非常熟悉 (5)

  第四步: 下一張
    - 更新複習時間
    - 載入下張詞卡
```

#### SM-2 演算法實現
```typescript
interface ReviewResult {
  quality: number; // 1-5
  easinessFactor: number;
  interval: number;
  repetition: number;
}

function calculateNextReview(
  quality: number,
  currentEF: number,
  currentInterval: number,
  repetitions: number
): ReviewResult {
  let newEF = currentEF;
  let newInterval = currentInterval;
  let newRepetitions = repetitions;

  if (quality < 3) {
    // 重置
    newInterval = 1;
    newRepetitions = 0;
  } else {
    // 計算新 EF
    newEF = currentEF + (0.1 - (5 - quality) * (0.08 + (5 - quality) * 0.02));
    newEF = Math.max(1.3, newEF);

    // 計算間隔
    if (repetitions === 0) {
      newInterval = 1;
    } else if (repetitions === 1) {
      newInterval = 6;
    } else {
      newInterval = Math.round(currentInterval * newEF);
    }
    newRepetitions++;
  }

  return {
    quality,
    easinessFactor: newEF,
    interval: newInterval,
    repetition: newRepetitions
  };
}
```

### 3.4 詞卡管理

#### 列表檢視
```yaml
顯示內容:
  - 詞卡列表 (分頁，每頁 20)
  - 搜尋框
  - 排序選項 (新到舊/舊到新/字母)
  - 篩選 (全部/待複習/已掌握)

詞卡項目:
  - 單字
  - 定義摘要
  - 下次複習時間
  - 掌握程度圖示
```

#### 詞卡詳情
```yaml
顯示內容:
  - 完整單字資訊
  - 學習歷史
  - 編輯按鈕
  - 刪除按鈕

編輯功能:
  - 修改定義
  - 修改例句
  - 重設複習進度
```

### 3.5 學習統計

#### 儀表板
```yaml
今日數據:
  - 新增詞卡數
  - 複習詞卡數
  - 正確率
  - 學習時間

總體統計:
  - 總詞卡數
  - 連續學習天數
  - 本週學習時間
  - 掌握程度分布

視覺化:
  - 7 日學習趨勢圖
  - 詞彙掌握度圓餅圖
```

## 4. UI/UX 規格

### 4.1 設計系統

#### 顏色規範
```yaml
主色:
  primary: #4F46E5 (靛藍)
  primaryDark: #3730A3
  primaryLight: #818CF8

輔助色:
  success: #10B981 (綠)
  warning: #F59E0B (橙)
  error: #EF4444 (紅)
  info: #3B82F6 (藍)

中性色:
  background: #F9FAFB
  surface: #FFFFFF
  text: #111827
  textSecondary: #6B7280
  border: #E5E7EB
```

#### 字體規範
```yaml
標題:
  H1: 28px, bold
  H2: 24px, semibold
  H3: 20px, semibold

內文:
  body: 16px, regular
  caption: 14px, regular
  small: 12px, regular

按鈕:
  button: 16px, medium
```

### 4.2 主要畫面

#### 首頁
```
┌────────────────────┐
│     LinguaForge    │
├────────────────────┤
│  歡迎回來，用戶!   │
│                    │
│  今日待複習: 15    │
│  [開始複習]        │
│                    │
│  快速操作:         │
│  [+ 新增詞卡]      │
│                    │
│  學習統計          │
│  連續 7 天 🔥      │
│  本週 120 詞       │
└────────────────────┘
[首頁][詞卡][統計][我]
```

#### 詞卡生成
```
┌────────────────────┐
│    新增詞卡        │
├────────────────────┤
│ 輸入句子:          │
│ ┌────────────────┐ │
│ │                │ │
│ └────────────────┘ │
│                    │
│ 選擇單字:          │
│ [word1][word2]     │
│                    │
│ [生成詞卡]         │
└────────────────────┘
```

## 5. 資料庫設計

### 5.1 資料表結構

#### users 表
```sql
CREATE TABLE users (
  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  email VARCHAR(255) UNIQUE NOT NULL,
  nickname VARCHAR(50),
  created_at TIMESTAMP DEFAULT NOW(),
  last_login TIMESTAMP,
  preferences JSONB DEFAULT '{}'
);
```

#### cards 表
```sql
CREATE TABLE cards (
  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  user_id UUID REFERENCES users(id) ON DELETE CASCADE,
  word VARCHAR(100) NOT NULL,
  pronunciation VARCHAR(100),
  definition TEXT NOT NULL,
  part_of_speech VARCHAR(20),
  examples JSONB DEFAULT '[]',
  source_sentence TEXT,
  difficulty VARCHAR(20),
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW(),

  -- 複習相關
  next_review_date TIMESTAMP DEFAULT NOW(),
  easiness_factor DECIMAL(3,2) DEFAULT 2.5,
  interval_days INTEGER DEFAULT 0,
  repetition_count INTEGER DEFAULT 0,

  INDEX idx_user_review (user_id, next_review_date)
);
```

#### review_logs 表
```sql
CREATE TABLE review_logs (
  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  card_id UUID REFERENCES cards(id) ON DELETE CASCADE,
  user_id UUID REFERENCES users(id) ON DELETE CASCADE,
  quality INTEGER CHECK (quality BETWEEN 1 AND 5),
  reviewed_at TIMESTAMP DEFAULT NOW(),
  time_spent INTEGER, -- 秒數

  INDEX idx_user_date (user_id, reviewed_at)
);
```

## 6. API 規格

### 6.1 端點列表

```yaml
認證相關:
  POST /auth/register - 註冊
  POST /auth/login - 登入
  POST /auth/logout - 登出
  POST /auth/refresh - 更新 token

詞卡相關:
  GET /cards - 取得詞卡列表
  POST /cards - 新增詞卡
  GET /cards/:id - 取得單一詞卡
  PUT /cards/:id - 更新詞卡
  DELETE /cards/:id - 刪除詞卡
  POST /cards/generate - AI 生成詞卡

複習相關:
  GET /review/today - 今日待複習
  POST /review/submit - 提交複習結果

統計相關:
  GET /stats/summary - 學習統計摘要
  GET /stats/history - 歷史記錄
```

### 6.2 Gemini API 呼叫規格

#### Request
```javascript
const prompt = `
你是一個英語教學助手。請根據以下句子和目標單字，生成詞彙學習卡片。

句子：${sentence}
目標單字：${targetWord}

請以 JSON 格式返回：
{
  "word": "單字",
  "pronunciation": "IPA 音標",
  "definition": "中文定義",
  "partOfSpeech": "詞性",
  "examples": [
    {
      "english": "英文例句",
      "chinese": "中文翻譯"
    }
  ],
  "difficulty": "beginner/intermediate/advanced"
}
`;

const response = await geminiAPI.generateContent(prompt);
```

## 7. 效能需求

### 7.1 回應時間
- 頁面載入：< 2 秒
- API 回應：< 1 秒
- AI 生成：< 5 秒
- 資料庫查詢：< 100ms

### 7.2 容量規劃
- 單用戶詞卡上限：1000 張
- 每日 API 呼叫：100 次/用戶
- 圖片大小：< 500KB
- App 大小：< 50MB

## 8. 測試需求

### 8.1 功能測試
- [ ] 註冊流程完整測試
- [ ] 登入各種情境
- [ ] AI 生成 20+ 測試案例
- [ ] 複習演算法驗證
- [ ] 資料 CRUD 操作

### 8.2 相容性測試
- [ ] iOS 14+
- [ ] Android 8+
- [ ] 各種螢幕尺寸
- [ ] 橫豎屏切換

### 8.3 效能測試
- [ ] 1000 張詞卡載入
- [ ] 離線模式
- [ ] 記憶體使用
- [ ] 電池消耗

## 9. 成功指標

### 9.1 技術指標
- 崩潰率 < 1%
- 冷啟動 < 3 秒
- API 成功率 > 99%

### 9.2 產品指標
- D1 留存 > 60%
- D7 留存 > 40%
- 日均使用 > 10 分鐘
- 每用戶日均新增 > 3 詞卡

## 10. 未來擴展預留

### 10.1 Phase 2 功能
- 語音評估
- 訂閱系統
- 社群分享
- 詞卡分類
- 學習計劃

### 10.2 技術預留
- 多語言架構
- 主題切換架構
- 插件系統架構
- A/B 測試框架