# DramaLing 功能需求規格書

## 1. 核心功能需求

### 1.1 用戶認證系統

#### 1.1.1 註冊功能
- **Email 註冊**
  - 輸入：Email、密碼、用戶名
  - 密碼要求：最少8位，需包含大小寫字母、數字、特殊符號
  - Email 格式驗證
  - 用戶名唯一性檢查（3-20字符）
  - 發送驗證郵件（24小時有效期）
  - 驗證後自動登入

- **Google OAuth 登入**
  - 一鍵 Google 登入
  - 自動獲取用戶名稱和頭像
  - 首次登入自動創建帳號
  - 綁定現有帳號功能

- **錯誤處理**
  - Email 已註冊提示
  - 密碼強度即時反饋
  - 驗證碼錯誤/過期處理

#### 1.1.2 登入/登出
- **登入功能**
  - Email/密碼登入
  - 記住我功能（7天/30天選項）
  - 登入失敗次數限制（5次後鎖定15分鐘）
  - 顯示上次登入時間和IP

- **忘記密碼**
  - 輸入 Email 發送重設連結
  - 重設連結有效期（1小時）
  - 密碼重設成功通知
  - 安全問題驗證（可選）

- **Session 管理**
  - JWT Token（Access Token: 15分鐘，Refresh Token: 7天）
  - 自動更新 Token
  - 多裝置登入管理
  - 強制登出所有裝置選項

### 1.2 AI 詞卡生成

#### 1.2.1 輸入處理
- **文字輸入**
  - 支援格式：純文字、SRT字幕、劇本格式
  - 字數限制：單次最多5000字
  - 自動語言檢測（英文）
  - 保留上下文理解

- **主題模式**
  - 預設主題：
    - 日常對話（Daily Conversation）
    - 商務英語（Business English）
    - 美劇經典（TV Series Classics）
    - 電影台詞（Movie Quotes）
    - 學術英語（Academic English）
  - 自定義主題輸入
  - 難度選擇：A1, A2, B1, B2, C1, C2

#### 1.2.2 AI 生成規格
- **原始例句輸入**
  - 輸入方式
    1. 手動輸入
  - 輸入資料
    - 可接受多句子
    - 字數限制規則：限定300字以內

- **例句分析**
    - 用戶輸入句子後，AI進行以下分析
      - 例句語法校正
      - 例句中文翻譯
      - 例句單字分析
      - 例句慣用語分析

  1. 點擊查詢體驗
    - 句子顯示為可點擊的單字
    - 點擊對象
      - 若為高價值標記，則即時顯示意思（無延遲，讀取預分析資料），不扣除使用次數
      - 若非高價值標記，則拿當前點擊單字及當前句子，給AI分析並生成內容詳情，扣除使用次數一次
    - 片語/俚語特殊高亮顯示
      - 智能提醒：當單字屬於片語/俚語時，優先顯示片語意思並提醒
      - 若出現多筆片語/俚語需標記時，請使用不同顏色區分

  2. 成本優化策略
    - **核心原則**：一句一次 API 調用，多次查詢零成本
    - 相同句子分析結果快取（24小時）
    - 常用單字基礎資訊本地快取
    - 預估 API 成本降低 80-95%
  
  3. 收費策略(phase 2)：
    - 免費用戶：5次/3小時
    - 付費用戶：無限制

- **生成內容詳情**
  - **原始例句**
    - 整體意思：不論原始例句是多句、一句、片段，就是將原始例句整體意思描述出來
    - 修正語法錯誤：若原始例句有語法錯誤，則進行修正，並說明修正原因，且後續學習內容皆以正確的版本進行

  - **單字/片語**
    - 原形展示
    - 詞性標註（noun/verb/adjective/adverb/pronoun/preposition/conjunction/interjection）
    - 英文定義 (程度應維持在A1-A2)
    - 同義詞（最多3個且程度應維持在A1-A2）

  - **翻譯**
    - 繁體中文翻譯

  - **發音**
    - IPA 國際音標
    - 美式發音
    - 音頻播放（整合 TTS）

  - **例句**
    - 原始例句（來自輸入文本）
    - 生成例句（1個）
    - 例句中文翻譯
    - 重點標示（highlight目標詞）
    - 例句圖
    - 例句發音

- **生成後處理**
  - 預覽所有生成詞卡
  - 單個詞卡編輯/刪除
  - 重新生成選項
  - 批量保存到卡組

### 1.3 詞卡管理

#### 1.3.1 卡組管理
- **卡組 CRUD**
  - 創建卡組（名稱、描述、封面圖）
  - 編輯卡組資訊
  - 刪除卡組（需二次確認）
  - 複製卡組
  - 卡組排序（創建時間/名稱/詞卡數量）

- **卡組類型**
  - 個人卡組（私有）
  - 共享卡組（公開，未來功能）
  - 系統卡組（官方提供）

#### 1.3.2 詞卡操作
- **新增詞卡**
  - 手動創建（填寫表單）
  - 從 AI 生成添加
  - 批量導入（CSV/JSON）
  - 快速添加模式

- **編輯詞卡**
  - 編輯所有欄位
  - 富文本編輯器（例句）
  - 圖片上傳（記憶圖像）
  - 音頻錄製（自定義發音）

- **刪除詞卡**
  - 單個刪除（滑動/右鍵）
  - 批量刪除（多選）
  - 軟刪除（回收站，30天內可恢復）

- **批量操作**
  - 批量移動到其他卡組
  - 批量添加標籤
  - 批量重設學習進度
  - 批量導出

- **智能檢測**
  - 單一詞彙檢測
    - 全面檢查指定詞彙所有內容是否有問題，並修正錯誤內容
    - 點擊指定內容進行檢查，並修正錯誤內容
  - 錯誤清單一鍵檢測
    - 點擊後及針對當前錯誤回報系統中清單進行檢測，一一修正錯誤內容

#### 1.3.3 組織功能
- **標籤系統**
  - 預設標籤（動詞、名詞、片語、俚語等）
  - 自定義標籤（最多10個/詞卡）
  - 標籤顏色自定義
  - 標籤批量管理

- **收藏功能**
  - 一鍵收藏/取消收藏
  - 收藏夾分類
  - 快速訪問收藏詞卡

- **搜尋篩選**
  - 全文搜尋（單字、翻譯、例句）
  - 按標籤篩選
  - 按難度篩選
  - 按學習狀態篩選（新詞/學習中/已掌握）
  - 組合篩選條件

### 1.4 複習系統

#### 1.4.1 間隔重複算法（SM-2）
- **算法參數**
  - 初始間隔：2^0天、2^1天...依此類推
  - 難度係數：0.8-2.5
  - 最小間隔：1天
  - 最大間隔：365天

- **評分及間隔時間**
  - 1分：完全不記得（重置進度）
  - 2分：有印象但錯誤（間隔×0.6）
  - 3分：困難但正確（間隔×0.8）
  - 4分：猶豫後正確（間隔×1.0）
  - 5分：輕鬆正確（間隔×1.3）

- **複習排程**
  - 每日複習上限設定（預設50個）
  - 優先級排序（過期天數）
  - 智能分散（避免同時大量到期）

#### 1.4.2 學習模式
- **翻卡模式**
  - 正面：英文詞彙
  - 背面：英文定義、例句、發音、例句圖
  - 手勢操作：左滑（不記得）、右滑（記得）、上滑（收藏）
  - 鍵盤快捷鍵支援

- **測驗模式**
  - 選擇題（題目是英文定義，答案中文翻譯4選1）
  - 填空題
    - 題目是顯示例句圖和挖空的例句
    - 點擊提示，會出現詞彙的英文定義
    - 答案就是詞彙，但是不是原型，而是例句挖空的部分
  - 拼寫測試 (phase 2)
  - 聽力測試（聽音選詞）
  - 口說測試 (念例句)

- **錯誤回報**
  - 翻卡模式及所有測驗模式，都要設定錯誤回報
  - 點擊錯誤回報後，可以輸入錯誤原因，可以不填寫直接送出

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

#### 1.4.3 複習設定
- **提醒功能**
  - 每日提醒時間設定
  - 推送通知（瀏覽器/Email）
  - 連續學習天數追蹤
  - 複習債務提醒

- **個人化設定**
  - 每日目標詞數
  - 學習時段偏好
  - 難度調整（激進/保守）
  - 音效開關

### 1.5 數據分析

#### 1.5.1 學習統計
- **基礎數據**
  - 總學習詞彙數
  - 今日學習時間
  - 連續學習天數
  - 本週/本月學習時間
  - 平均每日學習詞數

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

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

- **成就系統**
  - 里程碑徽章（100/500/1000詞）
  - 連續學習徽章（7/30/100天）
  - 特殊成就（完美週/月）
  - 等級系統（經驗值）
  - 排行榜（未來功能）

#### 1.5.3 報告導出
- **導出格式**
  - PDF 學習報告
  - Excel 數據表
  - 圖表圖片

- **報告內容**
  - 學習總結
  - 詞彙清單
  - 進步分析
  - 學習建議

## 2. 用戶介面需求

### 2.1 頁面結構
- **首頁（未登入）**
  - 產品介紹
  - 功能展示
  - 價格方案
  - 註冊/登入入口

- **Dashboard（已登入）**
  - 今日學習任務卡片
  - 快速操作按鈕（生成詞卡/開始學習）
  - 學習進度概覽
  - 最近學習的詞卡

- **詞卡頁面**
  - 卡組列表視圖（網格/列表切換）
  - 詞卡詳情視圖
  - 批量操作工具欄
  - 篩選器側邊欄

- **學習頁面**
  - 全螢幕學習界面
  - 進度條顯示
  - 操作按鈕區
  - 設定面板

- **個人中心**
  - 個人資料編輯
  - 學習設定
  - 數據統計
  - 帳號安全

### 2.2 響應式設計
- **桌面版（>1024px）**
  - 三欄布局（側邊欄+主內容+右側面板）
  - 懸浮操作按鈕
  - 鍵盤快捷鍵支援

- **平板版（768-1024px）**
  - 兩欄布局
  - 可收縮側邊欄
  - 觸控優化

- **手機版（<768px）**
  - 單欄布局
  - 底部導航欄
  - 手勢操作
  - 大按鈕設計

## 3. 技術規格需求

### 3.1 前端技術
- **框架**：Next.js 14 (App Router)
- **語言**：TypeScript
- **樣式**：Tailwind CSS + shadcn/ui
- **狀態管理**：Zustand
- **數據獲取**：TanStack Query
- **表單**：React Hook Form + Zod

### 3.2 後端技術
- **API**：Next.js API Routes
- **資料庫**：Supabase (PostgreSQL)
- **認證**：NextAuth.js
- **AI**：Google Gemini API
- **文件存儲**：Supabase Storage
- **快取**：Redis (Upstash)

### 3.3 第三方服務
- **Email**：Resend/SendGrid
- **分析**：Google Analytics
- **錯誤追蹤**：Sentry
- **CDN**：Vercel Edge Network

## 4. 非功能性需求

### 4.1 效能需求
- **載入速度**
  - FCP < 1.8秒
  - LCP < 2.5秒
  - TTI < 3.8秒
  - CLS < 0.1

- **API 效能**
  - 一般 API < 200ms
  - AI 生成 < 3秒
  - 資料庫查詢 < 100ms

- **容量需求**
  - 支援單用戶 10,000+ 詞卡
  - 支援 100+ 卡組
  - 並發用戶 1000+

### 4.2 可用性需求
- **瀏覽器支援**
  - Chrome 90+
  - Safari 14+
  - Firefox 88+
  - Edge 90+

- **無障礙性**
  - WCAG 2.1 AA 標準
  - 鍵盤導航
  - 螢幕閱讀器支援
  - 高對比模式

- **國際化**
  - 繁體中文（預設）
  - 英文介面
  - 日期/時間本地化

### 4.3 安全需求
- **認證安全**
  - 密碼加密（bcrypt）
  - JWT Token 管理
  - Session 超時控制
  - 2FA（未來功能）

- **數據安全**
  - HTTPS only
  - XSS 防護
  - CSRF Token
  - SQL Injection 防護
  - Rate Limiting

- **隱私保護**
  - GDPR 合規
  - 數據加密存儲
  - 用戶數據導出
  - 帳號刪除功能

### 4.4 可靠性需求
- **可用性**：99.9% uptime
- **備份**：每日自動備份
- **災難恢復**：RTO < 4小時，RPO < 1小時
- **錯誤處理**：優雅降級，友善錯誤提示

## 5. 開發階段劃分

### Phase 1 - MVP（第1-2週）
**目標**：基礎功能可用
- ✅ 用戶註冊/登入（Email only）
- ✅ AI 詞卡生成（基礎版）
- ✅ 詞卡 CRUD
- ✅ 簡單翻卡學習
- ✅ 基礎 UI

### Phase 2 - 核心功能（第3-4週）
**目標**：完整學習流程
- ✅ Google OAuth
- ✅ 卡組管理
- ✅ SM-2 算法實現
- ✅ 學習模式（翻卡+測驗）
- ✅ 基礎統計
- ✅ 響應式設計

### Phase 3 - 增強功能（第5-6週）
**目標**：提升用戶體驗
- ✅ 標籤系統
- ✅ 搜尋篩選
- ⬜ **互動式單字查詢系統**
  - 句子預分析 API 端點
  - 可點擊文字組件
  - 片語/俚語智能提醒
  - 快取機制實現
- ✅ 進階統計圖表
- ✅ 成就系統
- ✅ 學習提醒
- ✅ 性能優化

### Phase 4 - 商業化準備（第7-8週）
**目標**：準備上線
- ⬜ 付費方案
- ⬜ 用戶反饋系統
- ⬜ 管理後台
- ⬜ 數據分析
- ⬜ A/B 測試

## 6. 驗收標準

### 6.1 功能驗收
- 所有 P0 功能完整實現
- 通過所有功能測試用例
- 無阻塞性 Bug

### 6.2 性能驗收
- Lighthouse 分數 > 90
- 所有頁面載入 < 3秒
- API 響應時間符合規格

### 6.3 品質驗收
- 代碼覆蓋率 > 80%
- 無安全漏洞（通過安全掃描）
- UI/UX 審查通過

## 7. 風險與限制

### 7.1 技術風險
- Gemini API 配額限制
- Supabase 免費層限制
- 第三方服務依賴

### 7.2 業務風險
- 競品競爭
- 用戶獲取成本
- 內容版權問題

### 7.3 緩解措施
- 實施 API 快取機制（重點：單字查詢預分析快取）
- 準備備用 AI 服務
- 建立用戶反饋循環
- 確保內容合規性
- 監控 AI API 使用量並設定預算警告
- 實現降級機制：API 配額用盡時使用離線字典