20 KiB

Raw Blame History

DramaLing 詞卡管理功能產品需求規格書

1. 概述

1.1 文檔目的

本文檔定義了 DramaLing 詞卡管理功能的詳細產品需求規格，涵蓋詞卡的創建、編輯、組織、搜尋、篩選和管理等核心功能。

1.2 功能簡介

詞卡管理是 DramaLing 的核心功能之一，為用戶提供完整的詞卡生命週期管理，包括：

📝 詞卡新增與編輯
🔍 智能搜尋與篩選
⭐ 收藏與分類管理
📊 學習進度追蹤
🔄 批量操作功能

2. 用戶需求分析

2.1 用戶角色定義

2.1.1 主要用戶

英語學習者: 使用 DramaLing 學習英語詞彙的用戶
目標: 有效管理和學習英語詞彙，提升英語水平
技能水平: 具備基本的電腦操作能力，英語水平從初學者到高級

2.1.2 用戶畫像

年齡: 16-45歲
職業: 學生、上班族、語言學習愛好者
使用場景: 通勤時間、休息時間、專門的學習時段
設備: 手機、平板、電腦
學習目標: 考試準備、工作需要、興趣提升

2.2 用戶故事 (User Stories)

2.2.1 詞卡檢視與瀏覽

作為一個英語學習者，
我想要瀏覽我所有的詞卡，
這樣我可以回顧我已經學習的詞彙。

驗收標準：
- 我可以看到詞卡列表，包含詞彙、翻譯、例句圖片
- 每個詞卡顯示 CEFR 難度等級和掌握度
- 我可以在「所有詞卡」和「收藏詞卡」之間切換
- 詞卡按創建時間排序顯示

2.2.2 詞卡搜尋與篩選

作為一個英語學習者，
我想要快速找到特定的詞卡，
這樣我可以有效地複習特定的詞彙。

驗收標準：
- 我可以透過搜尋框輸入關鍵字搜尋詞彙、翻譯或定義
- 我可以使用進階篩選按 CEFR 等級、詞性、掌握度篩選
- 我可以使用快速篩選按鈕找到需要加強的詞卡
- 搜尋結果會高亮顯示關鍵字，並顯示找到的詞卡數量

2.2.3 詞卡收藏管理

作為一個英語學習者，
我想要標記重要的詞卡為收藏，
這樣我可以優先複習重要的詞彙。

驗收標準：
- 我可以點擊星星圖標將詞卡加入收藏
- 已收藏的詞卡會顯示實心黃色星星
- 我可以在收藏分頁中查看所有收藏的詞卡
- 我可以隨時取消收藏某個詞卡

2.2.4 詞卡編輯與管理

作為一個英語學習者，
我想要編輯或刪除詞卡，
這樣我可以更正錯誤或移除不需要的詞卡。

驗收標準：
- 我可以點擊編輯按鈕修改詞卡的任何欄位
- 我可以刪除不需要的詞卡，系統會要求確認
- 編輯後的詞卡會立即更新並保存
- 刪除操作會顯示成功或失敗的回饋訊息

2.2.5 詞卡創建

作為一個英語學習者，
我想要手動創建新的詞卡，
這樣我可以將遇到的新詞彙加入學習列表。

驗收標準：
- 我可以點擊「新增詞卡」按鈕開啟創建表單
- 我可以填寫詞彙、翻譯、定義、發音、詞性、例句等欄位
- 提交後新詞卡會出現在詞卡列表中
- 如果有錯誤，系統會顯示明確的錯誤訊息

2.2.6 詞卡詳細檢視

作為一個英語學習者，
我想要查看詞卡的完整詳細資訊，
這樣我可以深入了解詞彙的各種用法和學習狀態。

驗收標準：
- 我可以點擊「詳細」按鈕進入詞卡詳細頁面
- 詳細頁面顯示所有詞卡信息和學習統計
- 我可以在詳細頁面進行編輯或收藏操作
- 我可以查看學習記錄和複習歷史

2.3 用戶流程 (User Flows)

2.3.1 詞卡瀏覽流程

用戶進入詞卡頁面 → 查看詞卡列表 → 選擇分頁(所有詞卡/收藏詞卡) → 瀏覽詞卡
                                    ↓
用戶可以執行以下操作：
- 點擊收藏/取消收藏
- 點擊編輯進入編輯模式
- 點擊刪除(需確認)
- 點擊詳細查看完整信息
- 點擊發音按鈕播放音頻

2.3.2 詞卡搜尋流程

用戶進入詞卡頁面 → 點擊搜尋框 → 輸入關鍵字 → 查看即時篩選結果
                                    ↓
用戶可以進一步操作：
- 點擊「進階篩選」設定更多條件
- 使用快速篩選按鈕
- 清除搜尋條件
- 對搜尋結果執行詞卡操作

2.3.3 詞卡創建流程

用戶進入詞卡頁面 → 點擊「新增詞卡」按鈕 → 填寫詞卡表單 → 點擊保存
                                        ↓
表單驗證：
- 成功：新詞卡出現在列表中，顯示成功訊息
- 失敗：顯示錯誤訊息，保持表單開啟狀態

2.3.4 詞卡編輯流程

用戶選擇詞卡 → 點擊「編輯」按鈕 → 修改詞卡欄位 → 點擊保存
                                ↓
編輯驗證：
- 成功：詞卡更新，顯示成功訊息，關閉編輯表單
- 失敗：顯示錯誤訊息，保持編輯模式

2.3.5 詞卡刪除流程

用戶選擇詞卡 → 點擊「刪除」按鈕 → 確認刪除對話框 → 用戶確認
                                ↓
刪除處理：
- 成功：詞卡從列表中移除，顯示成功訊息
- 失敗：顯示錯誤訊息，詞卡保持在列表中

2.3.6 詞卡收藏管理流程

用戶瀏覽詞卡 → 點擊星星圖標 → 切換收藏狀態
                        ↓
收藏狀態更新：
- 加入收藏：星星變為實心黃色，顯示成功訊息
- 取消收藏：星星變為空心灰色，顯示成功訊息
- 在收藏分頁中即時更新詞卡列表

2.3.7 AI 生成詞卡流程 (與其他頁面整合)

用戶在詞卡頁面 → 點擊「AI 生成詞卡」按鈕 → 跳轉到 /generate 頁面
                                          ↓
AI 分析流程：
用戶輸入句子 → AI 分析 → 查看分析結果 → 點擊保存詞卡 → 返回詞卡頁面查看

2.4 用戶體驗目標

2.4.1 易用性目標

直觀操作: 新用戶在 5 分鐘內能完成基本詞卡操作
快速搜尋: 搜尋結果在 300ms 內顯示
清楚回饋: 所有操作都有明確的成功/失敗回饋
一致設計: 整個詞卡管理流程保持視覺和交互一致性

2.4.2 效率目標

批量操作: 支援多選和批量操作(未來功能)
鍵盤快捷鍵: 支援 ESC 清除搜尋等常用快捷鍵
智能提示: 搜尋框提供輸入建議(未來功能)
離線功能: 基本瀏覽功能支援離線使用(未來功能)

3. 功能需求分析

3.1 核心功能模組

3.1.1 詞卡展示頁面 (FlashcardsPage)

位置: /flashcards
主要功能: 集中管理和展示所有詞卡

頁面佈局設計

頁面標題區域
- 顯示 "我的詞卡" 標題
- 新增詞卡按鈕 (手動創建)
- AI 生成詞卡按鈕 (跳轉至 /generate)
分頁標籤系統
- 所有詞卡: 顯示用戶全部詞卡 (顯示詞卡總數)
- 收藏詞卡: 顯示已收藏的詞卡 (顯示收藏總數，⭐ 圖標)
搜尋與篩選區域
- 主要搜尋框：支援詞彙、翻譯、定義的全文搜尋
- 進階篩選選項 (可展開/收起)
- 快速篩選按鈕組
- 搜尋結果統計

2.1.2 詞卡顯示格式

每個詞卡採用橫向卡片佈局，包含：

左側區域

例句圖片: 54x36 像素，展示詞彙使用情境
詞彙信息:
- 詞彙本身 (大字體粗體顯示)
- 詞性標籤 (noun, verb, adjective 等)
- 中文翻譯 (中等字體)
- 發音符號與播放按鈕

右上角

CEFR 難度標籤: A1-C2 等級，使用顏色區分
- A1: 綠色 (基礎)
- A2: 藍色 (基礎)
- B1: 黃色 (中級)
- B2: 橙色 (中高級)
- C1: 紅色 (高級)
- C2: 紫色 (精通)

右側操作區域

收藏按鈕: 星星圖標，已收藏顯示黃色實心
編輯按鈕: 編輯圖標，開啟編輯表單
刪除按鈕: 垃圾桶圖標，需二次確認
詳細按鈕: 箭頭圖標，導航至詞卡詳細頁面

底部統計信息

創建日期
掌握度百分比

2.2 搜尋與篩選功能

2.2.1 主要搜尋功能

// 搜尋範圍
- 詞彙本身 (word)
- 中文翻譯 (translation)
- 英文定義 (definition)
- 例句內容 (example)

搜尋增強功能

即時搜尋: 輸入時即時過濾結果
高亮顯示: 搜尋關鍵字在結果中高亮標示
清除功能: 一鍵清除搜尋條件 (ESC 鍵或 X 按鈕)
結果統計: 顯示找到的詞卡數量

2.2.2 進階篩選選項

CEFR 等級篩選

enum CEFRLevel {
  A1 = "A1 - 基礎",
  A2 = "A2 - 基礎",
  B1 = "B1 - 中級",
  B2 = "B2 - 中高級",
  C1 = "C1 - 高級",
  C2 = "C2 - 精通"
}

詞性篩選

enum PartOfSpeech {
  noun = "名詞 (noun)",
  verb = "動詞 (verb)",
  adjective = "形容詞 (adjective)",
  adverb = "副詞 (adverb)",
  preposition = "介詞 (preposition)",
  interjection = "感嘆詞 (interjection)"
}

掌握程度篩選

enum MasteryLevel {
  high = "已熟練 (80%+)",     // >= 80%
  medium = "學習中 (60-79%)", // 60-79%
  low = "需加強 (<60%)"       // < 60%
}

收藏狀態篩選

檢查框選項："僅顯示收藏詞卡"
與星星圖標配合顯示

2.2.3 快速篩選按鈕

提供常用篩選組合的快速按鈕：

需加強詞卡: 自動設定掌握度 < 60%
收藏詞卡: 自動篩選收藏項目
高級詞彙: 自動設定 CEFR 等級為 C1/C2
清除全部: 重置所有篩選條件

2.3 詞卡操作功能

2.3.1 CRUD 操作

新增詞卡

觸發方式:
- 手動新增按鈕 (開啟表單)
- AI 生成詞卡 (從 /generate 頁面)
- 批量導入 (未來功能)

編輯詞卡

可編輯欄位:

interface EditableFlashcard {
  word: string;           // 詞彙
  translation: string;    // 中文翻譯
  definition: string;     // 英文定義
  pronunciation: string;  // 發音符號
  partOfSpeech: string;   // 詞性
  example: string;        // 例句
  difficultyLevel: string; // CEFR 等級
}

刪除詞卡

安全機制:
- 二次確認對話框
- 顯示詞彙名稱確認
- 軟刪除機制 (可恢復，未來功能)

2.3.2 收藏功能

收藏狀態切換: 點擊星星圖標
視覺反饋:
- 未收藏: 灰色空心星星
- 已收藏: 黃色實心星星
操作反饋: 顯示操作成功/失敗訊息
收藏統計: 在收藏分頁顯示總數

2.3.3 詞卡詳細頁面

導航路徑: /flashcards/[id]
顯示內容:
- 完整詞卡信息
- 學習記錄統計
- 複習歷史
- 錯誤回報記錄

2.4 學習進度管理

2.4.1 掌握度系統

interface MasteryTracking {
  masteryLevel: number;      // 0-100% 掌握度
  timesReviewed: number;     // 複習次數
  nextReviewDate: string;    // 下次複習日期
  lastReviewDate?: string;   // 上次複習日期
  consecutiveCorrect: number; // 連續答對次數
}

2.4.2 學習狀態指示

掌握度顏色編碼:
- < 60%: 紅色 (需加強)
- 60-79%: 黃色 (學習中)
- = 80%: 綠色 (已熟練)

2.5 資料結構定義

2.5.1 詞卡核心資料結構

interface Flashcard {
  // 基本識別信息
  id: string;                    // 唯一識別碼
  createdAt: string;             // 創建時間
  updatedAt?: string;            // 更新時間

  // 詞彙基本信息
  word: string;                  // 詞彙本身
  translation: string;           // 中文翻譯
  definition: string;            // 英文定義
  pronunciation: string;         // 發音符號 (IPA)
  partOfSpeech: string;          // 詞性

  // 學習相關
  example: string;               // 例句
  exampleTranslation?: string;   // 例句翻譯
  difficultyLevel: string;       // CEFR 難度等級

  // 學習追蹤
  masteryLevel: number;          // 掌握度 (0-100)
  timesReviewed: number;         // 複習次數
  nextReviewDate: string;        // 下次複習日期

  // 用戶偏好
  isFavorite: boolean;           // 是否收藏
}

2.5.2 API 服務結構

class FlashcardsService {
  // 查詢操作
  getFlashcards(search?: string, favoritesOnly?: boolean): Promise<ApiResponse<{flashcards: Flashcard[], count: number}>>
  getFlashcard(id: string): Promise<ApiResponse<Flashcard>>

  // 修改操作
  createFlashcard(data: CreateFlashcardRequest): Promise<ApiResponse<Flashcard>>
  updateFlashcard(id: string, data: CreateFlashcardRequest): Promise<ApiResponse<Flashcard>>
  deleteFlashcard(id: string): Promise<ApiResponse<void>>

  // 特殊操作
  toggleFavorite(id: string): Promise<ApiResponse<void>>
}

3. 用戶介面規格

3.1 響應式設計要求

3.1.1 桌面版 (>1024px)

詞卡列表：單欄佈局，每個詞卡橫向顯示
搜尋區域：完整展示所有篩選選項
操作按鈕：完整文字標籤

3.1.2 平板版 (768-1024px)

詞卡圖片：適度縮小但保持清晰
篩選選項：可收縮式設計
操作按鈕：保持圖標+文字

3.1.3 手機版 (<768px)

詞卡佈局：調整為垂直堆疊
搜尋功能：優先顯示主搜尋框
操作按鈕：僅顯示圖標，提供 tooltip

3.2 互動設計規範

3.2.1 狀態回饋

載入狀態: 顯示 "載入中..." 提示
空狀態: 友善的空狀態提示 + 引導操作
錯誤狀態: 清楚的錯誤信息 + 重試選項

3.2.2 操作回饋

成功操作: 綠色提示訊息，自動消失
失敗操作: 紅色錯誤訊息，需手動關閉
確認操作: 模態對話框，清楚的確認/取消選項

3.3 可訪問性要求

鍵盤導航: 支援 Tab/Enter/Escape 鍵操作
螢幕閱讀器: 適當的 ARIA 標籤和角色
對比度: 符合 WCAG 2.1 AA 標準
文字大小: 支援縮放至 200% 而不影響功能

4. 技術約束與架構

📋 架構文檔引用

本功能需求必須遵循既有的系統架構，完整技術規格請參考：

系統架構總覽

後端架構詳細說明

前端架構詳細說明

詞卡 API 規格

4.1 技術架構約束

前端技術限制

框架: 必須使用 Next.js 15 with App Router
語言: 必須使用 TypeScript
樣式: 必須使用 Tailwind CSS
狀態管理: 使用 React hooks (useState/useEffect)
API 通信: 使用現有的 flashcardsService

後端技術限制

框架: 必須使用 ASP.NET Core 8.0
資料庫: 必須使用 SQLite + Entity Framework Core
API 格式: 必須遵循現有的 RESTful API 設計
認證: 必須相容現有的 JWT 認證機制

資料模型約束

詞卡模型: 必須使用現有的 Flashcard.cs 實體
API 回應: 必須遵循 {success, data?, error?} 格式
關聯設計: 必須保持與 User、CardSet 的現有關聯

4.2 資料處理流程

4.2.1 詞卡載入流程

// 載入流程
loadFlashcards() -> flashcardsService.getFlashcards() -> setFlashcards(data)

// 錯誤處理
catch(error) -> setError(message) -> 顯示錯誤狀態

4.2.2 搜尋篩選流程

// 即時篩選
filteredCards = allCards.filter(card => {
  // 文字搜尋
  matchesText = word/translation/definition 包含關鍵字

  // 篩選條件
  matchesCEFR = 符合CEFR等級篩選
  matchesPartOfSpeech = 符合詞性篩選
  matchesMastery = 符合掌握度篩選
  matchesFavorite = 符合收藏狀態篩選

  return matchesText && matchesCEFR && ...
})

4.3 效能優化策略

4.3.1 資料載入優化

分頁載入: 避免一次載入過多詞卡
快取機制: 本地快取搜尋結果
延遲載入: 圖片使用 lazy loading

4.3.2 搜尋效能優化

防抖處理: 搜尋輸入 300ms 延遲
索引優化: 預處理搜尋索引
記憶化: 使用 useMemo 快取篩選結果

5. 資料存儲規格

5.1 後端 API 端點

GET    /api/flashcards              # 取得詞卡列表
GET    /api/flashcards/{id}         # 取得單一詞卡
POST   /api/flashcards              # 創建新詞卡
PUT    /api/flashcards/{id}         # 更新詞卡
DELETE /api/flashcards/{id}         # 刪除詞卡
POST   /api/flashcards/{id}/favorite # 切換收藏狀態

5.2 資料庫結構 (SQLite)

CREATE TABLE flashcards (
  id TEXT PRIMARY KEY,
  user_id TEXT NOT NULL,
  word TEXT NOT NULL,
  translation TEXT NOT NULL,
  definition TEXT NOT NULL,
  pronunciation TEXT,
  part_of_speech TEXT,
  example TEXT,
  example_translation TEXT,
  difficulty_level TEXT,
  mastery_level INTEGER DEFAULT 0,
  times_reviewed INTEGER DEFAULT 0,
  is_favorite BOOLEAN DEFAULT FALSE,
  next_review_date TEXT,
  created_at TEXT NOT NULL,
  updated_at TEXT,

  FOREIGN KEY (user_id) REFERENCES users(id)
);

6. 測試規格

6.1 功能測試用例

6.1.1 詞卡顯示測試

詞卡列表正確載入和顯示
CEFR 等級顏色正確顯示
收藏狀態正確顯示
掌握度百分比正確顯示

6.1.2 搜尋功能測試

文字搜尋功能正常
搜尋結果高亮顯示
進階篩選功能正常
快速篩選按鈕功能正常
清除篩選功能正常

6.1.3 詞卡操作測試

新增詞卡功能正常
編輯詞卡功能正常
刪除詞卡功能正常 (包含二次確認)
收藏切換功能正常
詳細頁面導航正常

6.2 效能測試要求

1000+ 詞卡載入時間 < 2秒
搜尋響應時間 < 300ms
篩選操作響應時間 < 100ms
記憶體使用合理 (< 100MB)

6.3 可用性測試要求

新用戶能在 5 分鐘內完成基本操作
搜尋功能直觀易用
錯誤訊息清楚明確
空狀態引導有效

7. 未來功能規劃

7.1 短期功能 (1-2個月)

批量操作: 多選詞卡進行批量刪除、編輯
標籤系統: 自定義標籤分類詞卡
排序功能: 按創建時間、掌握度、複習頻率排序
匯入匯出: CSV/JSON 格式的詞卡匯入匯出

7.2 中期功能 (3-6個月)

智能推薦: 基於學習進度推薦複習詞卡
學習統計: 詳細的學習進度圖表分析
協作功能: 詞卡分享和協作編輯
離線功能: 離線瀏覽和學習詞卡

7.3 長期功能 (6個月+)

AI 輔助: 智能錯誤檢測和內容優化建議
多媒體支援: 音訊、影片例句
社群功能: 公共詞卡庫和評分系統
API 開放: 第三方整合 API

8. 成功指標

8.1 功能完成度指標

所有核心功能 100% 實現
所有測試用例 100% 通過
零阻塞性 Bug

8.2 用戶體驗指標

詞卡載入時間 < 2秒
搜尋響應時間 < 300ms
用戶操作成功率 > 95%
錯誤恢復時間 < 5秒

8.3 業務指標

用戶詞卡創建數量增長
搜尋功能使用頻率
收藏功能使用率
用戶留存率提升

文檔版本: v1.0 最後更新: 2025-09-24 文檔狀態: 待審核 負責人: AI Assistant 審核人: 待指定

20 KiB Raw Blame History