jettcheng1018
/
dramaling-vocab-learning
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: 簡化星星標記提示文字並新增詞卡管理功能產品需求規格 

- 簡化星星標記說明為「⭐ 為常用高頻詞彙，建議優先學習！」
- 修復 generate 頁面 TypeScript 錯誤：新增 compareCEFRLevels 函數
- 修復慣用語星星顯示邏輯中的 userLevel 變數問題
- 新增詳細的詞卡管理功能產品需求規格書，涵蓋：
  * 完整的功能模組分析和UI/UX設計規格
  * 搜尋與篩選系統的詳細實現規格
  * CRUD操作流程和技術架構定義
  * 響應式設計要求和可訪問性標準
  * 測試用例規格和未來功能規劃

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
鄭沛軒 2025-09-24 03:01:12 +08:00
parent 8d85366a45
commit 7f85c79bc3
2 changed files with 467 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
frontend/app/generate/page.tsx
View File

@ -25,6 +25,21 @@ const getTargetLearningRange = (userLevel: string): string => {
return ranges[userLevel] || 'B1-B2'
}
const compareCEFRLevels = (level1: string, level2: string, operator: '>' | '<' | '==='): boolean => {
const levels = ['A1', 'A2', 'B1', 'B2', 'C1', 'C2']
const index1 = levels.indexOf(level1)
const index2 = levels.indexOf(level2)
if (index1 === -1 || index2 === -1) return false
switch (operator) {
case '>': return index1 > index2
case '<': return index1 < index2
case '===': return index1 === index2
default: return false
}
}
interface GrammarCorrection {
hasErrors: boolean;
originalText: string;
@ -333,10 +348,7 @@ function GenerateContent() {
<div className="bg-yellow-50 border border-yellow-200 rounded-lg p-3 mb-6">
<div className="flex items-center gap-2 text-sm text-yellow-800">
<span className="text-yellow-500 text-base">⭐</span>
<span className="font-medium">重點提示：</span>
標有星星的詞彙和慣用語是
<strong className="text-yellow-900">常用、高頻詞彙</strong>
，建議優先學習和保存到詞卡庫！
<span className="font-medium">⭐ 為常用高頻詞彙，建議優先學習！</span>
</div>
</div>
@ -469,6 +481,7 @@ function GenerateContent() {
{(() => {
// 只有當慣用語為常用且不是簡單慣用語時才顯示星星
// 簡單慣用語定義：學習者CEFR > 慣用語CEFR
const userLevel = localStorage.getItem('userEnglishLevel') || 'A2'
const isHighFrequency = idiom?.frequency === 'high'
const idiomCefr = idiom?.cefrLevel || 'A1'
const isNotSimpleIdiom = !compareCEFRLevels(userLevel, idiomCefr, '>')

450
詞卡管理功能產品需求規格.md Normal file
View File

@ -0,0 +1,450 @@
# DramaLing 詞卡管理功能產品需求規格書
## 1. 概述
### 1.1 文檔目的
本文檔定義了 DramaLing 詞卡管理功能的詳細產品需求規格，涵蓋詞卡的創建、編輯、組織、搜尋、篩選和管理等核心功能。
### 1.2 功能簡介
詞卡管理是 DramaLing 的核心功能之一，為用戶提供完整的詞卡生命週期管理，包括：
- 📝 詞卡新增與編輯
- 🔍 智能搜尋與篩選
- ⭐ 收藏與分類管理
- 📊 學習進度追蹤
- 🔄 批量操作功能
## 2. 功能需求分析
### 2.1 核心功能模組
#### 2.1.1 詞卡展示頁面 (FlashcardsPage)
- **位置**: `/flashcards`
- **主要功能**: 集中管理和展示所有詞卡
##### 頁面佈局設計
1. **頁面標題區域**
- 顯示 "我的詞卡" 標題
- 新增詞卡按鈕 (手動創建)
- AI 生成詞卡按鈕 (跳轉至 `/generate`)
2. **分頁標籤系統**
- **所有詞卡**: 顯示用戶全部詞卡 (顯示詞卡總數)
- **收藏詞卡**: 顯示已收藏的詞卡 (顯示收藏總數，⭐ 圖標)
3. **搜尋與篩選區域**
- 主要搜尋框：支援詞彙、翻譯、定義的全文搜尋
- 進階篩選選項 (可展開/收起)
- 快速篩選按鈕組
- 搜尋結果統計
#### 2.1.2 詞卡顯示格式
每個詞卡採用橫向卡片佈局，包含：
##### 左側區域
- **例句圖片**: 54x36 像素，展示詞彙使用情境
- **詞彙信息**:
- 詞彙本身 (大字體粗體顯示)
- 詞性標籤 (noun, verb, adjective 等)
- 中文翻譯 (中等字體)
- 發音符號與播放按鈕
##### 右上角
- **CEFR 難度標籤**: A1-C2 等級，使用顏色區分
- A1: 綠色 (基礎)
- A2: 藍色 (基礎)
- B1: 黃色 (中級)
- B2: 橙色 (中高級)
- C1: 紅色 (高級)
- C2: 紫色 (精通)
##### 右側操作區域
- **收藏按鈕**: 星星圖標，已收藏顯示黃色實心
- **編輯按鈕**: 編輯圖標，開啟編輯表單
- **刪除按鈕**: 垃圾桶圖標，需二次確認
- **詳細按鈕**: 箭頭圖標，導航至詞卡詳細頁面
##### 底部統計信息
- 創建日期
- 掌握度百分比
### 2.2 搜尋與篩選功能
#### 2.2.1 主要搜尋功能
```typescript
// 搜尋範圍
- 詞彙本身 (word)
- 中文翻譯 (translation)
- 英文定義 (definition)
- 例句內容 (example)
```
##### 搜尋增強功能
- **即時搜尋**: 輸入時即時過濾結果
- **高亮顯示**: 搜尋關鍵字在結果中高亮標示
- **清除功能**: 一鍵清除搜尋條件 (ESC 鍵或 X 按鈕)
- **結果統計**: 顯示找到的詞卡數量
#### 2.2.2 進階篩選選項
##### CEFR 等級篩選
```typescript
enum CEFRLevel {
A1 = "A1 - 基礎",
A2 = "A2 - 基礎",
B1 = "B1 - 中級",
B2 = "B2 - 中高級",
C1 = "C1 - 高級",
C2 = "C2 - 精通"
}
```
##### 詞性篩選
```typescript
enum PartOfSpeech {
noun = "名詞 (noun)",
verb = "動詞 (verb)",
adjective = "形容詞 (adjective)",
adverb = "副詞 (adverb)",
preposition = "介詞 (preposition)",
interjection = "感嘆詞 (interjection)"
}
```
##### 掌握程度篩選
```typescript
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` 頁面)
- 批量導入 (未來功能)
##### 編輯詞卡
- **可編輯欄位**:
```typescript
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 掌握度系統
```typescript
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 詞卡核心資料結構
```typescript
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 服務結構
```typescript
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. 技術實現規格
### 4.1 前端技術架構
- **框架**: Next.js 15 with App Router
- **語言**: TypeScript
- **樣式**: Tailwind CSS
- **狀態管理**: React useState/useEffect hooks
- **API 通信**: Fetch API with error handling
### 4.2 資料處理流程
#### 4.2.1 詞卡載入流程
```typescript
// 載入流程
loadFlashcards() -> flashcardsService.getFlashcards() -> setFlashcards(data)
// 錯誤處理
catch(error) -> setError(message) -> 顯示錯誤狀態
```
#### 4.2.2 搜尋篩選流程
```typescript
// 即時篩選
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)
```sql
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
**審核人**: 待指定