795 lines
26 KiB
Markdown
795 lines
26 KiB
Markdown
# AI 互動式單字查詢系統 - 完整功能規格
|
||
|
||
**項目**: DramaLing 英語學習平台
|
||
**功能模組**: 智能句子分析與互動式單字查詢
|
||
**版本**: v1.0
|
||
**文檔日期**: 2025-01-18
|
||
|
||
## 🎯 功能概述
|
||
|
||
AI 互動式單字查詢系統是一個智能英語學習工具，允許用戶輸入英文句子，獲得 AI 驅動的完整分析，並通過點擊單字的方式進行深度學習。系統具備語法修正、高價值詞彙標記、成本優化和快取機制。
|
||
|
||
## 📋 核心功能特性
|
||
|
||
### 🔍 主要功能
|
||
1. **智能句子分析**: Gemini AI 驅動的句子翻譯和解釋
|
||
2. **語法自動修正**: 檢測並建議語法錯誤修正
|
||
3. **互動式單字查詢**: 點擊任何單字即時查看詳細信息
|
||
4. **高價值詞彙標記**: AI 識別重要學習詞彙（免費查詢）
|
||
5. **成本優化設計**: 低價值詞彙收費查詢，防止濫用
|
||
6. **24小時快取機制**: 避免重複 AI 調用，提升響應速度
|
||
7. **使用額度管理**: 免費用戶 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 請求/回應格式
|
||
|
||
**句子分析請求**:
|
||
```typescript
|
||
interface AnalyzeSentenceRequest {
|
||
inputText: string // 用戶輸入的英文句子 (≤300字)
|
||
forceRefresh?: boolean // 強制刷新快取 (預設: false)
|
||
analysisMode?: string // 分析模式 (預設: 'full')
|
||
}
|
||
```
|
||
|
||
**句子分析回應**:
|
||
```typescript
|
||
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. 單字分析資料結構
|
||
|
||
```typescript
|
||
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. 語法修正結構
|
||
|
||
```typescript
|
||
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 功能，付費用戶限定
|
||
|
||
#### 輸入驗證
|
||
```typescript
|
||
// 字數限制邏輯
|
||
if (mode === 'manual' && value.length > 300) {
|
||
return // 阻止輸入
|
||
}
|
||
|
||
// 視覺回饋
|
||
const borderColor =
|
||
textLength >= 300 ? 'border-red-400' :
|
||
textLength >= 280 ? 'border-yellow-400' :
|
||
'border-gray-300'
|
||
```
|
||
|
||
#### 按鈕狀態
|
||
```typescript
|
||
// 分析按鈕啟用條件
|
||
disabled = isAnalyzing ||
|
||
(mode === 'manual' && (!textInput || textInput.length > 300)) ||
|
||
(mode === 'screenshot')
|
||
```
|
||
|
||
### 🔍 分析階段
|
||
|
||
#### 載入狀態
|
||
- **初始**: "🔍 分析句子"
|
||
- **載入中**: "正在分析句子... (AI 分析約需 3-5 秒)" + 旋轉動畫
|
||
- **完成**: 自動跳轉到分析結果頁面
|
||
|
||
#### 快取邏輯
|
||
```csharp
|
||
// 後端快取檢查流程
|
||
1. 計算輸入文字的 SHA-256 hash
|
||
2. 查詢資料庫是否有未過期的快取
|
||
3. Cache Hit: 立即返回 + 更新統計
|
||
4. Cache Miss: 調用 Gemini AI + 存入快取
|
||
```
|
||
|
||
#### 錯誤處理
|
||
- **API 錯誤**: 顯示錯誤訊息
|
||
- **網路錯誤**: 重試機制
|
||
- **使用額度超限**: 提示升級或等待
|
||
|
||
### 🖱️ 互動查詢階段
|
||
|
||
#### 單字分類和視覺設計
|
||
```css
|
||
/* 高價值片語 */
|
||
.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
|
||
}
|
||
```
|
||
|
||
#### 點擊行為邏輯
|
||
```typescript
|
||
// 單字點擊處理流程
|
||
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難度等級)
|
||
```
|
||
|
||
### 💰 收費模式規格
|
||
|
||
#### 免費用戶限制
|
||
```typescript
|
||
const FREE_USER_LIMITS = {
|
||
sentenceAnalysis: 5, // 3小時內最多5次句子分析
|
||
timeWindow: 3 * 60 * 60, // 3小時窗口 (秒)
|
||
wordQueryCost: 1, // 每次低價值詞彙查詢成本
|
||
highValueWordsFree: true // 高價值詞彙永遠免費
|
||
}
|
||
```
|
||
|
||
#### 高價值詞彙判定邏輯
|
||
```typescript
|
||
// 高價值詞彙標準
|
||
const isHighValue =
|
||
cefrLevel >= 'B1' || // B1+ 等級詞彙
|
||
isIdiomOrPhrase || // 慣用語和片語
|
||
isAcademicVocabulary || // 學術詞彙
|
||
learningFrequency === 'high' // 高學習頻率詞彙
|
||
```
|
||
|
||
### 🗄️ 資料持久化規格
|
||
|
||
#### 快取資料表結構
|
||
```sql
|
||
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 連接性**
|
||
```bash
|
||
# 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回應
|
||
模擬: 後端回傳缺少某些欄位的資料
|
||
預期: 使用預設值，顯示部分資訊而非崩潰
|
||
```
|
||
|
||
## 🎯 驗收標準
|
||
|
||
### ✅ 功能驗收標準
|
||
|
||
1. **基本功能完整性**
|
||
- [ ] 用戶可成功輸入並分析英文句子
|
||
- [ ] 所有UI組件正確顯示和互動
|
||
- [ ] API調用成功且資料正確處理
|
||
|
||
2. **AI功能正確性**
|
||
- [ ] Gemini AI 整合正常運作
|
||
- [ ] 翻譯和解釋內容品質符合要求
|
||
- [ ] 語法修正建議合理且準確
|
||
|
||
3. **互動查詢功能**
|
||
- [ ] 高價值詞彙免費查詢正常
|
||
- [ ] 低價值詞彙收費機制正確
|
||
- [ ] 詞彙彈窗內容完整準確
|
||
|
||
4. **快取系統功能**
|
||
- [ ] 新句子使用 AI 分析
|
||
- [ ] 重複句子使用快取結果
|
||
- [ ] 快取狀態正確顯示
|
||
|
||
5. **使用限制功能**
|
||
- [ ] 免費用戶額度限制生效
|
||
- [ ] 付費用戶無限制使用
|
||
- [ ] 額度計算準確無誤
|
||
|
||
### 📊 效能驗收標準
|
||
|
||
1. **回應時間要求**
|
||
- [ ] 快取命中 < 200ms
|
||
- [ ] AI分析 < 10秒 (95%的情況下 < 5秒)
|
||
- [ ] 頁面導航 < 100ms
|
||
|
||
2. **系統穩定性**
|
||
- [ ] 24小時連續運行無崩潰
|
||
- [ ] 記憶體使用穩定
|
||
- [ ] 資料庫連接池正常
|
||
|
||
3. **用戶體驗標準**
|
||
- [ ] 用戶操作回饋及時 (<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/ (資料模型)
|
||
```
|
||
|
||
### 🚀 部署需求
|
||
|
||
#### 環境變數
|
||
```env
|
||
# 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
|
||
**審核狀態**: ✅ 完成 |