# AI生成網頁前端需求規格

## 📋 **文件資訊**

- **文件名稱**: AI生成網頁前端需求規格
- **版本**: v1.0
- **建立日期**: 2025-09-21
- **最後更新**: 2025-09-21
- **負責團隊**: DramaLing產品需求團隊

---

## 🎯 **產品概述**

### **產品定位**
DramaLing AI生成網頁是個人化英語學習平台的核心功能，專注於提供智能句子分析、個人化詞彙標記和互動式學習體驗。

### **核心價值主張**
- 🤖 **AI驅動分析** - 即時語法檢查和詞彙解析
- 🎯 **個人化學習** - 基於CEFR等級的詞彙分類
- 📊 **視覺化統計** - 直觀的學習進度展示
- 💡 **互動式學習** - 點擊式詞彙詳情查看

---

## 🎭 **用戶故事**

### **US1. 核心學習流程**

#### **US1.1 句子分析學習**
```
身為一個英語學習者
我想要輸入一個英文句子並獲得智能分析
以便了解句子結構、詞彙難度和學習重點

驗收標準：
- 能輸入最多300字的英文句子
- 獲得詞彙分析、翻譯和語法檢查
- 看到個人化的詞彙標記
- 了解詞彙難度分布統計
```

#### **US1.2 個人化詞彙學習**
```
身為不同程度的英語學習者
我想要系統根據我的CEFR等級標記詞彙難度
以便專注學習適合我程度的詞彙

驗收標準：
- 簡單詞彙顯示灰色虛線（已掌握）
- 適中詞彙顯示綠色邊框（重點學習）
- 艱難詞彙顯示橙色邊框（挑戰詞彙）
- 能調整個人CEFR等級設定
```

#### **US1.3 語法錯誤修正**
```
身為英語學習者
我想要在輸入有語法錯誤的句子時獲得修正建議
以便學習正確的英語表達方式

驗收標準：
- 自動檢測語法錯誤（時態、主謂一致等）
- 顯示原句與修正建議的對比
- 可選擇採用修正或保持原樣
- 提供錯誤解釋和學習建議
```

#### **US1.4 慣用語學習**
```
身為英語學習者
我想要識別句子中的慣用語和慣用語
以便學習地道的英語表達

驗收標準：
- 自動識別慣用語
- 在專門區域展示慣用語列表
- 點擊慣用語查看詳細解釋
- 能保存慣用語到個人詞卡庫
```

### **US2. 互動學習體驗**

#### **US2.1 詞彙深度學習**
```
身為英語學習者
我想要點擊句子中的詞彙查看詳細資訊
以便深入了解詞彙的用法和含義

驗收標準：
- 點擊標記詞彙顯示詳情彈窗
- 查看中文翻譯、英文定義、發音
- 查看同義詞和實用例句
- 一鍵保存重要詞彙到詞卡
```

#### **US2.2 學習進度可視化**
```
身為英語學習者
我想要快速了解句子的詞彙難度分布
以便評估學習挑戰和重點

背景：
系統會根據我的CEFR程度與詞彙CEFR程度進行比較分類：
- 簡單啦：學習者CEFR > 詞彙CEFR（簡單詞彙）
- 重點學習：學習者CEFR = 詞彙CEFR（適中難度詞彙）
- 具挑戰：學習者CEFR < 詞彙CEFR（艱難詞彙）
- 慣用語：獨立分類，不參與等級比較

範例（用戶A2等級）：
- "she"(A1) → 已掌握
- "team"(A2) → 重點學習
- "workflow"(B2) → 挑戰詞彙
- "cut someone some slack" → 慣用語

驗收標準：
- 頁面頂部顯示四張統計卡片
- 各卡片準確顯示基於CEFR比較的詞彙數量
- 統計卡片顏色與詞彙標記顏色一致
- 統計數據基於用戶等級動態計算
- 用戶更改CEFR等級時統計即時更新
```

---

## 📋 **功能需求規格**

### **FR1. 文本輸入與處理**

#### **FR1.1 輸入界面需求**
**優先級**: P0 (必須)

**功能描述**:
- 提供大型文本輸入框供用戶輸入英文句子
- 支援最多300字元的文本輸入
- 即時顯示字符計數和剩餘字數
- 接近上限時提供視覺警告

**詳細需求**:
1. **輸入框尺寸**: 最少3行高度，可視區域足夠
2. **字符計數**: 動態顯示 "目前：X/300 字元"
3. **警告機制**:
   - 280字元：黃色警告邊框
   - 300字元：紅色警告，禁止繼續輸入
4. **輸入驗證**: 阻止超過限制的輸入

#### **FR1.2 AI分析觸發**
**優先級**: P0 (必須)

**功能描述**:
- 點擊分析按鈕觸發AI句子分析
- 顯示分析進度和預估時間
- 處理分析失敗的錯誤狀況

**詳細需求**:
1. **按鈕狀態**:
   - 正常：藍色 "🔍 分析句子"
   - 載入中：灰色 + 轉圈動畫 + "正在分析句子... (AI 分析約需 3-5 秒)"
   - 禁用：輸入為空或超過限制時禁用
2. **錯誤處理**: API失敗時顯示友善錯誤訊息
3. **狀態切換**: 分析完成後自動切換到結果視圖

### **FR2. 語法修正系統**

#### **FR2.1 錯誤檢測與顯示**
**優先級**: P0 (必須)

**功能描述**:
- 自動檢測英文句子中的語法錯誤
- 以視覺面板展示修正建議
- 提供錯誤類型說明和學習建議

**詳細需求**:
1. **檢測範圍**:
   - 時態錯誤 (如：join → joined)
   - 主謂一致 (如：get → gets)
   - 介詞使用錯誤
   - 詞序問題
2. **視覺設計**:
   - 黃色警告面板 `bg-yellow-50`
   - ⚠️ 警告圖標
   - 原始句子與修正建議對比顯示
3. **操作選項**:
   - ✅ 採用修正 (綠色按鈕)
   - 📝 保持原樣 (灰色按鈕)

#### **FR2.2 修正建議處理**
**優先級**: P0 (必須)

**功能描述**:
- 用戶可選擇接受或拒絕語法修正建議
- 基於用戶選擇更新後續的學習內容

**詳細需求**:
1. **採用修正**: 使用修正後句子進行詞彙學習
2. **保持原樣**: 使用原始輸入進行詞彙學習
3. **確認訊息**: 顯示用戶選擇的確認提示
4. **學習連續性**: 確保後續功能基於正確版本

---

### **FR3. 個人化詞彙標記系統**

#### **FR3.1 CEFR等級比較機制**
**優先級**: P0 (必須)

**功能描述**:
- 基於用戶CEFR等級與詞彙難度進行即時比較
- 前端直接處理分類邏輯，不依賴後端判定

**分類邏輯**:
```
用戶等級 vs 詞彙等級：
- 用戶 > 詞彙 → 簡單詞彙 (灰色虛線)
- 用戶 = 詞彙 → 適中難度詞彙 (綠色邊框)
- 用戶 < 詞彙 → 艱難詞彙 (橙色邊框)
- 慣用語標記 → 藍色邊框，在慣用語區域顯示
```

**詳細需求**:
1. **等級讀取**: 從localStorage讀取用戶CEFR等級
2. **預設等級**: 未設定時預設為A1
3. **即時分類**: 詞彙標記隨用戶等級變更即時更新
4. **冠勇與處理**: 慣用語詞彙不在句子中標記，統一在慣用語區域顯示

#### **FR3.2 視覺標記規格**
**優先級**: P0 (必須)

**功能描述**:
- 為不同類型詞彙提供清晰的視覺區分
- 確保標記不影響句子可讀性

**視覺規格**:
1. **簡單詞彙**:
   - 樣式：`bg-gray-50 border border-dashed border-gray-300`
   - 顏色：`text-gray-600 opacity-80`
   - 含義：已掌握的詞彙
2. **適中難度詞彙**:
   - 樣式：`bg-green-50 border border-green-200`
   - 顏色：`text-green-700 font-medium`
   - 含義：重點學習目標
3. **艱難詞彙**:
   - 樣式：`bg-orange-50 border border-orange-200`
   - 顏色：`text-orange-700 font-medium`
   - 含義：挑戰性詞彙
4. **無標記詞彙**: 純黑字，無特殊樣式

### **FR4. 詞彙統計展示系統**

#### **FR4.1 四張統計卡片設計**
**優先級**: P0 (必須)

**功能描述**:
- 在例句上方顯示詞彙分布統計
- 提供快速的學習難度評估

**卡片規格**:
1. **簡單詞彙卡片**:
   - 背景：灰色虛線邊框
   - 數字：大字體顯示數量
   - 標籤：「太簡單啦」
2. **適中難度詞彙卡片**:
   - 背景：綠色邊框
   - 數字：綠色大字體
   - 標籤：「重點學習」
3. **艱難詞彙卡片**:
   - 背景：橙色邊框
   - 數字：橙色大字體
   - 標籤：「有點挑戰」
4. **慣用語卡片**:
   - 背景：藍色邊框
   - 數字：藍色大字體
   - 標籤：「慣用語」

**詳細需求**:
1. **響應式佈局**: 桌面一行四張，移動設備兩行
2. **即時更新**: 統計數據隨分析結果即時更新
3. **數字突出**: 使用大字體突出顯示統計數量
4. **顏色一致**: 與對應的詞彙標記顏色保持一致

#### **FR4.2 動態統計計算**
**優先級**: P0 (必須)

**功能描述**:
- 根據用戶CEFR等級動態計算詞彙分類統計
- 支援個人化的學習數據展示

**計算需求**:
1. **實時計算**: 基於當前用戶等級進行分類統計
2. **性能優化**: 使用記憶化避免重複計算
3. **準確性**: 確保統計數字與實際標記一致
4. **更新機制**: 用戶更改等級時統計即時更新

---

### **FR5. 慣用語展示與互動系統**

#### **FR5.1 慣用語獨立展示區域**
**優先級**: P0 (必須)

**功能描述**:
- 在翻譯後方獨立展示句子中識別的慣用語和慣用語
- 提供與例句詞彙一致的互動體驗

**展示需求**:
1. **位置**: 中文翻譯區域下方
2. **標題**: 「慣用語」，使用統一的標題樣式
3. **標籤設計**:
   - 藍色主題 `bg-blue-50 border border-blue-200`
   - 與例句詞彙標記使用相同的基礎樣式
   - 支援hover效果和點擊互動
4. **佈局**: 使用flexbox排列，支援多個慣用語並排顯示

#### **FR5.2 慣用語詳情彈窗**
**優先級**: P0 (必須)

**功能描述**:
- 點擊慣用語標籤顯示完整的慣用語資訊彈窗
- 提供與詞彙彈窗一致的設計和功能

**彈窗需求**:
1. **觸發方式**: 點擊慣用語標籤
2. **彈窗內容**:
   - 慣用語名稱和CEFR等級
   - 中文翻譯（綠色區塊）
   - 英文定義（灰色區塊）
   - 例句和翻譯（藍色區塊）
   - 保存到詞卡按鈕
3. **設計一致性**: 與詞彙彈窗使用相同的視覺風格
4. **關閉機制**: 點擊外部或關閉按鈕可關閉

---

### **FR6. 互動式詞彙學習系統**

#### **FR6.1 詞彙點擊互動**
**優先級**: P0 (必須)

**功能描述**:
- 點擊標記的詞彙顯示詳細學習資訊
- 支援詞彙保存到個人詞卡庫

**互動需求**:
1. **點擊目標**: 所有有標記的詞彙（綠色、橙色、灰色）
2. **彈窗定位**: 智能計算位置，避免超出螢幕邊界
3. **響應速度**: 點擊後100ms內顯示彈窗
4. **移動適配**: 移動設備上適當調整彈窗大小和位置

#### **FR6.2 詞彙詳情彈窗**
**優先級**: P0 (必須)

**功能描述**:
- 全螢幕式彈窗展示詞彙的完整學習資訊
- 與現有詞卡系統保持100%視覺一致

**彈窗結構需求**:
1. **標題區域**:
   - 漸層藍色背景
   - 詞彙名稱（大字體加粗）
   - 詞性標籤、發音、CEFR等級標籤
   - 關閉按鈕（右上角）
2. **內容區域**:
   - 翻譯區塊：綠色背景
   - 定義區塊：灰色背景
   - 例句區塊：藍色背景（條件顯示）
   - 同義詞區塊：紫色背景（條件顯示）
3. **操作區域**:
   - 保存到詞卡按鈕（全寬藍色按鈕）

---

### **FR7. 學習輔助功能**

#### **FR7.1 個人化程度指示器**
**優先級**: P1 (重要)

**功能描述**:
- 顯示用戶當前CEFR等級和對應的學習範圍
- 提供快速調整等級的入口

**顯示需求**:
1. **程度顯示**: 🎯 您的程度: A2
2. **學習範圍**: 📈 重點學習範圍: B1-B2
3. **調整連結**: ⚙️ 調整（連結到設定頁面）
4. **位置**: 分析按鈕下方居中顯示

#### **FR7.2 學習提示系統**
**優先級**: P2 (建議)

**功能描述**:
- 提供詞彙樣式的說明和學習建議
- 幫助用戶理解不同標記的含義

**提示需求**:
1. **樣式示例**: 使用實際的詞彙標記樣式作為示例
2. **Hover說明**: 滑鼠移到樣式上顯示詳細說明
3. **個人化訊息**:
   - 簡單詞彙：對你來說太簡單
   - 適中難度詞彙：對你來說剛剛好
   - 艱難詞彙：對你來說較難

---

## 🎨 **非功能性需求**

### **NFR1. 用戶體驗需求**

#### **NFR1.1 響應時間要求**
```yaml
頁面載入時間: < 2秒
詞彙標記渲染: < 100ms
彈窗開啟時間: < 200ms
統計卡片更新: < 50ms
AI分析回應: < 5秒
```

#### **NFR1.2 互動流暢度**
```yaml
動畫幀率: 60 FPS
觸控響應: < 16ms
scroll 流暢度: 無卡頓
resize 適應: < 100ms
```

### **NFR2. 可用性需求**

#### **NFR2.1 易用性指標**
- **學習曲線**: 新用戶5分鐘內掌握基本操作
- **操作效率**: 完成一次完整分析學習 < 2分鐘
- **錯誤率**: 用戶操作錯誤率 < 5%
- **滿意度**: 用戶體驗評分 > 4.5/5

#### **NFR2.2 無障礙需求**
- **鍵盤導航**: 支援Tab鍵導航所有交互元素
- **螢幕閱讀器**: 提供適當的aria-label
- **顏色對比**: 符合WCAG 2.1 AA標準 (4.5:1)
- **字體大小**: 支援瀏覽器字體縮放

---

### **NFR3. 兼容性需求**

#### **NFR3.1 瀏覽器支援**
```yaml
Chrome: >= 90
Safari: >= 14
Firefox: >= 88
Edge: >= 90
移動Safari: >= 14
移動Chrome: >= 90
```

#### **NFR3.2 設備支援**
```yaml
桌面解析度:
  - 1920x1080 (主要)
  - 1366x768 (次要)
  - 2560x1440 (高解析度)

移動設備:
  - iPhone: 375x667 ~ 428x926
  - Android: 360x640 ~ 412x915
  - iPad: 768x1024 ~ 1024x1366
```

---

## 🔧 **技術需求**

### **TR1. 前端架構需求**

#### **TR1.1 技術棧要求**
```yaml
框架: Next.js >= 15.0
語言: TypeScript >= 5.0
樣式: Tailwind CSS >= 3.0
狀態管理: React Hooks
API通信: Fetch API
```

#### **TR1.2 性能要求**
```yaml
包大小:
  - 初始包 < 500KB
  - 總包大小 < 2MB
記憶體使用:
  - 初始記憶體 < 50MB
  - 峰值記憶體 < 100MB
  - 無記憶體洩漏
```

### **TR2. 整合需求**

#### **TR2.1 後端API整合**
**端點**: `POST /api/ai/analyze-sentence`

**請求需求**:
```json
{
  "inputText": "英文句子",
  "userLevel": "A2",
  "analysisMode": "full"
}
```

**回應處理需求**:
```json
{
  "success": true,
  "data": {
    "WordAnalysis": "詞彙分析對象",
    "SentenceMeaning": "句子翻譯",
    "GrammarCorrection": "語法修正資料"
  }
}
```

#### **TR2.2 本地存儲整合**
**需求**:
1. **用戶等級**: `localStorage.getItem('userEnglishLevel')`
2. **認證Token**: `localStorage.getItem('auth_token')`
3. **錯誤處理**: 處理存儲不可用的情況
4. **資料同步**: 支援跨設備的設定同步（未來）

---

## 📊 **數據需求**

### **DR1. 詞彙分析數據**

#### **DR1.1 必需欄位**
```typescript
interface WordAnalysisRequired {
  word: string          // 必需：詞彙本身
  translation: string   // 必需：中文翻譯
  definition: string    // 必需：英文定義
  partOfSpeech: string  // 必需：詞性
  pronunciation: string // 必需：發音
  difficultyLevel: string // 必需：CEFR等級
  isIdiom: boolean     // 必需：是否為慣用語
}
```

#### **DR1.2 可選欄位**
```typescript
interface WordAnalysisOptional {
  synonyms?: string[]        // 可選：同義詞陣列
  example?: string          // 可選：例句
  exampleTranslation?: string // 可選：例句翻譯
}
```

---

## 🧪 **測試需求**

### **TEST1. 功能測試需求**

#### **TEST1.1 核心功能測試**
**測試案例**: TC001 - 完整分析流程

**測試步驟**:
1. 輸入測試句子：「She just join the team, so let's cut her some slack until she get used to the workflow.」
2. 點擊分析按鈕
3. 驗證語法修正面板顯示
4. 選擇採用修正
5. 驗證詞彙統計卡片數量
6. 驗證詞彙標記正確性
7. 點擊詞彙驗證彈窗顯示
8. 驗證慣用語展示區域

**預期結果** (用戶A2等級):
- 語法修正：顯示2個錯誤修正
- 簡單詞彙：8個
- 適中詞彙：4個
- 艱難詞彙：3個
- 慣用語：1個

#### **TEST1.2 邊界值測試**
**測試案例**: TC002 - 輸入限制測試

**測試步驟**:
1. 輸入299字元 → 正常顯示
2. 輸入300字元 → 顯示警告但允許
3. 嘗試輸入301字元 → 阻止輸入
4. 輸入空字串 → 分析按鈕禁用

### **TEST2. 性能測試需求**

#### **TEST2.1 載入性能測試**
**測試目標**:
- 首次載入 < 2秒
- 分析響應 < 5秒
- 詞彙互動 < 100ms

#### **TEST2.2 記憶體洩漏測試**
**測試方法**:
- 連續進行20次分析操作
- 監控記憶體使用增長
- 驗證彈窗開關後記憶體釋放

---

## 🔒 **安全需求**

### **SEC1. 前端安全**

#### **SEC1.1 輸入安全**
**需求**:
1. **XSS防護**: 過濾HTML標籤和腳本
2. **長度限制**: 嚴格執行300字元限制
3. **特殊字元**: 正確處理標點符號和Unicode

#### **SEC1.2 API安全**
**需求**:
1. **Token驗證**: 每次API請求包含有效token
2. **HTTPS強制**: 生產環境強制使用HTTPS
3. **錯誤處理**: 不洩露敏感錯誤資訊

---

## 📱 **移動端需求**

### **MOB1. 移動體驗需求**

#### **MOB1.1 觸控優化**
**需求**:
1. **觸控目標**: 最小44x44px點擊區域
2. **手勢支援**: 支援點擊外部關閉彈窗
3. **防誤觸**: 詞彙間提供足夠間距
4. **載入指示**: 明確的載入狀態指示

#### **MOB1.2 版面適應**
**需求**:
1. **輸入區域**: 移動設備上高度適中
2. **統計卡片**: 兩行兩列佈局
3. **彈窗適配**: 佔用90%螢幕寬度
4. **字體縮放**: 支援系統字體大小設定

---

## 🌐 **國際化需求**

### **I18N1. 多語言支援**

#### **I18N1.1 當前支援**
- **界面語言**: 繁體中文（台灣）
- **學習語言**: 英文
- **翻譯語言**: 繁體中文

#### **I18N1.2 擴展計劃**
- **短期**: 簡體中文支援
- **中期**: 日文界面
- **長期**: 多學習語言支援

---


## 🔮 **未來擴展需求**

### **FUTURE1. 短期擴展 (1-3個月)**
- [ ] **批次分析**: 支援多句子同時分析
- [ ] **學習歷史**: 顯示過往分析記錄
- [ ] **詞彙收藏**: 快速收藏重點詞彙
- [ ] **主題設定**: 支援深色模式

### **FUTURE2. 中期擴展 (3-6個月)**
- [ ] **語音輸入**: 支援語音轉文字輸入
- [ ] **發音練習**: 整合TTS和語音評估
- [ ] **學習路徑**: 基於分析結果推薦學習計劃
- [ ] **社群功能**: 分享分析結果和學習心得

### **FUTURE3. 長期擴展 (6-12個月)**
- [ ] **多語言學習**: 支援法語、德語、西班牙語
- [ ] **AI導師**: 個人化學習建議和指導
- [ ] **AR/VR整合**: 沉浸式學習體驗
- [ ] **企業版**: 團隊學習管理功能

### **BIZ1. 使用限制**

#### **BIZ1.1 免費用戶限制**
- **分析次數**: 5次/3小時
- **功能限制**: 基礎分析功能
- **廣告**: 適當位置顯示升級提示

#### **BIZ1.2 付費用戶權益**
- **無限分析**: 移除次數限制
- **進階功能**: 批次分析、詳細報告
- **優先支援**: 客服優先處理

---

## ✅ **驗收標準**

### **ACC1. 功能驗收**

#### **ACC1.1 核心功能檢查表**
- [ ] 文本輸入和字符限制正常運作
- [ ] AI分析請求和回應處理正確
- [ ] 語法修正建議正確顯示和處理
- [ ] 詞彙標記分類準確無誤
- [ ] 統計卡片數字與實際標記一致
- [ ] 慣用語識別和展示功能完整
- [ ] 詞彙和慣用語彈窗互動正常
- [ ] 保存詞卡功能運作正常

#### **ACC1.2 用戶體驗檢查表**
- [ ] 響應式設計在各種設備上正常
- [ ] 載入時間符合性能要求
- [ ] 錯誤處理友善且有幫助
- [ ] 視覺設計一致且美觀
- [ ] 互動回饋及時且清晰

### **ACC2. 技術驗收**

#### **ACC2.1 代碼品質**
- [ ] TypeScript類型檢查零錯誤
- [ ] ESLint檢查通過
- [ ] 單元測試覆蓋率 > 80%
- [ ] 性能測試通過基準要求

#### **ACC2.2 安全檢查**
- [ ] XSS防護測試通過
- [ ] 輸入驗證覆蓋所有邊界情況
- [ ] API安全認證正確實現
- [ ] 無敏感資訊洩露

---

**文件版本**: v1.0
**產品負責人**: DramaLing產品團隊
**最後更新**: 2025-09-21
**下次審查**: 2025-10-21