dramaling-vocab-learning/docs/01_requirement/functional-requirements.md

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 配額用盡時使用離線字典