# AI句子分析功能產品需求規格

## 📋 **文件資訊**

- **文件名稱**: AI句子分析功能產品需求規格
- **版本**: v2.0
- **建立日期**: 2025-01-25
- **最後更新**: 2025-01-25
- **負責團隊**: DramaLing產品團隊
- **適用範圍**: 全平台 (Web、API、未來Mobile)

---

## 🎯 **產品概述**

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

### **商業目標**
- 🎯 **提升學習效率**: 通過AI分析幫助用戶快速理解句子結構
- 💡 **個人化學習**: 基於用戶程度提供適合的學習內容
- 📈 **用戶留存**: 通過互動式體驗增加平台黏性
- 🌍 **市場差異化**: 提供業界領先的AI驅動語言學習體驗

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

---

## 🎭 **用戶故事與使用場景**

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

#### **US1.1 智能句子分析**
```gherkin
功能: 智能英文句子分析
背景: 用戶想要學習和理解英文句子

場景: 用戶分析英文句子
  給定 用戶是英語學習者
  當 用戶輸入英文句子 "She just join the team, so let's cut her some slack until she get used to the workflow."
  並且 點擊「分析句子」按鈕
  那麼 系統應該顯示語法修正建議
  並且 系統應該提供詞彙難度標記
  並且 系統應該識別慣用語 "cut someone some slack"
  並且 系統應該提供完整的中文翻譯

驗收標準:
- 能輸入最多300字的英文句子
- 分析回應時間 < 5秒
- 語法檢查準確率 > 85%
- 詞彙CEFR分級準確率 > 90%
- 慣用語識別覆蓋率 > 80%
```

#### **US1.2 個人化詞彙學習**
```gherkin
功能: 基於CEFR等級的個人化詞彙標記
背景: 不同程度的學習者需要不同的學習重點

場景: A2程度學習者查看句子分析
  給定 用戶的CEFR等級是A2
  當 系統分析句子中的詞彙
  那麼 A1詞彙應該顯示為「太簡單啦」(灰色虛線)
  並且 A2詞彙應該顯示為「重點學習」(綠色邊框)
  並且 B1+詞彙應該顯示為「有點挑戰」(橙色邊框)
  並且 慣用語應該獨立顯示為「慣用語」(藍色邊框)

驗收標準:
- 詞彙分類基於用戶當前CEFR等級動態計算
- 用戶可以調整CEFR等級設定
- 等級變更時詞彙標記即時更新
- 統計卡片數字與實際標記一致
```

#### **US1.3 語法修正學習**
```gherkin
功能: 智能語法錯誤檢測和修正建議
背景: 學習者需要了解和改正語法錯誤

場景: 用戶獲得語法修正建議
  給定 用戶輸入有語法錯誤的句子
  當 系統完成分析
  那麼 系統應該顯示語法修正面板
  並且 提供原句與修正句的對比
  並且 解釋每個錯誤的類型和原因
  並且 用戶可以選擇採用修正或保持原樣

驗收標準:
- 檢測時態錯誤、主謂一致、介詞使用、詞序問題
- 提供繁體中文的錯誤解釋
- 修正建議自然且符合語言習慣
- 用戶選擇後影響後續的詞彙學習內容
```

### **US2. 深度學習互動**

#### **US2.1 詞彙探索學習**
```gherkin
功能: 互動式詞彙詳情查看
背景: 學習者想要深入了解特定詞彙

場景: 用戶點擊詞彙查看詳情
  給定 句子已完成分析並顯示詞彙標記
  當 用戶點擊任何標記的詞彙
  那麼 系統應該顯示詞彙詳情彈窗
  並且 包含中文翻譯、英文定義、發音
  並且 提供同義詞和實用例句
  並且 提供「保存到詞卡」功能

驗收標準:
- 所有標記詞彙都可點擊
- 彈窗定位智能，不超出螢幕邊界
- 彈窗開啟時間 < 200ms
- 詞彙資料完整且準確
```

#### **US2.2 慣用語學習**
```gherkin
功能: 慣用語識別和學習
背景: 學習者需要掌握地道的英語表達

場景: 用戶學習句子中的慣用語
  給定 句子包含慣用語表達
  當 系統完成分析
  那麼 慣用語應該在專門區域顯示
  並且 不在句子中重複標記
  並且 點擊慣用語可查看詳細解釋
  並且 包含文化背景和使用場景

驗收標準:
- 慣用語、片語動詞、固定搭配的準確識別
- 提供文化背景和使用建議
- 與詞彙詳情彈窗一致的視覺設計
- 支援保存到個人詞彙庫
```

---

## 📋 **功能需求規格 (Functional Requirements)**

### **FR1. 智能分析引擎**

#### **FR1.1 文本輸入處理**
**優先級**: P0 (必須)

**需求描述**:
- 支援多語言文本輸入（主要英文）
- 文本長度限制和即時驗證
- 特殊字符和格式處理

**詳細規格**:
```yaml
輸入限制:
  - 最大長度: 300字符
  - 支援字符: 英文字母、數字、標點符號
  - 警告機制: 280字符黃色警告，300字符禁止輸入
  - 即時驗證: 字符計數顯示，超限阻止提交

錯誤處理:
  - 空字串: 禁用分析按鈕
  - 無效字符: 自動過濾或提示
  - 超長文本: 截斷並警告用戶
```

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

**需求描述**:
- 整合AI語言模型進行句子分析
- 支援多維度分析結果
- 確保分析準確性和一致性

**詳細規格**:
```yaml
分析範圍:
  - 語法檢查: 時態、主謂一致、介詞、詞序
  - 詞彙分析: CEFR等級、詞性、發音、翻譯、使用頻率
  - 句子翻譯: 自然流暢的繁體中文
  - 慣用語識別: 慣用語、片語動詞、固定搭配、使用頻率

API回應格式:
  - 詞彙物件須包含: word, definition, translation, cefrLevel, isCommon
  - 慣用語物件須包含: idiom, meaning, translation, isCommon
  - 頻率資料來源: AI模型基於語料庫統計分析
  - 容錯處理: isCommon欄位缺失時預設為false

品質要求:
  - 語法檢查準確率: > 85%
  - CEFR分級準確率: > 90%
  - 翻譯自然度評分: > 4.0/5.0
  - 慣用語識別率: > 80%
  - 常用詞頻率判定準確率: > 85%

性能要求:
  - 分析響應時間: < 5秒
  - 同時支援用戶數: > 100
  - 服務可用性: > 99.5%
```

### **FR2. 個人化學習系統**

#### **FR2.1 CEFR等級個人化**
**優先級**: P0 (必須)

**需求描述**:
- 基於用戶CEFR等級提供個人化詞彙分類
- 支援等級調整和即時更新
- 提供學習進度指引

**詳細規格**:
```yaml
分類邏輯:
  - 簡單詞彙: 用戶等級 > 詞彙等級
  - 適中詞彙: 用戶等級 = 詞彙等級
  - 困難詞彙: 用戶等級 < 詞彙等級
  - 慣用語: 獨立分類，不參與等級比較

支援等級:
  - A1: 初學者 (約1000詞彙)
  - A2: 基礎 (約2000詞彙)
  - B1: 中級 (約3000詞彙)
  - B2: 中高級 (約4000詞彙)
  - C1: 高級 (約8000詞彙)
  - C2: 精通 (約15000詞彙)

更新機制:
  - 等級變更即時重新分類
  - 本地存儲用戶設定
  - 跨設備同步 (未來功能)
```

#### **FR2.2 學習進度可視化**
**優先級**: P0 (必須)

**需求描述**:
- 提供直觀的詞彙難度分布統計
- 支援學習重點識別
- 幫助用戶評估學習挑戰

**詳細規格**:
```yaml
統計卡片:
  - 簡單詞彙卡片: 灰色虛線，「太簡單啦」
  - 適中詞彙卡片: 綠色邊框，「重點學習」
  - 困難詞彙卡片: 橙色邊框，「有點挑戰」
  - 慣用語卡片: 藍色邊框，「慣用語」

計算邏輯:
  - 前端即時計算統計數據
  - 基於當前用戶等級動態分類
  - 統計數字與實際標記保持一致
  - 用戶等級變更時即時更新
```

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

#### **FR3.1 詞彙深度探索**
**優先級**: P0 (必須)

**需求描述**:
- 提供豐富的詞彙學習資訊
- 支援多感官學習體驗
- 整合個人詞彙管理

**詳細規格**:
```yaml
詞彙詳情內容:
  - 基礎資訊: 詞彙、翻譯、定義、詞性
  - 語音資訊: IPA發音標記、音頻播放功能
  - 學習輔助: 同義詞、例句、例句翻譯
  - 個人化: CEFR等級、學習狀態
  - 使用頻率: 除了簡單詞彙「學習者的CEFR>詞彙CEFR」以外，當詞彙為常用時，於詞彙框線內右上角顯示星星

前端渲染邏輯:
  - 條件渲染: 檢查 isCommon 欄位存在且為 true 時顯示 ⭐
  - 容錯處理: 當 isCommon 欄位缺失或為 false 時不顯示星星
  - 佈局保護: 確保星星不影響詞彙文字的可讀性和佈局
  - 一致性檢查: 所有詞彙類型使用相同的星星顯示邏輯

互動功能:
  - 點擊詞彙開啟詳情彈窗
  - 一鍵保存到個人詞卡庫
  - 發音練習 (未來功能)
  - 相關詞彙推薦 (未來功能)
```

#### **FR3.2 慣用語文化學習**
**優先級**: P0 (必須)

**需求描述**:
- 深度學習英語慣用語和文化表達
- 提供使用場景和文化背景
- 支援實際應用練習

**詳細規格**:
```yaml
慣用語資訊:
  - 基礎定義: 慣用語、中英文解釋、發音
  - 學習輔助: 同義表達、實用例句
  - 難度標記: CEFR等級
  - 使用頻率: 除了簡單慣用語「學習者的CEFR>慣用語CEFR」以外，當慣用語為常用時，於慣用語框線內右上角顯示星星

前端渲染邏輯:
  - 條件渲染: 檢查 isCommon 欄位存在且為 true 時顯示 ⭐
  - 容錯處理: 當 isCommon 欄位缺失或為 false 時不顯示星星
  - 佈局保護: 確保星星不影響慣用語文字的可讀性和佈局
  - 一致性檢查: 與詞彙標記使用相同的星星顯示邏輯

展示方式:
  - 獨立區域展示，不與一般詞彙混淆
  - 統一的視覺設計和互動體驗
  - 支援多個慣用語並排顯示
  - 與詞彙詳情一致的彈窗設計
```

---

## 🔧 **非功能性需求 (Non-Functional Requirements)**

### **NFR1. 性能需求**

#### **NFR1.1 響應時間要求**
```yaml
核心功能:
  - 文本輸入響應: < 100ms
  - AI分析處理: < 5秒
  - 詞彙標記渲染: < 200ms
  - 詞彙詳情彈窗: < 100ms
  - 統計卡片更新: < 50ms

系統負載:
  - 同時在線用戶: > 100
  - 每日分析請求: > 10,000
  - 峰值處理能力: > 200 req/min
  - 系統可用性: > 99.5%
```

#### **NFR1.2 可擴展性要求**
```yaml
用戶擴展:
  - 支援用戶數: 10,000+ (第一年)
  - 數據存儲: 100GB+ (分析記錄)
  - 並發處理: 500+ 同時請求

功能擴展:
  - 多語言支援: 法語、德語 (未來)
  - 多模態分析: 語音、圖片 (未來)
  - 實時協作: 團隊學習 (未來)
```

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

#### **NFR2.1 易用性標準**
```yaml
學習曲線:
  - 新用戶上手時間: < 5分鐘
  - 完整分析流程: < 2分鐘
  - 功能發現時間: < 30秒

操作效率:
  - 點擊響應時間: < 100ms
  - 頁面載入時間: < 2秒
  - 功能切換時間: < 500ms
  - 錯誤恢復時間: < 3秒

滿意度指標:
  - 用戶體驗評分: > 4.5/5
  - 功能完成率: > 95%
  - 錯誤率: < 5%
```

#### **NFR2.2 無障礙需求**
```yaml
WCAG 2.1 AA 合規:
  - 顏色對比度: > 4.5:1
  - 鍵盤導航: 完整支援
  - 螢幕閱讀器: 適當的ARIA標籤
  - 字體縮放: 支援200%放大

多設備支援:
  - 桌面瀏覽器: Chrome 90+, Safari 14+, Firefox 88+
  - 移動設備: iOS 14+, Android 10+
  - 響應式設計: 320px - 2560px
```

### **NFR3. 安全與隱私需求**

#### **NFR3.1 數據安全**
```yaml
輸入安全:
  - XSS防護: 輸入內容過濾和轉義
  - 內容驗證: 惡意內容檢測
  - 長度限制: 嚴格執行字符限制

數據隱私:
  - 個人數據: 符合GDPR要求
  - 學習記錄: 用戶控制和導出
  - 數據保留: 明確的保留政策
  - 匿名化: 分析統計數據去識別

頻率資料錯誤處理:
  - API回應缺失 isCommon 欄位時的降級策略
  - 前端容錯機制: 不影響核心分析功能運作
  - 錯誤記錄: 追蹤頻率資料異常情況以便改進
  - 用戶體驗: 星星缺失不影響其他學習功能
```

#### **NFR3.2 API安全**
```yaml
認證授權:
  - JWT Token認證
  - 角色權限控制
  - 速率限制保護

數據傳輸:
  - HTTPS強制加密
  - API金鑰安全管理
  - 請求簽名驗證
```

---

## 🎨 **用戶介面需求**

### **UI1. 視覺設計標準**

#### **UI1.1 詞彙標記設計**
```yaml
視覺層次:
  - 簡單詞彙: bg-gray-50, border-dashed, border-gray-300, text-gray-600, opacity-80
  - 適中詞彙: bg-green-50, border-green-200, text-green-700, font-medium
  - 困難詞彙: bg-orange-50, border-orange-200, text-orange-700, font-medium
  - 慣用語: bg-blue-50, border-blue-200, text-blue-700

常用標記設計:
  - 圖示: ⭐ emoji星星
  - 位置: 詞彙框線內右上角，絕對定位
  - 大小: 12px (桌面) / 10px (移動設備)
  - 顯示條件: 僅當 isCommon === true 時顯示
  - 層級: 確保在詞彙文字之上，不遮擋內容
  - 響應式: 在所有詞彙類型中一致顯示

互動效果:
  - hover: 陰影提升，輕微上移
  - focus: 鍵盤導航支援
  - active: 點擊回饋動畫
  - 星星: 無互動行為，純視覺標記
```

#### **UI1.2 統計卡片設計**
```yaml
卡片規格:
  - 響應式佈局: 桌面1行4張，移動設備2行2張
  - 數字突出: 大字體顯示統計數量
  - 顏色一致: 與對應詞彙標記顏色匹配
  - 即時更新: 分析完成後動畫顯示
```

### **UI2. 互動體驗設計**

#### **UI2.1 彈窗系統設計**
```yaml
詞彙詳情彈窗:
  - 標題區: 漸層藍色背景，詞彙名稱，CEFR標籤
  - 內容區: 翻譯(綠)、定義(灰)、例句(藍)、同義詞(紫)
  - 操作區: 保存按鈕，關閉按鈕
  - 定位: 智能計算，避免螢幕邊界

語法修正面板:
  - 警告樣式: 黃色背景，警告圖標
  - 對比顯示: 原句 vs 修正句
  - 操作按鈕: 採用修正(綠色)，保持原樣(灰色)
```

---

## 🧪 **驗收標準與測試需求**

### **AC1. 功能驗收標準**

#### **AC1.1 核心功能檢查表**
- [ ] 文本輸入和字符限制正常運作
- [ ] AI分析在5秒內完成並返回結果
- [ ] 語法修正準確檢測並提供合理建議
- [ ] 詞彙CEFR分級準確率達到90%以上
- [ ] 慣用語識別覆蓋率達到80%以上
- [ ] 個人化詞彙標記根據用戶等級正確分類
- [ ] 統計卡片數字與實際詞彙標記一致
- [ ] 詞彙和慣用語詳情彈窗正常運作
- [ ] 保存到詞卡功能完整可用
- [ ] 常用詞彙正確顯示⭐星星標記在框線右上角
- [ ] 非常用詞彙不顯示星星標記
- [ ] isCommon欄位缺失時功能正常降級，不顯示星星
- [ ] 星星標記不影響詞彙文字可讀性和整體佈局
- [ ] 響應式設計中星星標記在所有設備正常顯示

#### **AC1.2 用戶體驗檢查表**
- [ ] 新用戶能在5分鐘內完成首次完整分析
- [ ] 所有互動響應時間符合性能要求
- [ ] 響應式設計在所有目標設備正常顯示
- [ ] 錯誤處理友善且提供有用指導
- [ ] 視覺設計一致且符合品牌標準

### **AC2. 技術驗收標準**

#### **AC2.1 API品質檢查**
- [ ] API回應格式穩定一致
- [ ] 錯誤處理涵蓋所有邊界情況
- [ ] 性能指標達到要求基準
- [ ] 安全檢查通過滲透測試

#### **AC2.2 資料品質檢查**
- [ ] AI分析結果準確性達標
- [ ] 繁體中文翻譯自然流暢
- [ ] CEFR等級分配符合標準
- [ ] 慣用語解釋準確且完整

---

## 🚀 **產品路線圖**

### **Phase 1: 核心功能 (已完成)**
- ✅ 基礎AI句子分析
- ✅ 詞彙標記和分類
- ✅ 語法修正功能
- ✅ 慣用語識別

### **Phase 2: 體驗優化 (當前階段)**
- 🔄 性能優化和穩定性提升
- 🔄 用戶介面細節優化
- ⏳ 錯誤處理完善
- ⏳ 無障礙功能實施

### **Phase 3: 功能擴展 (規劃中)**
- 📅 批次分析功能
- 📅 學習歷史記錄
- 📅 個人詞彙庫進階管理
- 📅 語音集成 (TTS/STT)

### **Phase 4: 平台擴展 (未來)**
- 🔮 多語言學習支援
- 🔮 移動應用開發
- 🔮 團隊協作功能
- 🔮 AI模型自定義

---

## 📊 **成功指標 (KPIs)**

### **產品指標**
```yaml
用戶參與度:
  - 日活躍用戶數 (DAU): > 1,000
  - 平均每用戶分析次數: > 5次/日
  - 用戶留存率 (7天): > 70%
  - 功能使用率: > 80%

學習效果:
  - 用戶滿意度評分: > 4.5/5
  - 學習目標完成率: > 85%
  - 詞彙掌握改善度: > 30%
  - 重複使用率: > 60%
```

### **技術指標**
```yaml
性能指標:
  - API回應時間P95: < 5秒
  - 頁面載入時間P95: < 2秒
  - 系統可用性: > 99.5%
  - 錯誤率: < 1%

品質指標:
  - AI分析準確率: > 90%
  - 代碼覆蓋率: > 80%
  - 安全掃描通過率: 100%
  - 用戶回報問題解決率: > 95%
```

---

## 🔄 **變更管理**

### **需求變更流程**
1. **提出變更**: 產品經理、開發團隊、用戶回饋
2. **影響評估**: 技術可行性、工期影響、資源需求
3. **優先級評定**: 商業價值、緊急程度、實施成本
4. **審核批准**: 產品委員會審核決定
5. **實施追蹤**: 開發進度、測試驗證、上線監控

### **文件版本管理**
- **v1.0**: 初始需求規格 (2025-09-21)
- **v2.0**: 整合統一產品需求規格 (2025-01-25)

---

**文件版本**: v2.0
**產品負責人**: DramaLing產品團隊
**最後更新**: 2025-01-25
**下次審查**: 2025-02-25

**關聯文件**:
- 《AI分析API技術實現規格》- 技術實現細節
- 《系統整合與部署規格》- 系統整合和部署
- 《AI驅動產品後端技術架構指南》- 架構設計指導


待辦
- [x] 顯示常用
- [x] 所有詞彙都要分析
- [ ] 點圖+，就會生出例
- [ ] 句圖
- [ ] 點播放，要能生出語音
- [ ] 儲存詞彙的後端還沒做好