# 🔍 進階搜尋功能完善計劃

## 📋 現狀評估

### ✅ 已完成功能
- [x] 基本文字搜尋（詞彙、翻譯、定義）
- [x] CEFR等級篩選 (A1-C2)
- [x] 詞性篩選 (noun, verb, adjective, etc.)
- [x] 掌握程度篩選 (高/中/低)
- [x] 收藏狀態篩選
- [x] 快速篩選按鈕
- [x] 搜尋結果高亮
- [x] 防抖搜尋 (200ms)
- [x] ESC 鍵清除篩選
- [x] 焦點管理優化

### 🚫 缺失的核心功能

#### 1. **排序功能**
- **缺失**: 沒有詞卡排序選項
- **需要**: 按創建時間、掌握度、字母順序、CEFR等級排序
- **影響**: 用戶無法按需要的順序瀏覽詞卡

#### 2. **分頁功能**
- **缺失**: 沒有分頁機制
- **問題**: 大量詞卡時載入慢、滾動困難
- **需要**: 分頁導航、每頁數量選擇

#### 3. **進階搜尋條件**
- **缺失**: 創建日期範圍篩選
- **缺失**: 複習次數篩選
- **缺失**: 例句內容搜尋

#### 4. **搜尋歷史記錄**
- **缺失**: 搜尋記錄保存
- **缺失**: 常用篩選組合快捷鍵

#### 5. **批量操作**
- **缺失**: 批量選擇詞卡
- **缺失**: 批量收藏/取消收藏
- **缺失**: 批量刪除

#### 6. **搜尋結果優化**
- **缺失**: 搜尋結果相關性排序
- **缺失**: 模糊搜尋支援
- **缺失**: 搜尋建議

---

## 🎯 四階段改善計劃

### 第一階段：排序與分頁 (優先)
> **預計時間**: 3-5天
> **難度**: ⭐⭐
> **價值**: ⭐⭐⭐⭐⭐

#### 1.1 新增排序功能
- [ ] 添加排序下拉選單組件
  - 創建時間 (最新/最舊)
  - 掌握度 (高到低/低到高)
  - 字母順序 (A-Z/Z-A)
  - CEFR等級 (A1-C2/C2-A1)
  - 複習次數 (多到少/少到多)
- [ ] 升序/降序切換按鈕
- [ ] 更新前端狀態管理
- [ ] 更新 API 參數支援排序
- [ ] 後端實現排序邏輯

#### 1.2 實現分頁機制
- [ ] 分頁導航組件設計
- [ ] 每頁數量選擇 (10/20/50/100)
- [ ] 頁碼跳轉功能
- [ ] 總數統計顯示
- [ ] URL 參數同步 (支援書籤分享)
- [ ] 更新後端 API 支援 `page`, `limit`, `offset` 參數
- [ ] 無限滾動模式 (可選)

---

### 第二階段：進階篩選條件
> **預計時間**: 4-6天
> **難度**: ⭐⭐⭐
> **價值**: ⭐⭐⭐⭐

#### 2.1 時間範圍篩選
- [ ] 創建日期範圍選擇器
- [ ] 最後複習時間篩選
- [ ] 預設快捷選項
  - 今天
  - 昨天
  - 本週
  - 本月
  - 上個月
  - 自定義範圍
- [ ] 日曆組件整合

#### 2.2 複習統計篩選
- [ ] 複習次數範圍篩選 (滑桿組件)
- [ ] 正確率篩選 (0-100%)
- [ ] 學習狀態篩選
  - 從未複習
  - 學習中
  - 已掌握
  - 需要複習
- [ ] 連續答對次數篩選

#### 2.3 內容深度搜尋
- [ ] 例句內容搜尋
- [ ] 定義內容搜尋
- [ ] 標籤搜尋 (如果有標籤系統)
- [ ] 多關鍵字組合搜尋 (AND/OR)

---

### 第三階段：用戶體驗優化
> **預計時間**: 5-7天
> **難度**: ⭐⭐⭐⭐
> **價值**: ⭐⭐⭐⭐

#### 3.1 搜尋歷史與快捷
- [ ] localStorage 保存搜尋記錄
- [ ] 搜尋歷史下拉選單
- [ ] 常用篩選組合儲存
- [ ] 自定義篩選預設
- [ ] 一鍵重置到個人偏好
- [ ] 搜尋記錄管理 (清除、固定)

#### 3.2 批量操作系統
- [ ] 多選 checkbox 界面
- [ ] 全選/反選/部分選功能
- [ ] 批量操作工具列
  - 批量收藏/取消收藏
  - 批量刪除
  - 批量標記為已掌握
  - 批量移動到複習列表
- [ ] 批量操作確認對話框
- [ ] 操作結果通知

#### 3.3 界面優化
- [ ] 響應式設計改善
- [ ] 搜尋結果載入骨架
- [ ] 空狀態優化設計
- [ ] 篩選條件摺疊/展開動畫
- [ ] 搜尋結果數量動畫

---

### 第四階段：搜尋智能化
> **預計時間**: 7-10天
> **難度**: ⭐⭐⭐⭐⭐
> **價值**: ⭐⭐⭐

#### 4.1 智能搜尋算法
- [ ] 模糊搜尋實現 (Fuzzy Search)
- [ ] 相關性排序算法
- [ ] 詞根匹配 (英語詞根系統)
- [ ] 同義詞搜尋
- [ ] 拼寫錯誤容錯

#### 4.2 搜尋建議系統
- [ ] 自動完成功能
- [ ] 搜尋建議下拉
- [ ] 相關詞彙推薦
- [ ] 搜尋熱詞統計
- [ ] 個性化建議

#### 4.3 效能優化
- [ ] 虛擬滾動支援大量數據
- [ ] 搜尋結果快取策略
- [ ] 防抖優化進階版
- [ ] 背景預加載
- [ ] CDN 快取優化

---

## 🛠️ 技術實現細節

### 前端技術棧
- **UI組件**: 自定義組件 + Tailwind CSS
- **狀態管理**: React useState + useEffect
- **快取策略**: localStorage + sessionStorage
- **虛擬滾動**: react-window (如需要)
- **日期選擇**: react-datepicker
- **模糊搜尋**: fuse.js

### 後端 API 擴展
```typescript
// 新增 API 參數
interface GetFlashcardsParams {
  // 現有參數
  search?: string;
  favoritesOnly?: boolean;
  cefrLevel?: string;
  partOfSpeech?: string;
  masteryLevel?: string;

  // 新增參數
  page?: number;           // 頁碼
  limit?: number;          // 每頁數量
  sortBy?: string;         // 排序字段
  sortOrder?: 'asc' | 'desc'; // 排序方向
  dateFrom?: string;       // 創建時間起始
  dateTo?: string;         // 創建時間結束
  reviewCountMin?: number; // 最少複習次數
  reviewCountMax?: number; // 最多複習次數
  accuracyMin?: number;    // 最低正確率
  accuracyMax?: number;    // 最高正確率
}
```

### 資料庫查詢優化
- 添加相關索引 (created_at, mastery_level, review_count)
- 分頁查詢優化
- 全文搜尋索引 (如果支援)

---

## 📊 成功指標

### 使用者體驗指標
- [ ] 搜尋回應時間 < 300ms
- [ ] 分頁載入時間 < 200ms
- [ ] 用戶搜尋成功率 > 90%
- [ ] 平均搜尋步驟 < 3步

### 功能完成度指標
- [ ] 階段一功能 100% 完成
- [ ] 階段二功能 100% 完成
- [ ] 階段三功能 80% 完成
- [ ] 階段四功能 60% 完成

### 代碼品質指標
- [ ] TypeScript 類型覆蓋率 > 95%
- [ ] 單元測試覆蓋率 > 80%
- [ ] ESLint 規則 100% 通過
- [ ] 效能測試通過

---

## 📅 時程規劃

| 階段 | 功能 | 預計時間 | 優先級 | 負責人 |
|------|------|----------|--------|--------|
| 1 | 排序功能 | 2-3天 | P0 | 開發者 |
| 1 | 分頁機制 | 2-3天 | P0 | 開發者 |
| 2 | 時間篩選 | 2-3天 | P1 | 開發者 |
| 2 | 複習統計篩選 | 2-3天 | P1 | 開發者 |
| 3 | 搜尋歷史 | 3-4天 | P2 | 開發者 |
| 3 | 批量操作 | 2-3天 | P2 | 開發者 |
| 4 | 智能搜尋 | 5-7天 | P3 | 開發者 |
| 4 | 效能優化 | 2-3天 | P3 | 開發者 |

**總計預估**: 20-29 天

---

## 🔄 迭代策略

### MVP (最小可行產品)
**目標**: 第一階段功能
- 基本排序 (創建時間、掌握度)
- 簡單分頁 (固定每頁 20 個)

### V1.0
**目標**: 第一、二階段功能
- 完整排序選項
- 靈活分頁配置
- 時間範圍篩選
- 複習統計篩選

### V2.0
**目標**: 第三階段功能
- 搜尋歷史
- 批量操作
- UI/UX 優化

### V3.0
**目標**: 第四階段功能
- 智能搜尋
- 效能優化
- 進階分析

---

## 📝 備注

### 技術債務
- 現有搜尋邏輯需重構以支援新功能
- API 回應格式可能需要調整
- 前端狀態管理複雜度會增加

### 風險評估
- **高風險**: 大量數據時的效能問題
- **中風險**: 複雜篩選條件的 UI 設計
- **低風險**: 基本排序和分頁功能

### 測試策略
- 單元測試：搜尋邏輯、篩選函數
- 整合測試：API 調用、狀態管理
- E2E 測試：用戶搜尋流程
- 效能測試：大量數據場景

---

*最後更新: 2025-09-24*
*版本: 1.0*