# DramaLing 產品需求規格書

## 📋 **文件資訊**

- **文件名稱**: DramaLing 產品需求規格書 (統一版)
- **版本**: v3.0 (整合版)
- **建立日期**: 2025-09-23
- **最後更新**: 2025-09-23
- **負責團隊**: DramaLing 產品與技術團隊
- **適用範圍**: 全平台 (Web、API、未來 Mobile)

---

## 🎯 **產品概述**

### **產品定位**
DramaLing 是一個 AI 驅動的個人化英語學習平台，專注於通過智能句子分析、互動式詞彙學習和間隔重複算法，提供高效的英語學習體驗。

### **商業目標**
- 🎯 **提升學習效率**: 通過 AI 分析幫助用戶快速理解句子結構
- 💡 **個人化學習**: 基於用戶 CEFR 等級提供適合的學習內容
- 📈 **用戶留存**: 通過互動式體驗和科學算法增加平台黏性
- 🌍 **市場差異化**: 提供業界領先的 AI 驅動語言學習體驗

### **核心價值主張**
- 🤖 **AI 驅動分析** - 即時語法檢查和詞彙解析
- 🎯 **個人化學習** - 基於 CEFR 等級的智能詞彙分類
- 📊 **科學算法** - SM-2 間隔重複算法優化記憶
- 💡 **互動式體驗** - 點擊探索式的深度學習

---

## 🎭 **核心用戶故事**

### **US1. AI 智能分析流程**

#### **US1.1 智能句子分析**
```gherkin
功能: 智能英文句子分析
背景: 用戶想要學習和理解英文句子

場景: 用戶分析英文句子
  給定 用戶是英語學習者 (CEFR A2 等級)
  當 用戶輸入英文句子 "She just join the team, so let's cut her some slack until she get used to the workflow."
  並且 點擊「分析句子」按鈕
  那麼 系統應該顯示語法修正建議 (join → joins, get → gets)
  並且 系統應該提供詞彙難度標記 (based on A2 level)
  並且 系統應該識別慣用語 "cut someone some slack"
  並且 系統應該提供完整的中文翻譯

驗收標準:
- 能輸入最多 300 字的英文句子
- 分析回應時間 < 5 秒
- 語法檢查準確率 > 85%
- 詞彙 CEFR 分級準確率 > 90%
- 慣用語識別覆蓋率 > 80%
```

#### **US1.2 個人化詞彙學習**
```gherkin
功能: 基於 CEFR 等級的個人化詞彙標記
背景: 不同程度的學習者需要不同的學習重點

場景: A2 程度學習者查看句子分析
  給定 用戶的 CEFR 等級是 A2
  當 系統分析句子中的詞彙
  那麼 A1 詞彙應該顯示為「太簡單啦」(灰色虛線)
  並且 A2 詞彙應該顯示為「重點學習」(綠色邊框)
  並且 B1+ 詞彙應該顯示為「有點挑戰」(橙色邊框)
  並且 慣用語應該獨立顯示為「慣用語」(藍色邊框)
  並且 常用詞彙顯示 ⭐ 星星標記

驗收標準:
- 詞彙分類基於用戶當前 CEFR 等級動態計算
- 用戶可以調整 CEFR 等級設定
- 等級變更時詞彙標記即時更新
- 統計卡片數字與實際標記一致
- 常用詞彙星星標記正確顯示
```

### **US2. 詞卡管理系統**

#### **US2.1 AI 詞卡生成**
```gherkin
功能: 從分析結果生成學習詞卡
背景: 用戶想要將分析的詞彙保存為學習材料

場景: 用戶生成詞卡
  給定 句子分析已完成
  當 用戶點擊詞彙的「保存到詞卡」按鈕
  那麼 系統應該自動填入詞彙資訊
  並且 包含翻譯、定義、發音、例句
  並且 設定適當的 CEFR 等級
  並且 保存到用戶的詞卡庫

驗收標準:
- 一鍵保存詞彙到詞卡
- 自動填入完整詞卡資訊
- 支援批量生成詞卡
- 避免重複詞卡 (智能檢測)
```

#### **US2.2 詞卡學習系統**
```gherkin
功能: 科學的間隔重複學習
背景: 用戶需要有效的記憶和複習機制

場景: 用戶進行詞卡複習
  給定 用戶有待複習的詞卡
  當 用戶進入學習模式
  那麼 系統應該根據 SM-2 算法排序詞卡
  並且 提供多種學習模式 (翻卡/測驗)
  並且 根據答題表現調整複習間隔
  並且 追蹤學習進度和統計

驗收標準:
- SM-2 算法正確實施
- 學習模式切換流暢
- 進度追蹤準確
- 複習提醒及時
```

---

## 📋 **功能需求規格**

### **FR1. 用戶認證系統**

#### **FR1.1 註冊與登入**
**優先級**: P0 (必須)

**功能描述**:
- Email 註冊與驗證
- Google OAuth 整合
- 安全的密碼管理
- 多設備 Session 管理

**詳細規格**:
```yaml
註冊功能:
  - Email 格式驗證和唯一性檢查
  - 密碼要求: 最少8位，包含大小寫字母、數字、特殊符號
  - 用戶名: 3-20字符，唯一性檢查
  - 驗證郵件: 24小時有效期
  - Google OAuth: 一鍵登入，自動創建帳號

登入功能:
  - Email/密碼登入
  - 記住我功能 (7天/30天)
  - 失敗限制: 5次後鎖定15分鐘
  - 上次登入信息顯示

Session 管理:
  - JWT Token: Access (15分鐘), Refresh (7天)
  - 自動更新 Token
  - 多裝置登入管理
  - 強制登出所有裝置
```

### **FR2. AI 智能分析系統**

#### **FR2.1 文本輸入處理**
**優先級**: P0 (必須)

**功能描述**:
- 支援英文文本輸入和預處理
- 智能字符限制和驗證
- 輸入格式標準化

**詳細規格**:
```yaml
輸入限制:
  - 最大長度: 300 字符
  - 支援字符: 英文字母、數字、標點符號
  - 警告機制: 280字符黃色警告，300字符禁止輸入
  - 即時驗證: 字符計數顯示，超限阻止提交

錯誤處理:
  - 空字串: 禁用分析按鈕
  - 無效字符: 自動過濾或提示
  - 超長文本: 截斷並警告用戶

預處理功能:
  - 自動語言檢測 (英文)
  - 格式標準化
  - 特殊字符處理
```

#### **FR2.2 AI 分析核心**
**優先級**: P0 (必須)

**功能描述**:
- 整合 Google Gemini API 進行多維度分析
- 提供語法檢查、詞彙分析、翻譯、慣用語識別
- 確保分析準確性和一致性

**詳細規格**:
```yaml
分析範圍:
  - 語法檢查: 時態、主謂一致、介詞、詞序
  - 詞彙分析: CEFR等級、詞性、發音、翻譯、使用頻率
  - 句子翻譯: 自然流暢的繁體中文
  - 慣用語識別: 慣用語、片語動詞、固定搭配

API 回應格式:
  - 詞彙物件: word, definition, translation, cefrLevel, isCommon
  - 慣用語物件: idiom, meaning, translation, isCommon
  - 語法修正: original, corrected, type, explanation
  - 整句翻譯: 完整的繁體中文翻譯

品質要求:
  - 語法檢查準確率: > 85%
  - CEFR 分級準確率: > 90%
  - 翻譯自然度評分: > 4.0/5.0
  - 慣用語識別率: > 80%
  - 常用詞頻率判定準確率: > 85%

性能要求:
  - 分析響應時間: < 5 秒
  - 同時支援用戶數: > 100
  - 服務可用性: > 99.5%
  - 快取命中率: > 80% (已實現 67%+)
```

#### **FR2.3 個人化學習引擎**
**優先級**: P0 (必須)

**功能描述**:
- 基於用戶 CEFR 等級的動態詞彙分類
- 智能學習重點推薦
- 個人化統計和進度追蹤

**詳細規格**:
```yaml
分類邏輯:
  - 簡單詞彙: 用戶等級 > 詞彙等級
  - 適中詞彙: 用戶等級 = 詞彙等級
  - 困難詞彙: 用戶等級 < 詞彙等級
  - 慣用語: 獨立分類，不參與等級比較

支援等級:
  - A1: 初學者 (約1000詞彙)
  - A2: 基礎 (約2000詞彙)
  - B1: 中級 (約3000詞彙)
  - B2: 中高級 (約4000詞彙)
  - C1: 高級 (約8000詞彙)
  - C2: 精通 (約15000詞彙)

視覺標記:
  - 簡單詞彙: 灰色虛線，「太簡單啦」
  - 適中詞彙: 綠色邊框，「重點學習」
  - 困難詞彙: 橙色邊框，「有點挑戰」
  - 慣用語: 藍色邊框，「慣用語」
  - 常用標記: ⭐ 星星 (右上角)
```

### **FR3. 詞卡管理系統**

#### **FR3.1 詞卡 CRUD 操作**
**優先級**: P0 (必須)

**功能描述**:
- 完整的詞卡創建、讀取、更新、刪除功能
- 批量操作和管理工具
- 智能重複檢測

**詳細規格**:
```yaml
創建功能:
  - 手動創建 (填寫表單)
  - 從 AI 分析結果創建
  - 批量導入 (CSV/JSON)
  - 快速添加模式

編輯功能:
  - 編輯所有欄位
  - 富文本編輯器 (例句)
  - 圖片上傳 (記憶圖像)
  - 音頻錄製 (自定義發音)

刪除功能:
  - 單個刪除 (確認對話框)
  - 批量刪除 (多選)
  - 軟刪除 (回收站，30天內可恢復)

組織功能:
  - 標籤系統 (預設 + 自定義)
  - 收藏功能
  - 搜尋篩選 (全文搜尋、標籤、難度、狀態)
  - 排序選項 (創建時間、掌握度、複習時間)
```

#### **FR3.2 智能詞卡生成**
**優先級**: P0 (必須)

**功能描述**:
- 從 AI 分析結果一鍵生成詞卡
- 自動填入完整詞卡資訊
- 智能去重和品質檢查

**詳細規格**:
```yaml
生成流程:
  1. AI 分析句子
  2. 用戶點擊詞彙「保存到詞卡」
  3. 自動填入詞卡資訊
  4. 用戶確認或編輯
  5. 保存到詞卡庫

詞卡內容:
  - 基礎資訊: 詞彙、翻譯、定義、詞性
  - 語音資訊: IPA 發音、音頻播放
  - 學習輔助: 同義詞、例句、例句翻譯
  - 個人化: CEFR 等級、難度標記

品質保證:
  - 重複檢測: 避免創建重複詞卡
  - 資訊完整性: 必填欄位驗證
  - 格式標準化: 統一的資料格式
```

### **FR4. 學習系統**

#### **FR4.1 間隔重複算法 (SM-2)**
**優先級**: P0 (必須)

**功能描述**:
- 實施科學的 SM-2 算法
- 智能複習排程
- 個人化學習參數調整

**詳細規格**:
```yaml
算法參數:
  - 初始間隔: 1天、6天、依此類推
  - 難度係數: 1.3-2.5
  - 最小間隔: 1天
  - 最大間隔: 365天

評分系統:
  - 1分: 完全不記得 (重置進度)
  - 2分: 有印象但錯誤 (間隔 × 0.6)
  - 3分: 困難但正確 (間隔 × 0.8)
  - 4分: 猶豫後正確 (間隔 × 1.0)
  - 5分: 輕鬆正確 (間隔 × 1.3)

複習排程:
  - 每日複習上限: 可設定 (預設50個)
  - 優先級排序: 過期天數、難度係數
  - 智能分散: 避免同時大量到期
  - 負債管理: 過期詞卡優先處理
```

#### **FR4.2 多模式學習**
**優先級**: P1 (重要)

**功能描述**:
- 多種學習模式適應不同學習偏好
- 互動式學習體驗
- 進度追蹤和反饋

**詳細規格**:
```yaml
翻卡模式:
  - 正面: 英文詞彙
  - 背面: 定義、例句、發音、圖片
  - 操作: 手勢滑動、鍵盤快捷鍵
  - 評分: 1-5分即時評分

測驗模式:
  - 選擇題: 定義選翻譯 (4選1)
  - 填空題: 例句挖空填入
  - 聽力測試: 聽音選詞 (未來)
  - 口說測試: 念例句 (未來)

沉浸模式:
  - 全螢幕學習
  - 自動播放 (可調速度)
  - 背景音樂 (白噪音)
  - 番茄鐘計時 (25分鐘)
```

### **FR5. 數據分析與統計**

#### **FR5.1 學習統計**
**優先級**: P1 (重要)

**功能描述**:
- 全面的學習數據追蹤
- 視覺化進度展示
- 成就系統激勵

**詳細規格**:
```yaml
基礎數據:
  - 總學習詞彙數
  - 今日學習時間
  - 連續學習天數
  - 週/月學習統計
  - 平均每日學習詞數

進階分析:
  - 記憶曲線 (艾賓浩斯)
  - 詞彙掌握度分布
  - 最難/最易詞彙排行
  - 學習效率趨勢
  - 最佳學習時段分析

視覺化展示:
  - 折線圖: 學習趨勢
  - 柱狀圖: 每日學習量
  - 熱力圖: 365天學習記錄
  - 圓餅圖: 詞彙分類分布
  - 雷達圖: 能力維度分析

成就系統:
  - 里程碑徽章 (100/500/1000詞)
  - 連續學習徽章 (7/30/100天)
  - 特殊成就 (完美週/月)
  - 等級系統 (經驗值)
```

---

## 🎨 **用戶介面需求**

### **UI1. 視覺設計標準**

#### **UI1.1 詞彙標記設計**
```yaml
視覺層次:
  - 簡單詞彙: bg-gray-50, border-dashed, border-gray-300
  - 適中詞彙: bg-green-50, border-green-200, text-green-700
  - 困難詞彙: bg-orange-50, border-orange-200, text-orange-700
  - 慣用語: bg-blue-50, border-blue-200, text-blue-700

常用標記設計:
  - 圖示: ⭐ emoji 星星
  - 位置: 詞彙框線內右上角，絕對定位
  - 大小: 12px (桌面) / 10px (移動設備)
  - 顯示條件: 僅當 isCommon === true 時顯示
  - 響應式: 在所有詞彙類型中一致顯示

互動效果:
  - hover: 陰影提升，輕微上移
  - focus: 鍵盤導航支援
  - active: 點擊回饋動畫
  - 星星: 無互動行為，純視覺標記
```

#### **UI1.2 響應式設計**
```yaml
桌面版 (>1024px):
  - 三欄布局 (側邊欄+主內容+右側面板)
  - 懸浮操作按鈕
  - 鍵盤快捷鍵支援

平板版 (768-1024px):
  - 兩欄布局
  - 可收縮側邊欄
  - 觸控優化

手機版 (<768px):
  - 單欄布局
  - 底部導航欄
  - 手勢操作
  - 大按鈕設計
```

---

## 🔧 **技術規格需求**

### **Tech1. 前端技術棧**
```yaml
框架: Next.js 15 (App Router)
語言: TypeScript
樣式: Tailwind CSS
狀態管理: React useState/useEffect
數據獲取: Native fetch
表單: React Hook Form (規劃中)
```

### **Tech2. 後端技術棧**
```yaml
API: .NET 8 Web API
資料庫: SQLite (開發) / PostgreSQL (生產)
認證: JWT Bearer Token
AI: Google Gemini API
快取: Memory Cache + 分散式快取架構
檔案存儲: 本地存儲 (規劃中: 雲端存儲)
```

### **Tech3. 第三方服務**
```yaml
AI 服務: Google Gemini API
語音服務: Azure Speech Services (規劃中)
分析追蹤: 內建日誌系統
錯誤監控: 結構化錯誤處理
CDN: 本地部署 (規劃中: CDN)
```

---

## 🧪 **非功能性需求**

### **NFR1. 性能需求**

#### **NFR1.1 響應時間要求**
```yaml
核心功能:
  - 文本輸入響應: < 100ms
  - AI 分析處理: < 5秒
  - 詞彙標記渲染: < 200ms
  - 詞彙詳情彈窗: < 100ms
  - 統計卡片更新: < 50ms

已實現性能:
  - 快取命中響應: < 0.1ms (57,200倍提升)
  - API 端點響應: < 200ms
  - 頁面載入時間: < 2秒

系統負載:
  - 同時在線用戶: > 100
  - 每日分析請求: > 10,000
  - 峰值處理能力: > 200 req/min
  - 系統可用性: > 99.5%
```

### **NFR2. 安全需求**
```yaml
認證安全:
  - JWT Token 管理
  - 密碼加密 (bcrypt)
  - Session 超時控制
  - 多設備管理

數據安全:
  - HTTPS 強制加密
  - XSS 防護 (已實現)
  - 輸入驗證 (已實現)
  - SQL Injection 防護
  - Rate Limiting (已實現)

隱私保護:
  - 用戶數據加密存儲
  - 分析記錄本地化
  - 數據導出功能
  - 帳號刪除功能
```

---

## 🚀 **開發路線圖**

### **Phase 1: MVP 基礎 (已完成) ✅**
**時間**: 第1-2週
- ✅ AI 句子分析核心功能
- ✅ 基礎詞彙標記和分類
- ✅ 語法修正功能
- ✅ 慣用語識別
- ✅ 基礎 UI 和響應式設計

### **Phase 2: 性能優化 (已完成) ✅**
**時間**: 第3週
- ✅ 智能快取系統 (57,200倍性能提升)
- ✅ 架構重構和優化
- ✅ 錯誤處理改善
- ✅ 監控系統建立

### **Phase 3: 系統穩定 (當前階段) 🔄**
**時間**: 第4週
- ✅ 詞卡頁面修復 (CardSets 概念移除)
- 🔄 認證系統完善
- ⏳ 詞卡管理功能完整實現
- ⏳ 學習模式實現

### **Phase 4: 功能擴展 (規劃中) 📅**
**時間**: 第5-6週
- 📅 SM-2 算法完整實施
- 📅 學習統計和可視化
- 📅 語音功能整合
- 📅 測驗模式多樣化

### **Phase 5: 商業化準備 (未來) 🔮**
**時間**: 第7-8週
- 🔮 付費方案設計
- 🔮 用戶反饋系統
- 🔮 管理後台
- 🔮 A/B 測試框架

---

## ✅ **驗收標準**

### **AC1. 功能驗收 (當前狀態)**

#### **AI 分析功能** ✅
- [x] 文本輸入和字符限制正常運作
- [x] AI 分析在5秒內完成並返回結果
- [x] 語法修正準確檢測並提供合理建議
- [x] 詞彙 CEFR 分級準確率達到90%以上
- [x] 慣用語識別功能正常
- [x] 個人化詞彙標記根據用戶等級正確分類
- [x] 統計卡片數字與實際詞彙標記一致
- [x] 詞彙和慣用語詳情彈窗正常運作
- [x] 常用詞彙正確顯示 ⭐ 星星標記

#### **系統基礎** ✅
- [x] 前後端服務穩定運行
- [x] 快取系統高效運作 (67% 命中率)
- [x] API 端點正常響應
- [x] 錯誤處理和日誌記錄完善

#### **待完成功能** ⏳
- [ ] 用戶認證系統 (JWT 整合)
- [ ] 詞卡 CRUD 完整實現
- [ ] 學習模式和 SM-2 算法
- [ ] 完整的用戶介面和體驗

### **AC2. 技術驗收**
- [x] API 回應格式穩定一致
- [x] 性能指標達到要求基準 (57,200倍提升)
- [x] 架構治理系統建立
- [ ] 安全檢查通過滲透測試
- [ ] 代碼測試覆蓋率 > 80%

---

## 📊 **成功指標 (KPIs)**

### **產品指標**
```yaml
用戶參與度:
  - 日活躍用戶數 (DAU): > 100 (MVP 目標)
  - 平均每用戶分析次數: > 5次/日
  - 功能使用率: > 80%
  - 用戶滿意度: > 4.5/5

學習效果:
  - 詞彙掌握改善度: > 30%
  - 重複使用率: > 60%
  - 學習目標完成率: > 85%
```

### **技術指標 (已實現)**
```yaml
性能指標:
  - 快取命中率: 67% (目標 80%+)
  - API 回應時間: < 0.1ms (快取) / < 5s (AI)
  - 頁面載入時間: < 2秒
  - 系統可用性: > 99%

品質指標:
  - AI 分析準確率: > 90%
  - 架構健康度: 78/100
  - 零停機部署: ✅
  - 錯誤恢復能力: ✅
```

---

## 🔄 **變更管理**

### **需求變更流程**
1. **變更提出**: 產品經理、技術團隊、用戶反饋
2. **影響評估**: 技術可行性、時程影響、資源需求
3. **優先級評定**: 商業價值、緊急程度、實施成本
4. **實施追蹤**: 開發進度、測試驗證、部署監控

### **文檔版本歷史**
- **v1.0**: 初始 AI 分析功能規格 (2025-09-21)
- **v2.0**: 系統功能需求規格 (2025-01-25)
- **v3.0**: 統一產品需求規格書 (2025-09-23)

---

## 📚 **關聯文件**

### **技術文檔**
- [架構治理指南](../ARCHITECTURE_GOVERNANCE.md)
- [架構檢查清單](../ARCHITECTURE_CHECKLIST.md)
- [Services 優化總結](../SERVICES_OPTIMIZATION_SUMMARY.md)
- [技術架構指南](./docs/05_deployment/AI驅動產品後端技術架構指南.md)

### **修復記錄**
- [詞卡頁面問題診斷](../FLASHCARD_PAGE_ISSUE_REPORT.md)
- [詞卡修復總結](../FLASHCARD_FIX_SUMMARY.md)
- [系統優化摘要](../OPTIMIZATION_SUMMARY.md)

---

**文件狀態**: 🟢 當前有效
**下次審查**: 2025-10-23
**維護責任**: DramaLing 產品與技術團隊