# 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
**審核狀態**: ✅ 完成