26 KiB

Raw Blame History

AI 互動式單字查詢系統 - 完整功能規格

項目: DramaLing 英語學習平台 功能模組: 智能句子分析與互動式單字查詢版本: v1.0 文檔日期: 2025-01-18

🎯 功能概述

AI 互動式單字查詢系統是一個智能英語學習工具，允許用戶輸入英文句子，獲得 AI 驅動的完整分析，並通過點擊單字的方式進行深度學習。系統具備語法修正、高價值詞彙標記、成本優化和快取機制。

📋 核心功能特性

🔍 主要功能

智能句子分析: Gemini AI 驅動的句子翻譯和解釋
語法自動修正: 檢測並建議語法錯誤修正
互動式單字查詢: 點擊任何單字即時查看詳細信息
高價值詞彙標記: AI 識別重要學習詞彙（免費查詢）
成本優化設計: 低價值詞彙收費查詢，防止濫用
24小時快取機制: 避免重複 AI 調用，提升響應速度
使用額度管理: 免費用戶 3 小時內限制 5 次分析

🎨 用戶體驗特色

即時回饋: 新句子 3-5 秒，快取結果 <200ms
視覺化快取狀態: 清楚顯示結果來源（AI/快取）
智能語法提示: 主動發現和修正語法錯誤
分層收費模式: 高價值詞彙免費，低價值詞彙收費

🔄 用戶流程圖 (User Flow)

[1. 用戶登入]
    ↓
[2. 進入分析頁面 (/generate)]
    ↓
[3. 選擇輸入模式]
    ├── ✍️ 手動輸入 (最多300字)
    └── 📷 影劇截圖 (Phase 2, 付費功能)
    ↓
[4. 輸入英文文字]
    ├── 即時字數統計
    ├── 顏色警告 (280字+黃色, 300字+紅色)
    └── 輸入驗證
    ↓
[5. 點擊「🔍 分析句子」]
    ├── 檢查使用額度 (免費用戶 5次/3小時)
    ├── 顯示載入狀態 "正在分析句子... (AI 分析約需 3-5 秒)"
    └── 調用後端 API
    ↓
[6. 後端處理邏輯]
    ├── 檢查快取 (24小時TTL)
    │   ├── Cache Hit → 立即返回 (💾 快取結果)
    │   └── Cache Miss → 調用 Gemini AI (🤖 AI 分析)
    ├── 語法檢查和修正
    ├── 高價值詞彙標記
    └── 存入快取
    ↓
[7. 分析結果顯示]
    ├── 快取狀態標籤 (💾 快取結果 / 🤖 AI 分析)
    ├── 語法修正面板 (如有錯誤)
    │   ├── 顯示原始 vs 修正版本
    │   ├── [✅ 採用修正] [❌ 保持原版]
    │   └── 說明修正原因
    ├── 句子翻譯和解釋
    └── 互動式文字區域
    ↓
[8. 互動式單字查詢]
    ├── 點擊單字觸發分析
    ├── 高價值詞彙 (🟢⭐ / 🟡⭐) → 免費彈窗
    ├── 低價值詞彙 (🔵) → 收費確認對話框
    │   ├── 顯示剩餘額度
    │   ├── [✅ 確認查詢] [❌ 取消]
    │   └── 扣除使用額度
    └── 顯示詳細詞彙信息彈窗
    ↓
[9. 詞卡生成 (可選)]
    ├── 點擊「📖 生成詞卡」
    ├── AI 自動提取重要詞彙
    ├── 預覽生成的詞卡
    └── 保存到個人詞庫
    ↓
[10. 導航選項]
    ├── 🔄 分析新句子 → 返回步驟 2
    ├── ← 返回分析 → 返回步驟 7
    └── ← 返回輸入 → 返回步驟 4

📐 詳細功能規格

🔧 技術規格

前端技術棧

框架: Next.js 15.5.3 + TypeScript
UI 組件: React Hooks + Tailwind CSS
狀態管理: useState (本地狀態)
API 調用: Fetch API
路由: Next.js App Router

後端技術棧

框架: ASP.NET Core 8.0
AI 整合: Google Gemini API
資料庫: SQLite + Entity Framework Core
快取: 資料庫快取 (24小時TTL)
認證: JWT Token

📊 資料模型

1. API 請求/回應格式

句子分析請求:

interface AnalyzeSentenceRequest {
  inputText: string        // 用戶輸入的英文句子 (≤300字)
  forceRefresh?: boolean   // 強制刷新快取 (預設: false)
  analysisMode?: string    // 分析模式 (預設: 'full')
}

句子分析回應:

interface AnalyzeSentenceResponse {
  success: boolean
  message: string
  cached: boolean          // 是否來自快取
  cacheHit: boolean        // 快取命中狀態
  usingAI: boolean         // 是否使用 AI 分析
  data: {
    analysisId: string
    inputText: string
    grammarCorrection: GrammarCorrectionResult
    sentenceMeaning: {
      Translation: string    // 注意: 首字母大寫
      Explanation: string    // 注意: 首字母大寫
    }
    finalAnalysisText: string
    wordAnalysis: Record<string, WordAnalysis>
    highValueWords: string[]
    phrasesDetected: PhraseInfo[]
  }
}

2. 單字分析資料結構

interface WordAnalysis {
  word: string
  translation: string
  definition: string
  partOfSpeech: string
  pronunciation: string
  synonyms: string[]
  antonyms?: string[]
  isPhrase: boolean
  isHighValue: boolean      // 高學習價值標記
  learningPriority: 'high' | 'medium' | 'low'
  phraseInfo?: {
    phrase: string
    meaning: string
    warning: string
    colorCode: string
  }
  difficultyLevel: string   // CEFR 等級 (A1, A2, B1, B2, C1, C2)
  costIncurred?: number     // 查詢成本
}

3. 語法修正結構

interface GrammarCorrectionResult {
  hasErrors: boolean
  originalText: string
  correctedText?: string
  corrections: GrammarCorrection[]
  confidenceScore: number
}

interface GrammarCorrection {
  position: { start: number, end: number }
  errorType: string
  original: string
  corrected: string
  reason: string
  severity: 'high' | 'medium' | 'low'
}

🎨 UI/UX 規格

1. 主介面佈局 (`/generate`)

┌─────────────────────────────────────────┐
│ Navigation Bar                          │
├─────────────────────────────────────────┤
│ 📝 AI 智能生成詞卡                        │
│                                         │
│ ┌─── 原始例句類型 ──────────────────────┐ │
│ │ [✍️ 手動輸入] [📷 影劇截圖 🔒]         │ │
│ └───────────────────────────────────────┘ │
│                                         │
│ ┌─── 輸入英文文本 ──────────────────────┐ │
│ │ ┌─────────────────────────────────┐   │ │
│ │ │ [Textarea: 最多300字元]         │   │ │
│ │ │ "輸入英文句子（最多300字）..."    │   │ │
│ │ └─────────────────────────────────┘   │ │
│ │ 最多 300 字元 • 目前：0 字元           │ │
│ └───────────────────────────────────────┘ │
│                                         │
│ ┌─────────────────────────────────────┐ │
│ │ [🔍 分析句子] (全寬按鈕)              │ │
│ └─────────────────────────────────────┘ │
│                                         │
│ 免費用戶：已使用 0/5 次 (3小時內)        │
└─────────────────────────────────────────┘

2. 分析結果介面

┌─────────────────────────────────────────┐
│ 📝 句子分析結果              💾 快取結果  │
│                               [← 返回]  │
├─────────────────────────────────────────┤
│ ⚠️  語法修正建議 (如有錯誤)             │
│ ┌─ 原文：I go to school yesterday ──┐   │
│ │ 修正：I went to school yesterday   │   │
│ │ [✅ 採用修正] [❌ 保持原版]          │   │
│ └───────────────────────────────────┘   │
├─────────────────────────────────────────┤
│ 📝 句子分析                             │
│ ┌─ 用戶輸入 ────────────────────────┐   │
│ │ I go to school yesterday          │   │
│ └───────────────────────────────────┘   │
│ ┌─ 整句意思 ────────────────────────┐   │
│ │ 我昨天去學校。這句話表達了過去...   │   │
│ └───────────────────────────────────┘   │
├─────────────────────────────────────────┤
│ 💡 點擊查詢單字意思                      │
│ 🟡⭐高價值片語 🟢⭐高價值單字 🔵普通單字  │
│ ┌─────────────────────────────────────┐ │
│ │ I [went] to [school] [yesterday]    │ │
│ │    🟢⭐    🔵    🟡⭐               │ │
│ └─────────────────────────────────────┘ │
├─────────────────────────────────────────┤
│ [🔄 分析新句子] [📖 生成詞卡]            │
└─────────────────────────────────────────┘

3. 單字查詢彈窗

┌─── went ─────────────── ✕ ─┐
│ ⭐ 高價值詞彙（免費查詢）      │
│ ⭐⭐⭐⭐⭐ 學習價值           │
│                            │
│ [verb] /went/  🔊           │
│                            │
│ 翻譯: 去 (go的過去式)        │
│ 定義: Past tense of go     │
│                            │
│ 同義詞: [traveled] [moved]  │
│ 反義詞: [came] [stayed]     │
│                            │
│ 難度等級: [CEFR A1] (基礎)   │
└────────────────────────────┘

4. 收費確認對話框

┌─── school ─────────── ✕ ─┐
│ 💰 低價值詞彙（需消耗額度）   │
│ 此查詢將消耗 1 次 使用額度   │
│ 剩餘額度：4 次              │
│                            │
│ [✅ 確認查詢] [❌ 取消]      │
└────────────────────────────┘

🔧 技術實現規格

1. 前端組件架構

GeneratePage (主頁面)
├── Navigation (導航欄)
├── InputModeSelection (輸入模式選擇)
├── TextInputArea (文字輸入區域)
├── AnalysisButton (分析按鈕)
├── UsageCounter (使用次數顯示)
├── AnalysisView (分析結果檢視)
│   ├── CacheStatusBadge (快取狀態標籤)
│   ├── GrammarCorrectionPanel (語法修正面板)
│   ├── SentenceAnalysisPanel (句子分析面板)
│   └── ClickableTextV2 (互動式文字組件)
│       ├── WordClickHandler (單字點擊處理)
│       ├── CostConfirmDialog (收費確認對話框)
│       └── WordInfoPopup (單字資訊彈窗)
└── CardPreview (詞卡預覽, 可選)

2. 後端API架構

AIController
├── AnalyzeSentence (句子分析主API)
│   ├── 使用限制檢查
│   ├── 快取查詢邏輯
│   ├── Gemini AI 調用
│   ├── 語法修正處理
│   ├── 高價值詞彙標記
│   └── 快取寫入
├── QueryWord (單字查詢API)
│   ├── 高/低價值判斷
│   ├── 收費邏輯處理
│   └── 即時詞彙分析
└── CacheManagement (快取管理API)
    ├── GetCacheStats (快取統計)
    ├── CleanupCache (清理過期快取)
    └── InvalidateCache (手動清除快取)

3. 快取系統規格

SentenceAnalysisCache (資料表)
├── InputTextHash (SHA-256, 索引)
├── AnalysisResult (JSON格式)
├── ExpiresAt (過期時間, 索引)
├── AccessCount (存取次數)
├── CreatedAt / LastAccessedAt
└── 複合索引 (Hash + ExpiresAt)

快取策略:
├── TTL: 24小時
├── 清理: 自動背景任務
├── 命中率: >80% (預期)
└── 儲存格式: JSON序列化

🎮 詳細互動規格

📝 輸入階段

輸入模式

手動輸入: 300字元限制，即時字數統計
影劇截圖: Phase 2 功能，付費用戶限定

輸入驗證

// 字數限制邏輯
if (mode === 'manual' && value.length > 300) {
  return // 阻止輸入
}

// 視覺回饋
const borderColor =
  textLength >= 300 ? 'border-red-400' :
  textLength >= 280 ? 'border-yellow-400' :
  'border-gray-300'

按鈕狀態

// 分析按鈕啟用條件
disabled = isAnalyzing ||
          (mode === 'manual' && (!textInput || textInput.length > 300)) ||
          (mode === 'screenshot')

🔍 分析階段

載入狀態

初始: "🔍 分析句子"
載入中: "正在分析句子... (AI 分析約需 3-5 秒)" + 旋轉動畫
完成: 自動跳轉到分析結果頁面

快取邏輯

// 後端快取檢查流程
1. 計算輸入文字的 SHA-256 hash
2. 查詢資料庫是否有未過期的快取
3. Cache Hit: 立即返回 + 更新統計
4. Cache Miss: 調用 Gemini AI + 存入快取

錯誤處理

API 錯誤: 顯示錯誤訊息
網路錯誤: 重試機制
使用額度超限: 提示升級或等待

🖱️ 互動查詢階段

單字分類和視覺設計

/* 高價值片語 */
.high-value-phrase {
  background: bg-yellow-100
  border: 2px solid border-yellow-400
  icon: ⭐
  hover: bg-yellow-200 + shadow + transform
}

/* 高價值單字 */
.high-value-word {
  background: bg-green-100
  border: 2px solid border-green-400
  icon: ⭐
  hover: bg-green-200 + shadow + transform
}

/* 普通單字 */
.normal-word {
  border-bottom: border-blue-300
  hover: bg-blue-100 + border-blue-400
}

點擊行為邏輯

// 單字點擊處理流程
onClick(word) => {
  const wordAnalysis = analysis[cleanWord]

  if (wordAnalysis.isHighValue) {
    // 高價值詞彙 - 立即顯示彈窗
    showWordPopup(word, analysis)
    // 不扣除使用額度
  } else {
    // 低價值詞彙 - 顯示收費確認
    showCostConfirmDialog(word, cost: 1)
    // 確認後扣除額度並調用API
  }
}

彈窗內容結構

WordInfoPopup
├── Header (單字 + 關閉按鈕)
├── ValueBadge (高價值標記 + 學習價值星級)
├── PhraseWarning (片語警告，如適用)
├── BasicInfo (詞性 + 發音 + 發音按鈕)
├── Translation (翻譯)
├── Definition (英文定義)
├── Synonyms (同義詞標籤)
├── Antonyms (反義詞標籤)
└── DifficultyLevel (CEFR難度等級)

💰 收費模式規格

免費用戶限制

const FREE_USER_LIMITS = {
  sentenceAnalysis: 5,      // 3小時內最多5次句子分析
  timeWindow: 3 * 60 * 60,  // 3小時窗口 (秒)
  wordQueryCost: 1,         // 每次低價值詞彙查詢成本
  highValueWordsFree: true  // 高價值詞彙永遠免費
}

高價值詞彙判定邏輯

// 高價值詞彙標準
const isHighValue =
  cefrLevel >= 'B1' ||           // B1+ 等級詞彙
  isIdiomOrPhrase ||             // 慣用語和片語
  isAcademicVocabulary ||        // 學術詞彙
  learningFrequency === 'high'   // 高學習頻率詞彙

🗄️ 資料持久化規格

快取資料表結構

CREATE TABLE SentenceAnalysisCache (
    Id UNIQUEIDENTIFIER PRIMARY KEY,
    InputTextHash NVARCHAR(64) NOT NULL,     -- SHA-256 hash
    InputText NVARCHAR(1000) NOT NULL,       -- 原始輸入
    AnalysisResult NVARCHAR(MAX) NOT NULL,   -- JSON格式分析結果
    HasGrammarErrors BIT NOT NULL,           -- 是否有語法錯誤
    CorrectedText NVARCHAR(1000) NULL,       -- 修正後文字
    GrammarCorrections NVARCHAR(MAX) NULL,   -- 語法修正JSON
    HighValueWords NVARCHAR(MAX) NULL,       -- 高價值詞彙JSON
    PhrasesDetected NVARCHAR(MAX) NULL,      -- 檢測到的片語JSON
    CreatedAt DATETIME2 NOT NULL,            -- 建立時間
    ExpiresAt DATETIME2 NOT NULL,            -- 過期時間
    LastAccessedAt DATETIME2 NULL,           -- 最後存取時間
    AccessCount INT NOT NULL DEFAULT 0       -- 存取次數
);

-- 索引
CREATE INDEX IX_SentenceAnalysisCache_Hash ON SentenceAnalysisCache(InputTextHash);
CREATE INDEX IX_SentenceAnalysisCache_Expires ON SentenceAnalysisCache(ExpiresAt);
CREATE INDEX IX_SentenceAnalysisCache_Hash_Expires ON SentenceAnalysisCache(InputTextHash, ExpiresAt);

🧪 測試規格

🔬 功能測試案例

1. 句子分析功能測試

測試案例 1.1: 新句子分析

輸入: "I went to school yesterday"
預期結果:
- 載入時間: 3-5 秒
- 快取狀態: 🤖 AI 分析
- 翻譯: "我昨天去學校。"
- 解釋: 包含語法結構說明
- 高價值詞彙: went, school, yesterday 標記為 ⭐

測試案例 1.2: 快取命中測試

前置條件: 已分析過 "I went to school yesterday"
輸入: "I went to school yesterday" (相同句子)
預期結果:
- 載入時間: <200ms
- 快取狀態: 💾 快取結果
- 內容: 與首次分析完全相同
- 使用額度: 不增加

測試案例 1.3: 語法錯誤修正

輸入: "I go to school yesterday"
預期結果:
- 語法修正面板出現
- 原文: "I go to school yesterday"
- 修正: "I went to school yesterday"
- 修正原因: "過去式時態修正：句子中有 'yesterday'，應使用過去式"
- 用戶可選擇採用或拒絕修正

2. 互動式單字查詢測試

測試案例 2.1: 高價值詞彙查詢

前置條件: 已完成句子分析
操作: 點擊標記為 ⭐ 的單字 "went"
預期結果:
- 立即顯示詞彙資訊彈窗
- 顯示 "⭐ 高價值詞彙（免費查詢）"
- 不扣除使用額度
- 包含完整詞彙信息

測試案例 2.2: 低價值詞彙查詢

前置條件: 已完成句子分析，剩餘額度 > 0
操作: 點擊普通單字 (藍色下劃線)
預期結果:
1. 顯示收費確認對話框
2. 顯示消耗額度和剩餘額度
3. 用戶確認後扣除 1 次額度
4. 調用 query-word API
5. 顯示詞彙資訊彈窗

測試案例 2.3: 額度不足測試

前置條件: 剩餘額度 = 0
操作: 點擊低價值詞彙
預期結果:
- 顯示 "❌ 使用額度不足，無法查詢低價值詞彙"
- 不調用 API
- 不顯示詞彙彈窗

3. 使用限制測試

測試案例 3.1: 免費用戶限制

前置條件: 免費用戶，3小時內已分析 5 次
操作: 嘗試分析新句子
預期結果:
- 顯示 "❌ 免費用戶 3 小時內只能分析 5 次句子，請稍後再試或升級到付費版本"
- 不調用分析 API
- 使用計數不增加

測試案例 3.2: 付費用戶無限制

前置條件: isPremium = true
操作: 多次分析句子
預期結果:
- 顯示 "🌟 付費用戶：無限制使用"
- 所有分析正常執行
- 無使用次數限制

🚀 效能測試規格

1. 回應時間測試

測試情境	預期時間	測試方法
新句子 AI 分析	3-5 秒	測量從點擊到結果顯示的時間
快取命中查詢	<200ms	重複查詢相同句子
高價值詞彙點擊	<100ms	點擊已標記的高價值詞彙
低價值詞彙查詢	1-2 秒	確認後的API調用時間

2. 快取效能測試

測試指標	目標值	測試方法
快取命中率	>80%	重複查詢統計
快取寫入成功率	>99%	監控快取失敗日誌
快取過期清理	24小時	測試過期資料自動清理

🔧 整合測試規格

1. 端到端測試流程

完整用戶旅程測試:

1. 登入系統
2. 導航到 /generate 頁面
3. 輸入測試句子 "She felt ashamed of her mistake and apologized"
4. 點擊 "🔍 分析句子"
5. 驗證分析結果正確顯示
6. 點擊高價值詞彙 "ashamed" (免費)
7. 驗證詞彙彈窗內容
8. 點擊低價值詞彙 "her" (收費)
9. 確認收費對話框
10. 驗證額度扣除
11. 點擊 "🔄 分析新句子"
12. 輸入相同句子
13. 驗證快取命中 (💾 快取結果)
14. 點擊 "📖 生成詞卡"
15. 驗證詞卡生成功能

2. API 整合測試

測試案例: API 連接性

# 1. 句子分析 API 測試
curl -X POST http://localhost:5000/api/ai/analyze-sentence \
  -H "Content-Type: application/json" \
  -d '{"inputText": "Hello world", "analysisMode": "full"}'

# 2. 單字查詢 API 測試
curl -X POST http://localhost:5000/api/ai/query-word \
  -H "Content-Type: application/json" \
  -d '{"word": "hello", "sentence": "Hello world"}'

# 3. 快取統計 API 測試
curl -X GET http://localhost:5000/api/ai/cache-stats

3. 邊界條件測試

輸入驗證測試:

測試案例 3.1: 空白輸入
輸入: ""
預期: 按鈕禁用，無法提交

測試案例 3.2: 超長輸入
輸入: 301字元的文字
預期: 無法輸入，紅色邊框警告

測試案例 3.3: 特殊字元
輸入: "Hello @#$%^&*() world!"
預期: 正常分析，特殊字元適當處理

測試案例 3.4: 純中文輸入
輸入: "你好世界"
預期: 系統應適當處理或給出提示

🐛 錯誤處理測試

1. 網路錯誤測試

測試案例 1: 後端服務停止
操作: 停止後端服務後嘗試分析
預期: 顯示連接錯誤訊息，不崩潰

測試案例 2: Gemini API 失敗
模擬: API key 無效或 API 服務不可用
預期: 回退到本地分析，不中斷用戶體驗

2. 資料錯誤測試

測試案例 1: 損壞的快取資料
模擬: 資料庫中有格式錯誤的 JSON
預期: 忽略損壞快取，重新調用 AI 分析

測試案例 2: 不完整的API回應
模擬: 後端回傳缺少某些欄位的資料
預期: 使用預設值，顯示部分資訊而非崩潰

🎯 驗收標準

✅ 功能驗收標準

基本功能完整性
- 用戶可成功輸入並分析英文句子
- 所有UI組件正確顯示和互動
- API調用成功且資料正確處理
AI功能正確性
- Gemini AI 整合正常運作
- 翻譯和解釋內容品質符合要求
- 語法修正建議合理且準確
互動查詢功能
- 高價值詞彙免費查詢正常
- 低價值詞彙收費機制正確
- 詞彙彈窗內容完整準確
快取系統功能
- 新句子使用 AI 分析
- 重複句子使用快取結果
- 快取狀態正確顯示
使用限制功能
- 免費用戶額度限制生效
- 付費用戶無限制使用
- 額度計算準確無誤

📊 效能驗收標準

回應時間要求
- 快取命中 < 200ms
- AI分析 < 10秒 (95%的情況下 < 5秒)
- 頁面導航 < 100ms
系統穩定性
- 24小時連續運行無崩潰
- 記憶體使用穩定
- 資料庫連接池正常
用戶體驗標準
- 用戶操作回饋及時 (<100ms)
- 載入狀態清晰可見
- 錯誤訊息用戶友善

🔧 開發和部署規格

📁 檔案結構

frontend/
├── app/generate/page.tsx              (主要分析頁面)
├── components/ClickableTextV2.tsx     (互動式文字組件)
├── components/GrammarCorrectionPanel.tsx (語法修正面板)
└── contexts/AuthContext.tsx          (認證上下文)

backend/
├── Controllers/AIController.cs        (AI API 控制器)
├── Services/GeminiService.cs         (Gemini AI 服務)
├── Services/AnalysisCacheService.cs  (快取服務)
├── Services/UsageTrackingService.cs  (使用追蹤服務)
└── Models/Entities/               (資料模型)

🚀 部署需求

環境變數

# Gemini AI
GEMINI_API_KEY=your_gemini_api_key

# 資料庫
CONNECTION_STRING=Data Source=dramaling.db

# CORS
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:3002

# 快取設定
CACHE_TTL_HOURS=24
CACHE_CLEANUP_INTERVAL_HOURS=6

系統需求

前端: Node.js 18+, Next.js 15+
後端: .NET 8.0+, ASP.NET Core
資料庫: SQLite 3.x (開發), SQL Server (生產)
外部API: Google Gemini API access

文檔版本: v1.0 最後更新: 2025-01-18 負責人: Claude Code 審核狀態: ✅ 完成

26 KiB Raw Blame History Unescape Escape