docs: 更新產品需求規格並添加待辦清單
📝 文檔更新: • 在AI句子分析功能產品需求規格.md中添加待辦清單 • 記錄需要進一步實現的功能需求 📋 待辦項目: • 顯示常用詞彙功能 • 確保所有詞彙都進行分析 • 點擊圖+生成例句圖功能 • 點播放生成語音功能 • 儲存詞彙的後端API整合 🎯 改善效果: • 明確下一步開發方向 • 追蹤功能完整性 • 提升產品規劃清晰度 🚀 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
parent
ad919ec5b7
commit
add6e2a3dc
198
AI功能使用說明.md
198
AI功能使用說明.md
|
|
@ -1,198 +0,0 @@
|
||||||
# DramaLing AI功能使用說明
|
|
||||||
|
|
||||||
## 🎯 **功能概述**
|
|
||||||
|
|
||||||
DramaLing的AI生成功能現已完全實現，支持智能英文句子分析、語法修正、詞彙標記和慣用語識別。
|
|
||||||
|
|
||||||
## 🛠️ **開發環境設置**
|
|
||||||
|
|
||||||
### **1. 設置Gemini API Key**
|
|
||||||
|
|
||||||
#### **方法一：使用.NET User Secrets**
|
|
||||||
```bash
|
|
||||||
cd backend/DramaLing.Api
|
|
||||||
dotnet user-secrets set "Gemini:ApiKey" "你的真實Gemini API Key"
|
|
||||||
```
|
|
||||||
|
|
||||||
### **2. 啟動服務**
|
|
||||||
|
|
||||||
#### **後端服務（port 5000）**
|
|
||||||
```bash
|
|
||||||
cd backend/DramaLing.Api
|
|
||||||
dotnet run
|
|
||||||
```
|
|
||||||
|
|
||||||
#### **前端服務（port 3000）**
|
|
||||||
```bash
|
|
||||||
cd frontend
|
|
||||||
npm run dev
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🔧 **技術架構**
|
|
||||||
|
|
||||||
### **後端API端點**
|
|
||||||
- `POST /api/ai/analyze-sentence` - 句子智能分析
|
|
||||||
- `GET /api/ai/health` - AI服務健康檢查
|
|
||||||
|
|
||||||
### **前端頁面**
|
|
||||||
- `http://localhost:3000/generate` - AI分析主頁面
|
|
||||||
|
|
||||||
## 🎯 **使用流程**
|
|
||||||
|
|
||||||
### **1. 用戶操作**
|
|
||||||
1. 在輸入框中輸入英文句子（最多300字符）
|
|
||||||
2. 點擊「🔍 分析句子」按鈕
|
|
||||||
3. 查看語法修正建議（如有）
|
|
||||||
4. 瀏覽詞彙統計卡片
|
|
||||||
5. 點擊標記的詞彙查看詳細資訊
|
|
||||||
6. 點擊慣用語查看解釋
|
|
||||||
7. 保存感興趣的詞彙到詞卡
|
|
||||||
|
|
||||||
### **2. 系統處理**
|
|
||||||
1. 前端發送API請求到後端
|
|
||||||
2. 後端檢查使用限制和快取
|
|
||||||
3. 調用Gemini API進行分析
|
|
||||||
4. 處理和格式化回應數據
|
|
||||||
5. 快取結果並返回前端
|
|
||||||
6. 前端渲染分析結果
|
|
||||||
|
|
||||||
## 📊 **功能特色**
|
|
||||||
|
|
||||||
### **✅ 已實現功能**
|
|
||||||
|
|
||||||
#### **🤖 AI智能分析**
|
|
||||||
- **語法檢查** - 自動檢測時態、主謂一致等錯誤
|
|
||||||
- **詞彙分析** - 提供翻譯、定義、發音、CEFR等級
|
|
||||||
- **慣用語識別** - 智能識別句子中的習語和片語
|
|
||||||
- **中文翻譯** - 自然流暢的繁體中文翻譯
|
|
||||||
|
|
||||||
#### **🎯 個人化學習**
|
|
||||||
- **CEFR等級比較** - 基於用戶程度標記詞彙難度
|
|
||||||
- **視覺化分類** - 不同顏色標記不同難度詞彙
|
|
||||||
- **統計卡片** - 直觀展示詞彙分布
|
|
||||||
- **學習提示** - 幫助用戶理解標記含義
|
|
||||||
|
|
||||||
#### **💡 互動體驗**
|
|
||||||
- **彈窗詳情** - 點擊詞彙查看完整資訊
|
|
||||||
- **智能定位** - 彈窗自動避開螢幕邊界
|
|
||||||
- **一鍵保存** - 直接保存到個人詞卡庫
|
|
||||||
- **響應式設計** - 支援桌面和移動設備
|
|
||||||
|
|
||||||
#### **⚡ 性能優化**
|
|
||||||
- **快取機制** - 避免重複分析相同句子
|
|
||||||
- **使用限制** - 免費用戶每日5次分析
|
|
||||||
- **錯誤處理** - 優雅的錯誤回饋和回退機制
|
|
||||||
- **記憶化** - 前端性能優化
|
|
||||||
|
|
||||||
## 🔒 **安全設計**
|
|
||||||
|
|
||||||
### **API認證**
|
|
||||||
- 使用JWT Bearer Token認證
|
|
||||||
- 每個請求都需要有效的認證Token
|
|
||||||
|
|
||||||
### **使用限制**
|
|
||||||
- 免費用戶：每日5次分析
|
|
||||||
- 付費用戶：無限制使用
|
|
||||||
- 3小時重置週期
|
|
||||||
|
|
||||||
### **數據安全**
|
|
||||||
- API Key使用User Secrets安全存儲
|
|
||||||
- 敏感資訊不寫入代碼
|
|
||||||
- HTTPS傳輸加密
|
|
||||||
|
|
||||||
## 🧪 **測試模式**
|
|
||||||
|
|
||||||
### **真實API模式**
|
|
||||||
設置真實Gemini API Key後：
|
|
||||||
- 調用Google Gemini Pro模型
|
|
||||||
- 真實的AI分析結果
|
|
||||||
- 動態的詞彙和語法分析
|
|
||||||
- 支援任意英文句子
|
|
||||||
|
|
||||||
## 📈 **測試案例**
|
|
||||||
|
|
||||||
### **測試句子**
|
|
||||||
```
|
|
||||||
She just join the team, so let's cut her some slack until she get used to the workflow.
|
|
||||||
```
|
|
||||||
|
|
||||||
### **預期結果（A2用戶）**
|
|
||||||
- **語法修正**: 2個錯誤修正（join→joined, get→gets）
|
|
||||||
- **詞彙統計**: 太簡單8個，重點學習4個，有挑戰3個，慣用語1個
|
|
||||||
- **慣用語**: "cut someone some slack"
|
|
||||||
- **翻譯**: "她剛加入團隊，所以讓我們對她寬容一點，直到她習慣工作流程。"
|
|
||||||
|
|
||||||
## 🔧 **故障排除**
|
|
||||||
|
|
||||||
### **常見問題**
|
|
||||||
|
|
||||||
#### **Q: API請求失敗**
|
|
||||||
```
|
|
||||||
錯誤: API請求失敗: 401
|
|
||||||
解決: 檢查localStorage中是否有有效的auth_token
|
|
||||||
```
|
|
||||||
|
|
||||||
#### **Q: 編譯錯誤**
|
|
||||||
```
|
|
||||||
錯誤: IGeminiService無法解析
|
|
||||||
解決: 確保Program.cs中正確註冊了服務
|
|
||||||
```
|
|
||||||
|
|
||||||
#### **Q: Gemini API調用失敗**
|
|
||||||
```
|
|
||||||
錯誤: Gemini API call failed
|
|
||||||
解決: 檢查API Key是否正確設置，會自動回退到Mock模式
|
|
||||||
```
|
|
||||||
|
|
||||||
### **除錯方式**
|
|
||||||
|
|
||||||
#### **檢查後端日誌**
|
|
||||||
```bash
|
|
||||||
# 查看後端控制台輸出
|
|
||||||
# 尋找 "Starting sentence analysis" 和相關錯誤訊息
|
|
||||||
```
|
|
||||||
|
|
||||||
#### **檢查前端控制台**
|
|
||||||
```javascript
|
|
||||||
// 在瀏覽器開發者工具Console中查看
|
|
||||||
// API調用和錯誤訊息
|
|
||||||
```
|
|
||||||
|
|
||||||
#### **檢查網路請求**
|
|
||||||
```
|
|
||||||
瀏覽器 → F12 → Network → 查看API請求和回應
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🚀 **生產部署**
|
|
||||||
|
|
||||||
### **環境變數設置**
|
|
||||||
```bash
|
|
||||||
# 生產環境必需設置
|
|
||||||
GEMINI_API_KEY=你的真實Gemini API Key
|
|
||||||
DRAMALING_SUPABASE_JWT_SECRET=你的JWT Secret
|
|
||||||
```
|
|
||||||
|
|
||||||
### **健康檢查**
|
|
||||||
```bash
|
|
||||||
# 檢查服務狀態
|
|
||||||
curl http://your-domain/health
|
|
||||||
curl http://your-domain/api/ai/health
|
|
||||||
```
|
|
||||||
|
|
||||||
## 📚 **開發參考**
|
|
||||||
|
|
||||||
### **相關文檔**
|
|
||||||
- `/AI生成功能後端API規格.md` - 完整API技術規格
|
|
||||||
- `/AI生成網頁前端實際功能規格.md` - 前端功能規格
|
|
||||||
- `/AI生成網頁前端需求規格.md` - 前端需求規格
|
|
||||||
|
|
||||||
### **核心檔案**
|
|
||||||
- `backend/DramaLing.Api/Controllers/AIController.cs` - API控制器
|
|
||||||
- `backend/DramaLing.Api/Services/GeminiService.cs` - AI分析服務
|
|
||||||
- `frontend/app/generate/page.tsx` - 前端主頁面
|
|
||||||
- `frontend/components/ClickableTextV2.tsx` - 詞彙互動組件
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**最後更新**: 2025-01-25
|
|
||||||
**狀態**: ✅ 功能完整，可投入使用
|
|
||||||
1111
AI生成功能前後端串接規格.md
1111
AI生成功能前後端串接規格.md
File diff suppressed because it is too large
Load Diff
807
AI生成功能後端API規格.md
807
AI生成功能後端API規格.md
|
|
@ -1,807 +0,0 @@
|
||||||
# AI生成功能後端API規格
|
|
||||||
|
|
||||||
## 📋 **文件資訊**
|
|
||||||
|
|
||||||
- **文件名稱**: AI生成功能後端API規格
|
|
||||||
- **版本**: v1.0
|
|
||||||
- **建立日期**: 2025-01-25
|
|
||||||
- **最後更新**: 2025-01-25 (修正API規格)
|
|
||||||
- **負責團隊**: DramaLing後端開發團隊
|
|
||||||
- **對應前端**: `/app/generate/page.tsx`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🎯 **API概述**
|
|
||||||
|
|
||||||
### **核心功能**
|
|
||||||
AI生成功能後端API提供智能英文句子分析服務，包含語法檢查、詞彙分析、翻譯和慣用語識別，為前端提供完整的學習數據支援。
|
|
||||||
|
|
||||||
### **主要特色**
|
|
||||||
- 🤖 **AI驅動分析** - 使用先進AI模型進行語言分析
|
|
||||||
- 🎯 **個人化標記** - 基於用戶CEFR等級的詞彙分類
|
|
||||||
- 📊 **多維度數據** - 提供詞彙、語法、翻譯、慣用語分析
|
|
||||||
- ⚡ **高性能處理** - 支援快速響應和批次處理
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🛠 **技術架構**
|
|
||||||
|
|
||||||
### **架構組成**
|
|
||||||
```yaml
|
|
||||||
API Gateway:
|
|
||||||
- 路由管理
|
|
||||||
- 認證驗證
|
|
||||||
- 流量控制
|
|
||||||
- 錯誤處理
|
|
||||||
|
|
||||||
AI Analysis Service:
|
|
||||||
- 語法分析引擎
|
|
||||||
- 詞彙分析引擎
|
|
||||||
- 翻譯服務
|
|
||||||
- 慣用語識別
|
|
||||||
|
|
||||||
Database Layer:
|
|
||||||
- 詞彙資料庫
|
|
||||||
- 用戶數據
|
|
||||||
- 分析結果緩存
|
|
||||||
- 使用記錄
|
|
||||||
|
|
||||||
External Services:
|
|
||||||
- AI模型服務
|
|
||||||
- 詞典API
|
|
||||||
- 翻譯API
|
|
||||||
```
|
|
||||||
|
|
||||||
### **技術棧要求**
|
|
||||||
```yaml
|
|
||||||
語言: C# / .NET 8
|
|
||||||
框架: ASP.NET Core Web API
|
|
||||||
資料庫: PostgreSQL + Redis (緩存)
|
|
||||||
AI服務: Google Gemini 1.5 Flash API (包含結構化Prompt設計)
|
|
||||||
部署: Docker + Kubernetes
|
|
||||||
監控: Application Insights
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📡 **API端點規格**
|
|
||||||
|
|
||||||
### **API-001: 句子智能分析**
|
|
||||||
|
|
||||||
#### **端點資訊**
|
|
||||||
```http
|
|
||||||
POST /api/ai/analyze-sentence
|
|
||||||
Content-Type: application/json
|
|
||||||
Authorization: Bearer {token}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### **請求格式**
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"inputText": "She just join the team, so let's cut her some slack until she get used to the workflow.",
|
|
||||||
"analysisMode": "full",
|
|
||||||
"options": {
|
|
||||||
"includeGrammarCheck": true,
|
|
||||||
"includeVocabularyAnalysis": true,
|
|
||||||
"includeTranslation": true,
|
|
||||||
"includeIdiomDetection": true,
|
|
||||||
"includeExamples": true
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### **請求參數說明**
|
|
||||||
| 參數 | 類型 | 必需 | 說明 |
|
|
||||||
|------|------|------|------|
|
|
||||||
| inputText | string | 是 | 待分析的英文句子 (最多300字) |
|
|
||||||
| analysisMode | string | 否 | 分析模式: "basic"\|"full" (預設: "full") |
|
|
||||||
| options | object | 否 | 分析選項配置 |
|
|
||||||
|
|
||||||
#### **成功回應格式**
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": true,
|
|
||||||
"processingTime": 2.34,
|
|
||||||
"data": {
|
|
||||||
"analysisId": "uuid-string",
|
|
||||||
"originalText": "She just join the team, so let's cut her some slack until she get used to the workflow.",
|
|
||||||
"grammarCorrection": {
|
|
||||||
"hasErrors": true,
|
|
||||||
"correctedText": "She just joined the team, so let's cut her some slack until she gets used to the workflow.",
|
|
||||||
"corrections": [
|
|
||||||
{
|
|
||||||
"position": { "start": 9, "end": 13 },
|
|
||||||
"error": "join",
|
|
||||||
"correction": "joined",
|
|
||||||
"type": "時態錯誤",
|
|
||||||
"explanation": "第三人稱單數過去式應使用 'joined'",
|
|
||||||
"severity": "high"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"position": { "start": 79, "end": 82 },
|
|
||||||
"error": "get",
|
|
||||||
"correction": "gets",
|
|
||||||
"type": "時態錯誤",
|
|
||||||
"explanation": "第三人稱單數現在式應使用 'gets'",
|
|
||||||
"severity": "high"
|
|
||||||
}
|
|
||||||
]
|
|
||||||
},
|
|
||||||
"sentenceMeaning": "她剛加入團隊，所以讓我們對她寬容一點，直到她習慣工作流程。",
|
|
||||||
"vocabularyAnalysis": {
|
|
||||||
"she": {
|
|
||||||
"word": "she",
|
|
||||||
"translation": "她",
|
|
||||||
"definition": "female person pronoun",
|
|
||||||
"partOfSpeech": "pronoun",
|
|
||||||
"pronunciation": "/ʃiː/",
|
|
||||||
"difficultyLevel": "A1",
|
|
||||||
"frequency": "very_high",
|
|
||||||
"synonyms": ["her"],
|
|
||||||
"example": "She is a teacher.",
|
|
||||||
"exampleTranslation": "她是一名老師。",
|
|
||||||
},
|
|
||||||
"just": {
|
|
||||||
"word": "just",
|
|
||||||
"translation": "剛剛；僅僅",
|
|
||||||
"definition": "recently; only",
|
|
||||||
"partOfSpeech": "adverb",
|
|
||||||
"pronunciation": "/dʒʌst/",
|
|
||||||
"difficultyLevel": "A2",
|
|
||||||
"frequency": "high",
|
|
||||||
"synonyms": ["recently", "only", "merely"],
|
|
||||||
"example": "I just arrived.",
|
|
||||||
"exampleTranslation": "我剛到。",
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"idioms": [
|
|
||||||
{
|
|
||||||
"idiom": "cut someone some slack",
|
|
||||||
"translation": "對某人寬容一點",
|
|
||||||
"definition": "to be more lenient or forgiving with someone",
|
|
||||||
"pronunciation": "/kʌt ˈsʌmwʌn səm slæk/",
|
|
||||||
"difficultyLevel": "B2",
|
|
||||||
"frequency": "medium",
|
|
||||||
"synonyms": [
|
|
||||||
"give someone a break",
|
|
||||||
"go easy on someone",
|
|
||||||
"let someone off the hook"
|
|
||||||
],
|
|
||||||
"example": "Cut him some slack, he's new here.",
|
|
||||||
"exampleTranslation": "對他寬容一點，他是新來的。"
|
|
||||||
}
|
|
||||||
],
|
|
||||||
"metadata": {
|
|
||||||
"analysisModel": "gemini-1.5-flash",
|
|
||||||
"analysisVersion": "2.0",
|
|
||||||
"processingDate": "2025-01-25T10:30:00Z",
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### **錯誤回應格式**
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": false,
|
|
||||||
"error": {
|
|
||||||
"code": "INVALID_INPUT",
|
|
||||||
"message": "輸入文本超過最大長度限制",
|
|
||||||
"details": {
|
|
||||||
"maxLength": 300,
|
|
||||||
"actualLength": 350
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"timestamp": "2025-01-25T10:30:00Z",
|
|
||||||
"requestId": "uuid-string"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🔧 **數據模型規格**
|
|
||||||
|
|
||||||
### **VocabularyAnalysis 模型**
|
|
||||||
```typescript
|
|
||||||
interface VocabularyAnalysis {
|
|
||||||
word: string // 詞彙本身
|
|
||||||
translation: string // 中文翻譯
|
|
||||||
definition: string // 英文定義
|
|
||||||
partOfSpeech: string // 詞性
|
|
||||||
pronunciation: string // 發音 (IPA)
|
|
||||||
difficultyLevel: CEFRLevel // CEFR等級
|
|
||||||
frequency: FrequencyLevel // 使用頻率
|
|
||||||
synonyms: string[] // 同義詞
|
|
||||||
example?: string // 例句
|
|
||||||
exampleTranslation?: string // 例句翻譯
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### **GrammarCorrection 模型**
|
|
||||||
```typescript
|
|
||||||
interface GrammarCorrection {
|
|
||||||
hasErrors: boolean
|
|
||||||
correctedText: string
|
|
||||||
corrections: GrammarError[]
|
|
||||||
}
|
|
||||||
|
|
||||||
interface GrammarError {
|
|
||||||
position: { start: number; end: number }
|
|
||||||
error: string
|
|
||||||
correction: string
|
|
||||||
type: string
|
|
||||||
explanation: string
|
|
||||||
severity: "low" | "medium" | "high"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### **IdiomDto 模型**
|
|
||||||
```typescript
|
|
||||||
interface IdiomDto {
|
|
||||||
idiom: string // 慣用語本身
|
|
||||||
translation: string // 中文翻譯
|
|
||||||
definition: string // 英文定義
|
|
||||||
pronunciation: string // 發音 (IPA)
|
|
||||||
difficultyLevel: CEFRLevel // CEFR等級
|
|
||||||
frequency: FrequencyLevel // 使用頻率
|
|
||||||
synonyms: string[] // 同義詞或相似表達
|
|
||||||
example?: string // 例句
|
|
||||||
exampleTranslation?: string // 例句翻譯
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
|
|
||||||
### **AnalysisMetadata 模型**
|
|
||||||
```typescript
|
|
||||||
interface AnalysisMetadata {
|
|
||||||
analysisModel: string // AI模型名稱
|
|
||||||
analysisVersion: string // 分析版本
|
|
||||||
processingDate: string // 處理時間 (ISO 8601)
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### **ApiErrorResponse 模型**
|
|
||||||
```typescript
|
|
||||||
interface ApiErrorResponse {
|
|
||||||
success: boolean // 固定為 false
|
|
||||||
error: ApiError // 錯誤詳情
|
|
||||||
timestamp: string // 錯誤時間 (ISO 8601)
|
|
||||||
requestId: string // 請求ID
|
|
||||||
}
|
|
||||||
|
|
||||||
interface ApiError {
|
|
||||||
code: string // 錯誤代碼
|
|
||||||
message: string // 錯誤訊息
|
|
||||||
details?: object // 錯誤詳情
|
|
||||||
suggestions: string[] // 建議解決方案
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### **枚舉定義**
|
|
||||||
```typescript
|
|
||||||
type CEFRLevel = "A1" | "A2" | "B1" | "B2" | "C1" | "C2"
|
|
||||||
type FrequencyLevel = "very_high" | "high" | "medium" | "low" | "very_low"
|
|
||||||
type AnalysisMode = "basic" | "full"
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🤖 **AI Prompt設計規格**
|
|
||||||
|
|
||||||
### **Prompt架構設計**
|
|
||||||
|
|
||||||
#### **核心Prompt模板**
|
|
||||||
```text
|
|
||||||
You are an English learning assistant. Analyze this sentence for a learner and return ONLY a valid JSON response.
|
|
||||||
|
|
||||||
**Input Sentence**: "{inputText}"
|
|
||||||
|
|
||||||
**Required JSON Structure:**
|
|
||||||
{
|
|
||||||
"sentenceTranslation": "Traditional Chinese translation of the entire sentence",
|
|
||||||
"hasGrammarErrors": true/false,
|
|
||||||
"grammarCorrections": [
|
|
||||||
{
|
|
||||||
"original": "incorrect text",
|
|
||||||
"corrected": "correct text",
|
|
||||||
"type": "error type (tense/subject-verb/preposition/word-order)",
|
|
||||||
"explanation": "brief explanation in Traditional Chinese"
|
|
||||||
}
|
|
||||||
],
|
|
||||||
"vocabularyAnalysis": {
|
|
||||||
"word1": {
|
|
||||||
"word": "the word",
|
|
||||||
"translation": "Traditional Chinese translation",
|
|
||||||
"definition": "English definition",
|
|
||||||
"partOfSpeech": "noun/verb/adjective/etc",
|
|
||||||
"pronunciation": "/phonetic/",
|
|
||||||
"difficultyLevel": "A1/A2/B1/B2/C1/C2",
|
|
||||||
"frequency": "high/medium/low",
|
|
||||||
"synonyms": ["synonym1", "synonym2"],
|
|
||||||
"example": "example sentence",
|
|
||||||
"exampleTranslation": "Traditional Chinese example translation"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"idioms": [
|
|
||||||
{
|
|
||||||
"idiom": "idiomatic expression",
|
|
||||||
"translation": "Traditional Chinese meaning",
|
|
||||||
"definition": "English explanation",
|
|
||||||
"pronunciation": "/phonetic notation/",
|
|
||||||
"difficultyLevel": "A1/A2/B1/B2/C1/C2",
|
|
||||||
"frequency": "high/medium/low",
|
|
||||||
"synonyms": ["synonym1", "synonym2"],
|
|
||||||
"example": "usage example",
|
|
||||||
"exampleTranslation": "Traditional Chinese example"
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### **Prompt指導原則**
|
|
||||||
|
|
||||||
#### **分析指導方針**
|
|
||||||
```yaml
|
|
||||||
語法檢查:
|
|
||||||
- 檢測範圍: 時態錯誤、主謂一致、介詞使用、詞序問題
|
|
||||||
- 修正原則: 提供自然且正確的英語表達
|
|
||||||
- 解釋語言: 使用繁體中文（台灣標準）
|
|
||||||
|
|
||||||
詞彙分析:
|
|
||||||
- 包含範圍: 所有有意義的詞彙（排除冠詞 a, an, the）
|
|
||||||
- CEFR標準: 準確分配A1-C2等級
|
|
||||||
- 發音標記: 使用國際音標(IPA)
|
|
||||||
- 例句品質: 提供實用且常見的例句
|
|
||||||
|
|
||||||
慣用語識別:
|
|
||||||
- 識別目標: 慣用語、片語動詞、固定搭配
|
|
||||||
- 分類原則: 獨立於vocabularyAnalysis處理
|
|
||||||
- 解釋詳度: 提供文化背景和使用場景
|
|
||||||
|
|
||||||
翻譯品質:
|
|
||||||
- 語言標準: 繁體中文（台灣用法）
|
|
||||||
- 自然程度: 符合中文表達習慣
|
|
||||||
- 準確性: 保持原文語義完整
|
|
||||||
```
|
|
||||||
|
|
||||||
### **Prompt優化策略**
|
|
||||||
|
|
||||||
#### **結構化輸出控制**
|
|
||||||
```text
|
|
||||||
**IMPORTANT**: Return ONLY the JSON object, no additional text or explanation.
|
|
||||||
|
|
||||||
**Quality Assurance:**
|
|
||||||
1. Ensure all JSON keys are exactly as specified
|
|
||||||
2. Use Traditional Chinese for all translations
|
|
||||||
3. Assign accurate CEFR levels based on standard guidelines
|
|
||||||
4. Separate idioms from regular vocabulary
|
|
||||||
5. Provide practical examples that learners can use
|
|
||||||
```
|
|
||||||
|
|
||||||
#### **錯誤處理Prompt**
|
|
||||||
```text
|
|
||||||
**Error Handling Guidelines:**
|
|
||||||
- If unable to analyze: Return basic structure with explanatory messages
|
|
||||||
- If safety filtered: Provide alternative analysis approach
|
|
||||||
- If ambiguous input: Make reasonable assumptions and proceed
|
|
||||||
- Always return valid JSON regardless of input complexity
|
|
||||||
```
|
|
||||||
|
|
||||||
### **Prompt版本管理**
|
|
||||||
|
|
||||||
#### **版本演進記錄**
|
|
||||||
```yaml
|
|
||||||
v1.0 (2025-01-20):
|
|
||||||
- 基礎prompt結構
|
|
||||||
- 簡單詞彙分析
|
|
||||||
|
|
||||||
v1.5 (2025-01-22):
|
|
||||||
- 新增慣用語識別
|
|
||||||
- 優化語法檢查
|
|
||||||
|
|
||||||
v2.0 (2025-01-25):
|
|
||||||
- 結構化JSON輸出
|
|
||||||
- 完整資料模型支援
|
|
||||||
- 繁體中文本地化
|
|
||||||
- 錯誤處理機制
|
|
||||||
```
|
|
||||||
|
|
||||||
#### **A/B測試配置**
|
|
||||||
```csharp
|
|
||||||
// Prompt變體測試
|
|
||||||
public enum PromptVariant
|
|
||||||
{
|
|
||||||
Standard, // 標準prompt
|
|
||||||
DetailedExamples, // 強調例句品質
|
|
||||||
StrictGrammar, // 加強語法檢查
|
|
||||||
CulturalContext // 增加文化背景
|
|
||||||
}
|
|
||||||
|
|
||||||
// 動態Prompt選擇
|
|
||||||
private string GetPromptByVariant(PromptVariant variant, string inputText)
|
|
||||||
{
|
|
||||||
return variant switch
|
|
||||||
{
|
|
||||||
PromptVariant.Standard => BuildStandardPrompt(inputText),
|
|
||||||
PromptVariant.DetailedExamples => BuildDetailedPrompt(inputText),
|
|
||||||
_ => BuildStandardPrompt(inputText)
|
|
||||||
};
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🔒 **認證與授權**
|
|
||||||
|
|
||||||
### **API認證**
|
|
||||||
```yaml
|
|
||||||
認證方式: Bearer Token (JWT)
|
|
||||||
Token位置: Authorization Header
|
|
||||||
Token格式: "Bearer {jwt_token}"
|
|
||||||
過期時間: 24小時
|
|
||||||
刷新機制: Refresh Token
|
|
||||||
```
|
|
||||||
|
|
||||||
### **權限等級**
|
|
||||||
```yaml
|
|
||||||
Guest用戶:
|
|
||||||
- 每日5次免費分析
|
|
||||||
- 基礎分析功能
|
|
||||||
- 無歷史記錄
|
|
||||||
|
|
||||||
Premium用戶:
|
|
||||||
- 無限制分析
|
|
||||||
- 完整分析功能
|
|
||||||
- 歷史記錄保存
|
|
||||||
- 批次分析
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## ⚡ **性能要求**
|
|
||||||
|
|
||||||
### **響應時間目標**
|
|
||||||
```yaml
|
|
||||||
基礎分析: < 2秒
|
|
||||||
完整分析: < 5秒
|
|
||||||
批次分析: < 10秒 (10句)
|
|
||||||
錯誤回應: < 500ms
|
|
||||||
```
|
|
||||||
|
|
||||||
### **吞吐量要求**
|
|
||||||
```yaml
|
|
||||||
並發請求: 100 req/sec
|
|
||||||
每日請求: 100,000 requests
|
|
||||||
峰值處理: 200 req/sec
|
|
||||||
```
|
|
||||||
|
|
||||||
### **資源限制**
|
|
||||||
```yaml
|
|
||||||
輸入文本: 最大300字符
|
|
||||||
輸出大小: 最大5MB
|
|
||||||
內存使用: 最大500MB per request
|
|
||||||
超時設定: 30秒
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📊 **監控與日誌**
|
|
||||||
|
|
||||||
### **關鍵指標**
|
|
||||||
```yaml
|
|
||||||
性能指標:
|
|
||||||
- 請求響應時間
|
|
||||||
- API成功率
|
|
||||||
- AI服務響應時間
|
|
||||||
- 資料庫查詢時間
|
|
||||||
|
|
||||||
業務指標:
|
|
||||||
- 每日分析次數
|
|
||||||
- 用戶活躍度
|
|
||||||
- 錯誤類型分布
|
|
||||||
- 詞彙覆蓋率
|
|
||||||
```
|
|
||||||
|
|
||||||
### **日誌格式**
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"timestamp": "2025-01-25T10:30:00Z",
|
|
||||||
"level": "INFO",
|
|
||||||
"requestId": "uuid-string",
|
|
||||||
"userId": "user-id",
|
|
||||||
"endpoint": "/api/ai/analyze-sentence",
|
|
||||||
"method": "POST",
|
|
||||||
"statusCode": 200,
|
|
||||||
"responseTime": 2340,
|
|
||||||
"inputLength": 89,
|
|
||||||
"analysisMode": "full",
|
|
||||||
"aiModel": "gemini-1.5-flash",
|
|
||||||
"processingSteps": {
|
|
||||||
"grammarCheck": 450,
|
|
||||||
"vocabularyAnalysis": 1200,
|
|
||||||
"translation": 690
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🔄 **錯誤處理**
|
|
||||||
|
|
||||||
### **錯誤碼定義**
|
|
||||||
```yaml
|
|
||||||
4000: INVALID_INPUT - 輸入格式錯誤
|
|
||||||
4001: TEXT_TOO_LONG - 文本超過長度限制
|
|
||||||
4002: INVALID_CEFR_LEVEL - 無效的CEFR等級
|
|
||||||
4003: UNSUPPORTED_LANGUAGE - 不支援的語言
|
|
||||||
|
|
||||||
4010: AUTHENTICATION_FAILED - 認證失敗
|
|
||||||
4011: TOKEN_EXPIRED - Token已過期
|
|
||||||
4012: INSUFFICIENT_PERMISSIONS - 權限不足
|
|
||||||
|
|
||||||
4290: RATE_LIMIT_EXCEEDED - 超過使用限制
|
|
||||||
4291: QUOTA_EXCEEDED - 超過配額
|
|
||||||
|
|
||||||
5000: AI_SERVICE_ERROR - AI服務錯誤
|
|
||||||
5001: DATABASE_ERROR - 資料庫錯誤
|
|
||||||
5002: EXTERNAL_API_ERROR - 外部API錯誤
|
|
||||||
5003: PROCESSING_TIMEOUT - 處理超時
|
|
||||||
```
|
|
||||||
|
|
||||||
### **錯誤回應範例**
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": false,
|
|
||||||
"error": {
|
|
||||||
"code": "RATE_LIMIT_EXCEEDED",
|
|
||||||
"message": "已超過每日使用限制",
|
|
||||||
"details": {
|
|
||||||
"limit": 5,
|
|
||||||
"used": 5,
|
|
||||||
"resetTime": "2025-01-26T00:00:00Z"
|
|
||||||
},
|
|
||||||
"suggestions": [
|
|
||||||
"升級到Premium帳戶以獲得無限使用",
|
|
||||||
"明天重新嘗試"
|
|
||||||
]
|
|
||||||
},
|
|
||||||
"timestamp": "2025-01-25T10:30:00Z",
|
|
||||||
"requestId": "uuid-string"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🧪 **測試規格**
|
|
||||||
|
|
||||||
### **API測試案例**
|
|
||||||
|
|
||||||
#### **TC-001: 正常分析流程**
|
|
||||||
```yaml
|
|
||||||
測試目的: 驗證完整分析功能
|
|
||||||
輸入數據:
|
|
||||||
inputText: "She just join the team, so let's cut her some slack until she get used to the workflow."
|
|
||||||
analysisMode: "full"
|
|
||||||
|
|
||||||
預期結果:
|
|
||||||
statusCode: 200
|
|
||||||
grammarCorrection.hasErrors: true
|
|
||||||
grammarCorrection.corrections.length: 2
|
|
||||||
vocabularyAnalysis keys: 16 (不含慣用語)
|
|
||||||
idioms.length: 1
|
|
||||||
```
|
|
||||||
|
|
||||||
#### **TC-002: 輸入驗證測試**
|
|
||||||
```yaml
|
|
||||||
測試目的: 驗證輸入驗證機制
|
|
||||||
測試案例:
|
|
||||||
- 空字串輸入
|
|
||||||
- 超長文本 (>300字符)
|
|
||||||
- 無效CEFR等級
|
|
||||||
- 純數字輸入
|
|
||||||
- 特殊字符輸入
|
|
||||||
|
|
||||||
預期結果: 400錯誤與相應錯誤訊息
|
|
||||||
```
|
|
||||||
|
|
||||||
#### **TC-003: 認證測試**
|
|
||||||
```yaml
|
|
||||||
測試目的: 驗證API認證機制
|
|
||||||
測試案例:
|
|
||||||
- 無Token訪問
|
|
||||||
- 無效Token
|
|
||||||
- 過期Token
|
|
||||||
- 權限不足
|
|
||||||
|
|
||||||
預期結果: 401/403錯誤
|
|
||||||
```
|
|
||||||
|
|
||||||
### **性能測試**
|
|
||||||
```yaml
|
|
||||||
負載測試:
|
|
||||||
- 100 concurrent users
|
|
||||||
- 1000 requests in 10 minutes
|
|
||||||
- 目標: 95% requests < 5 seconds
|
|
||||||
|
|
||||||
壓力測試:
|
|
||||||
- 200 concurrent users
|
|
||||||
- 持續20分鐘
|
|
||||||
- 目標: API仍然響應
|
|
||||||
|
|
||||||
容量測試:
|
|
||||||
- 模擬10,000 daily users
|
|
||||||
- 24小時持續測試
|
|
||||||
- 目標: 系統穩定運行
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🚀 **部署規格**
|
|
||||||
|
|
||||||
### **環境配置**
|
|
||||||
```yaml
|
|
||||||
Development:
|
|
||||||
database: PostgreSQL 15
|
|
||||||
cache: Redis 7
|
|
||||||
ai_service: Google Gemini API
|
|
||||||
replicas: 1
|
|
||||||
resources:
|
|
||||||
cpu: 0.5 cores
|
|
||||||
memory: 1GB
|
|
||||||
|
|
||||||
Staging:
|
|
||||||
database: PostgreSQL 15 (replica)
|
|
||||||
cache: Redis 7 (cluster)
|
|
||||||
ai_service: Google Gemini API
|
|
||||||
replicas: 2
|
|
||||||
resources:
|
|
||||||
cpu: 1 core
|
|
||||||
memory: 2GB
|
|
||||||
|
|
||||||
Production:
|
|
||||||
database: PostgreSQL 15 (HA cluster)
|
|
||||||
cache: Redis 7 (cluster)
|
|
||||||
ai_service: Google Gemini API
|
|
||||||
replicas: 5
|
|
||||||
resources:
|
|
||||||
cpu: 2 cores
|
|
||||||
memory: 4GB
|
|
||||||
```
|
|
||||||
|
|
||||||
### **Docker配置**
|
|
||||||
```dockerfile
|
|
||||||
FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base
|
|
||||||
WORKDIR /app
|
|
||||||
EXPOSE 80
|
|
||||||
EXPOSE 443
|
|
||||||
|
|
||||||
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
|
|
||||||
WORKDIR /src
|
|
||||||
COPY ["DramaLing.AI.Api/DramaLing.AI.Api.csproj", "DramaLing.AI.Api/"]
|
|
||||||
RUN dotnet restore "DramaLing.AI.Api/DramaLing.AI.Api.csproj"
|
|
||||||
COPY . .
|
|
||||||
WORKDIR "/src/DramaLing.AI.Api"
|
|
||||||
RUN dotnet build "DramaLing.AI.Api.csproj" -c Release -o /app/build
|
|
||||||
|
|
||||||
FROM build AS publish
|
|
||||||
RUN dotnet publish "DramaLing.AI.Api.csproj" -c Release -o /app/publish
|
|
||||||
|
|
||||||
FROM base AS final
|
|
||||||
WORKDIR /app
|
|
||||||
COPY --from=publish /app/publish .
|
|
||||||
ENTRYPOINT ["dotnet", "DramaLing.AI.Api.dll"]
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📈 **擴展計劃**
|
|
||||||
|
|
||||||
### **短期擴展 (1-3個月)**
|
|
||||||
```yaml
|
|
||||||
功能擴展:
|
|
||||||
- 批次分析API
|
|
||||||
- 文本難度評估
|
|
||||||
- 個人化詞彙推薦
|
|
||||||
- 學習進度追蹤
|
|
||||||
|
|
||||||
技術改進:
|
|
||||||
- GraphQL支援
|
|
||||||
- WebSocket即時分析
|
|
||||||
- 分析結果緩存優化
|
|
||||||
- AI模型版本管理
|
|
||||||
```
|
|
||||||
|
|
||||||
### **中期擴展 (3-6個月)**
|
|
||||||
```yaml
|
|
||||||
多語言支援:
|
|
||||||
- 法語分析
|
|
||||||
- 德語分析
|
|
||||||
- 西班牙語分析
|
|
||||||
|
|
||||||
進階功能:
|
|
||||||
- 語音分析集成
|
|
||||||
- 圖片文字識別
|
|
||||||
- 視頻字幕分析
|
|
||||||
- 個人化AI調優
|
|
||||||
```
|
|
||||||
|
|
||||||
### **長期擴展 (6-12個月)**
|
|
||||||
```yaml
|
|
||||||
AI升級:
|
|
||||||
- 自訂AI模型訓練
|
|
||||||
- 多模態學習分析
|
|
||||||
- 即時語言學習建議
|
|
||||||
- 預測性學習路徑
|
|
||||||
|
|
||||||
企業功能:
|
|
||||||
- 團隊管理API
|
|
||||||
- 批量用戶管理
|
|
||||||
- 詳細分析報告
|
|
||||||
- 自訂詞彙庫
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🔐 **安全規格**
|
|
||||||
|
|
||||||
### **數據安全**
|
|
||||||
```yaml
|
|
||||||
傳輸安全:
|
|
||||||
- TLS 1.3加密
|
|
||||||
- API密鑰輪換
|
|
||||||
- 請求簽名驗證
|
|
||||||
|
|
||||||
數據保護:
|
|
||||||
- 個人數據加密存儲
|
|
||||||
- 敏感信息遮罩
|
|
||||||
- 數據保留政策
|
|
||||||
- GDPR合規
|
|
||||||
```
|
|
||||||
|
|
||||||
### **API安全**
|
|
||||||
```yaml
|
|
||||||
防護措施:
|
|
||||||
- 速率限制
|
|
||||||
- IP白名單
|
|
||||||
- 異常檢測
|
|
||||||
- 自動封鎖機制
|
|
||||||
|
|
||||||
審計日誌:
|
|
||||||
- 完整請求記錄
|
|
||||||
- 敏感操作追蹤
|
|
||||||
- 異常行為警報
|
|
||||||
- 合規性報告
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📋 **API文檔規範**
|
|
||||||
|
|
||||||
### **OpenAPI規格**
|
|
||||||
- 使用OpenAPI 3.0規範
|
|
||||||
- 提供互動式API文檔
|
|
||||||
- 自動生成客戶端SDK
|
|
||||||
- 版本化API文檔
|
|
||||||
|
|
||||||
### **文檔內容**
|
|
||||||
- 詳細的端點說明
|
|
||||||
- 請求/回應範例
|
|
||||||
- 錯誤碼說明
|
|
||||||
- 最佳實踐指南
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**文件版本**: v1.1 (更新AI模型和模型定義)
|
|
||||||
**API版本**: v1
|
|
||||||
**最後更新**: 2025-01-25
|
|
||||||
**下次審查**: 2025-02-25
|
|
||||||
|
|
||||||
**更新記錄**:
|
|
||||||
- v1.1: 修正AI模型名稱為Gemini 1.5 Flash
|
|
||||||
- v1.1: 移除VocabularyAnalysis中tags欄位
|
|
||||||
- v1.1: 新增IdiomDto和ApiErrorResponse模型定義
|
|
||||||
- v1.1: 移除userLevel參數（簡化API）
|
|
||||||
- v1.1: 統一回應格式範例
|
|
||||||
- v1.1: 新增完整的AI Prompt設計規格和版本管理
|
|
||||||
- v1.1: 同步更新後端DTO模型實現（移除Tags、IsIdiom、UserLevel欄位）
|
|
||||||
- v1.1: 移除statistics計算邏輯（前端自行處理統計）
|
|
||||||
741
AI生成網頁前端需求規格.md
741
AI生成網頁前端需求規格.md
|
|
@ -1,741 +0,0 @@
|
||||||
# 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": "英文句子",
|
|
||||||
"analysisMode": "full"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**回應處理需求**:
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": true,
|
|
||||||
"data": {
|
|
||||||
"vocabularyAnalysis": "詞彙分析字典對象",
|
|
||||||
"sentenceMeaning": "句子翻譯字串",
|
|
||||||
"grammarCorrection": "語法修正資料對象",
|
|
||||||
"idioms": "慣用語陣列",
|
|
||||||
"statistics": "統計資料對象",
|
|
||||||
"metadata": "分析元資料對象"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### **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等級
|
|
||||||
frequency: string // 必需：使用頻率
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
#### **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.1 (配合後端API規格更新)
|
|
||||||
**產品負責人**: DramaLing產品團隊
|
|
||||||
**最後更新**: 2025-01-25
|
|
||||||
**下次審查**: 2025-02-25
|
|
||||||
|
|
||||||
**更新記錄**:
|
|
||||||
- v1.1: 移除API請求中的userLevel參數要求
|
|
||||||
- v1.1: 更新API回應格式為實際實現的格式
|
|
||||||
- v1.1: 修正資料模型，移除isIdiom欄位，新增frequency欄位
|
|
||||||
- v1.1: 保留前端個人化分類邏輯，改為從localStorage獲取用戶等級
|
|
||||||
|
|
@ -1,711 +0,0 @@
|
||||||
# DramaLing AI句子分析功能前後端串接實施計劃
|
|
||||||
|
|
||||||
## 📋 **文件資訊**
|
|
||||||
|
|
||||||
- **文件名稱**: DramaLing AI句子分析功能前後端串接實施計劃
|
|
||||||
- **版本**: v1.0
|
|
||||||
- **建立日期**: 2025-01-25
|
|
||||||
- **最後更新**: 2025-01-25
|
|
||||||
- **負責團隊**: DramaLing技術團隊
|
|
||||||
- **專案階段**: 後端完成，準備前後端整合
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🎯 **計劃概述**
|
|
||||||
|
|
||||||
### **目標**
|
|
||||||
完成DramaLing AI句子分析功能的前後端串接，實現完整的智能英語學習體驗。
|
|
||||||
|
|
||||||
### **現狀分析**
|
|
||||||
- ✅ **後端API**: 已完成開發並運行在 localhost:5008
|
|
||||||
- ✅ **前端架構**: Next.js 15 + TypeScript + Tailwind CSS
|
|
||||||
- ✅ **AI整合**: Google Gemini 1.5 Flash API 已整合
|
|
||||||
- ⏳ **串接狀態**: 需要調整前端API調用邏輯以對接新後端
|
|
||||||
|
|
||||||
### **串接範圍**
|
|
||||||
1. AI句子分析核心功能
|
|
||||||
2. 詞彙分析與CEFR分級
|
|
||||||
3. 語法修正功能
|
|
||||||
4. 慣用語檢測
|
|
||||||
5. 個人化學習統計
|
|
||||||
6. 錯誤處理與用戶體驗
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📊 **當前架構對比分析**
|
|
||||||
|
|
||||||
### **後端API架構 (.NET 8)**
|
|
||||||
```yaml
|
|
||||||
核心端點:
|
|
||||||
- POST /api/ai/analyze-sentence # 主要分析API (backend/DramaLing.Api/Controllers/AIController.cs)
|
|
||||||
- GET /api/ai/health # 健康檢查 (backend/DramaLing.Api/Controllers/AIController.cs)
|
|
||||||
- POST /api/flashcards # 詞卡管理 (backend/DramaLing.Api/Controllers/FlashcardsController.cs)
|
|
||||||
- POST /api/auth/login # 用戶認證 (backend/DramaLing.Api/Controllers/AuthController.cs)
|
|
||||||
|
|
||||||
技術棧:
|
|
||||||
- .NET 8 Web API
|
|
||||||
- Entity Framework Core
|
|
||||||
- SQLite (開發) / PostgreSQL (生產)
|
|
||||||
- Google Gemini 1.5 Flash AI
|
|
||||||
- JWT認證機制
|
|
||||||
```
|
|
||||||
|
|
||||||
### **前端架構 (Next.js 15)**
|
|
||||||
```yaml
|
|
||||||
核心功能:
|
|
||||||
- 句子輸入與分析 (/Users/jettcheng1018/code/dramaling-vocab-learning/frontend/app/generate/page.tsx)
|
|
||||||
- 詞彙標記與統計 (/Users/jettcheng1018/code/dramaling-vocab-learning/frontend/components/ClickableTextV2.tsx)
|
|
||||||
- 語法修正面板 (/Users/jettcheng1018/code/dramaling-vocab-learning/frontend/components/GrammarCorrectionPanel.tsx)
|
|
||||||
- 詞彙詳情彈窗 (VocabPopup - 位於ClickableTextV2.tsx內)
|
|
||||||
- 學習模式整合 (/Users/jettcheng1018/code/dramaling-vocab-learning/frontend/app/learn/page.tsx)
|
|
||||||
|
|
||||||
技術棧:
|
|
||||||
- Next.js 15.5.3 + React 19
|
|
||||||
- TypeScript + Tailwind CSS
|
|
||||||
- localStorage (用戶設定)
|
|
||||||
- Fetch API (HTTP請求)
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🔄 **API整合對比**
|
|
||||||
|
|
||||||
### **現有前端API調用**
|
|
||||||
```typescript
|
|
||||||
// 檔案位置: /Users/jettcheng1018/code/dramaling-vocab-learning/frontend/app/generate/page.tsx
|
|
||||||
// 函數: handleAnalyzeSentence (約在第185-220行)
|
|
||||||
const response = await fetch('http://localhost:5008/api/ai/analyze-sentence', {
|
|
||||||
method: 'POST',
|
|
||||||
headers: { 'Content-Type': 'application/json' },
|
|
||||||
body: JSON.stringify({
|
|
||||||
inputText: textInput,
|
|
||||||
userLevel: userLevel, // ⚠️ 後端不需要此欄位
|
|
||||||
analysisMode: 'full',
|
|
||||||
options: {
|
|
||||||
includeGrammarCheck: true,
|
|
||||||
includeVocabularyAnalysis: true,
|
|
||||||
includeTranslation: true,
|
|
||||||
includeIdiomDetection: true,
|
|
||||||
includeExamples: true
|
|
||||||
}
|
|
||||||
})
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
### **後端API規格**
|
|
||||||
```json
|
|
||||||
// 檔案參考: backend/DramaLing.Api/Controllers/AIController.cs
|
|
||||||
// 端點: POST /api/ai/analyze-sentence
|
|
||||||
// 請求格式
|
|
||||||
{
|
|
||||||
"inputText": "英文句子",
|
|
||||||
"analysisMode": "full",
|
|
||||||
"options": {
|
|
||||||
"includeGrammarCheck": true,
|
|
||||||
"includeVocabularyAnalysis": true,
|
|
||||||
"includeTranslation": true,
|
|
||||||
"includeIdiomDetection": true,
|
|
||||||
"includeExamples": true
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
// 回應格式
|
|
||||||
{
|
|
||||||
"success": true,
|
|
||||||
"processingTime": 2.34,
|
|
||||||
"data": {
|
|
||||||
"analysisId": "uuid-string",
|
|
||||||
"originalText": "原始句子",
|
|
||||||
"sentenceMeaning": "中文翻譯",
|
|
||||||
"grammarCorrection": {
|
|
||||||
"hasErrors": true,
|
|
||||||
"correctedText": "修正後文本",
|
|
||||||
"corrections": [...]
|
|
||||||
},
|
|
||||||
"vocabularyAnalysis": {
|
|
||||||
"word1": {
|
|
||||||
"word": "詞彙",
|
|
||||||
"translation": "翻譯",
|
|
||||||
"definition": "定義",
|
|
||||||
"partOfSpeech": "詞性",
|
|
||||||
"pronunciation": "發音",
|
|
||||||
"difficultyLevel": "A1-C2",
|
|
||||||
"frequency": "high/medium/low",
|
|
||||||
"synonyms": ["同義詞"],
|
|
||||||
"example": "例句",
|
|
||||||
"exampleTranslation": "例句翻譯"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"idioms": [...],
|
|
||||||
"metadata": {...}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🛠️ **實施計劃**
|
|
||||||
|
|
||||||
### **階段一：API適配與調整 (1-2天)**
|
|
||||||
|
|
||||||
#### **1.1 前端API調用更新**
|
|
||||||
**目標**: 移除後端不需要的userLevel參數，確保請求格式正確
|
|
||||||
|
|
||||||
**檔案**: `/Users/jettcheng1018/code/dramaling-vocab-learning/frontend/app/generate/page.tsx`
|
|
||||||
**函數**: `handleAnalyzeSentence` (約在第185-220行)
|
|
||||||
```typescript
|
|
||||||
// 修改前
|
|
||||||
body: JSON.stringify({
|
|
||||||
inputText: textInput,
|
|
||||||
userLevel: userLevel, // 移除此行
|
|
||||||
analysisMode: 'full',
|
|
||||||
options: { ... }
|
|
||||||
})
|
|
||||||
|
|
||||||
// 修改後
|
|
||||||
body: JSON.stringify({
|
|
||||||
inputText: textInput,
|
|
||||||
analysisMode: 'full',
|
|
||||||
options: {
|
|
||||||
includeGrammarCheck: true,
|
|
||||||
includeVocabularyAnalysis: true,
|
|
||||||
includeTranslation: true,
|
|
||||||
includeIdiomDetection: true,
|
|
||||||
includeExamples: true
|
|
||||||
}
|
|
||||||
})
|
|
||||||
```
|
|
||||||
|
|
||||||
#### **1.2 回應數據結構適配**
|
|
||||||
**目標**: 更新前端以處理新的API回應格式
|
|
||||||
|
|
||||||
**檔案**: `/Users/jettcheng1018/code/dramaling-vocab-learning/frontend/app/generate/page.tsx`
|
|
||||||
**函數**: `handleAnalysisResult` (需新增)
|
|
||||||
```typescript
|
|
||||||
// 修改回應處理邏輯
|
|
||||||
const handleAnalysisResult = (result) => {
|
|
||||||
// 後端回應結構: result.data.vocabularyAnalysis
|
|
||||||
// 前端期望結構: result.vocabularyAnalysis
|
|
||||||
|
|
||||||
const analysisData = {
|
|
||||||
originalText: result.data.originalText,
|
|
||||||
sentenceMeaning: result.data.sentenceMeaning,
|
|
||||||
grammarCorrection: result.data.grammarCorrection,
|
|
||||||
vocabularyAnalysis: result.data.vocabularyAnalysis,
|
|
||||||
idioms: result.data.idioms,
|
|
||||||
processingTime: result.processingTime
|
|
||||||
};
|
|
||||||
|
|
||||||
setSentenceAnalysis(analysisData);
|
|
||||||
};
|
|
||||||
```
|
|
||||||
|
|
||||||
### **階段二：詞彙分析整合 (2-3天)**
|
|
||||||
|
|
||||||
#### **2.1 詞彙數據格式統一**
|
|
||||||
**目標**: 確保前端詞彙分析邏輯與後端回應格式匹配
|
|
||||||
|
|
||||||
**檔案**: `/Users/jettcheng1018/code/dramaling-vocab-learning/frontend/components/ClickableTextV2.tsx`
|
|
||||||
**函數**: `findWordAnalysis`, `getWordProperty` (約在第50-80行)
|
|
||||||
```typescript
|
|
||||||
// 更新詞彙分析資料存取邏輯
|
|
||||||
const findWordAnalysis = useCallback((word: string) => {
|
|
||||||
if (!sentenceAnalysis?.vocabularyAnalysis) return null;
|
|
||||||
|
|
||||||
// 後端格式: vocabularyAnalysis[word]
|
|
||||||
return sentenceAnalysis.vocabularyAnalysis[word] || null;
|
|
||||||
}, [sentenceAnalysis]);
|
|
||||||
|
|
||||||
// 更新CEFR難度取得邏輯
|
|
||||||
const getWordProperty = useCallback((word: string, property: string) => {
|
|
||||||
const analysis = findWordAnalysis(word);
|
|
||||||
return analysis?.[property] || '';
|
|
||||||
}, [findWordAnalysis]);
|
|
||||||
```
|
|
||||||
|
|
||||||
#### **2.2 統計計算邏輯優化**
|
|
||||||
**目標**: 基於新的API回應格式重新計算詞彙統計
|
|
||||||
|
|
||||||
**檔案**: `/Users/jettcheng1018/code/dramaling-vocab-learning/frontend/app/generate/page.tsx`
|
|
||||||
**函數**: `vocabularyStats` useMemo hook (約在第250-280行)
|
|
||||||
```typescript
|
|
||||||
const vocabularyStats = useMemo(() => {
|
|
||||||
if (!sentenceAnalysis?.vocabularyAnalysis) {
|
|
||||||
return { simpleCount: 0, moderateCount: 0, difficultCount: 0, idiomCount: 0 };
|
|
||||||
}
|
|
||||||
|
|
||||||
const userIndex = CEFR_LEVELS.indexOf(userLevel);
|
|
||||||
let simple = 0, moderate = 0, difficult = 0;
|
|
||||||
|
|
||||||
// 遍歷vocabularyAnalysis物件
|
|
||||||
Object.values(sentenceAnalysis.vocabularyAnalysis).forEach(word => {
|
|
||||||
const wordIndex = CEFR_LEVELS.indexOf(word.difficultyLevel);
|
|
||||||
if (userIndex > wordIndex) simple++;
|
|
||||||
else if (userIndex === wordIndex) moderate++;
|
|
||||||
else difficult++;
|
|
||||||
});
|
|
||||||
|
|
||||||
return {
|
|
||||||
simpleCount: simple,
|
|
||||||
moderateCount: moderate,
|
|
||||||
difficultCount: difficult,
|
|
||||||
idiomCount: sentenceAnalysis.idioms?.length || 0
|
|
||||||
};
|
|
||||||
}, [sentenceAnalysis, userLevel]);
|
|
||||||
```
|
|
||||||
|
|
||||||
### **階段三：語法修正整合 (1-2天)**
|
|
||||||
|
|
||||||
#### **3.1 語法修正數據適配**
|
|
||||||
**目標**: 更新語法修正面板以處理新的錯誤格式
|
|
||||||
|
|
||||||
**檔案**: `/Users/jettcheng1018/code/dramaling-vocab-learning/frontend/components/GrammarCorrectionPanel.tsx`
|
|
||||||
**介面定義**: `GrammarError` interface (需新增)
|
|
||||||
**函數**: `renderCorrections` (需修改)
|
|
||||||
```typescript
|
|
||||||
// 更新錯誤數據結構處理
|
|
||||||
interface GrammarError {
|
|
||||||
position: { start: number; end: number };
|
|
||||||
error: string;
|
|
||||||
correction: string;
|
|
||||||
type: string;
|
|
||||||
explanation: string;
|
|
||||||
severity: 'high' | 'medium' | 'low';
|
|
||||||
}
|
|
||||||
|
|
||||||
// 更新組件以使用新的錯誤格式
|
|
||||||
const renderCorrections = () => {
|
|
||||||
return grammarCorrection.corrections.map((correction, index) => (
|
|
||||||
<div key={index} className="correction-item">
|
|
||||||
<span className="error-text">{correction.error}</span>
|
|
||||||
<span className="arrow">→</span>
|
|
||||||
<span className="corrected-text">{correction.correction}</span>
|
|
||||||
<div className="explanation">{correction.explanation}</div>
|
|
||||||
</div>
|
|
||||||
));
|
|
||||||
};
|
|
||||||
```
|
|
||||||
|
|
||||||
### **階段四：慣用語功能整合 (1-2天)**
|
|
||||||
|
|
||||||
#### **4.1 慣用語顯示邏輯**
|
|
||||||
**目標**: 整合後端慣用語檢測結果
|
|
||||||
|
|
||||||
**檔案**: `/Users/jettcheng1018/code/dramaling-vocab-learning/frontend/app/generate/page.tsx`
|
|
||||||
**函數**: `renderIdioms`, `handleIdiomClick` (需新增)
|
|
||||||
```typescript
|
|
||||||
// 慣用語渲染邏輯
|
|
||||||
const renderIdioms = () => {
|
|
||||||
if (!sentenceAnalysis?.idioms || sentenceAnalysis.idioms.length === 0) {
|
|
||||||
return null;
|
|
||||||
}
|
|
||||||
|
|
||||||
return (
|
|
||||||
<div className="idioms-section">
|
|
||||||
<h3>慣用語解析</h3>
|
|
||||||
{sentenceAnalysis.idioms.map((idiom, index) => (
|
|
||||||
<div key={index} className="idiom-chip" onClick={() => handleIdiomClick(idiom)}>
|
|
||||||
{idiom.idiom}
|
|
||||||
</div>
|
|
||||||
))}
|
|
||||||
</div>
|
|
||||||
);
|
|
||||||
};
|
|
||||||
|
|
||||||
// 慣用語點擊處理
|
|
||||||
const handleIdiomClick = (idiom) => {
|
|
||||||
setSelectedVocab({
|
|
||||||
word: idiom.idiom,
|
|
||||||
translation: idiom.translation,
|
|
||||||
definition: idiom.definition,
|
|
||||||
pronunciation: idiom.pronunciation,
|
|
||||||
partOfSpeech: 'idiom',
|
|
||||||
difficultyLevel: idiom.difficultyLevel,
|
|
||||||
frequency: idiom.frequency,
|
|
||||||
synonyms: idiom.synonyms,
|
|
||||||
example: idiom.example,
|
|
||||||
exampleTranslation: idiom.exampleTranslation
|
|
||||||
});
|
|
||||||
setIsPopupVisible(true);
|
|
||||||
};
|
|
||||||
```
|
|
||||||
|
|
||||||
### **階段五：錯誤處理與用戶體驗 (1-2天)**
|
|
||||||
|
|
||||||
#### **5.1 統一錯誤處理**
|
|
||||||
**目標**: 實現友善的錯誤提示和降級體驗
|
|
||||||
|
|
||||||
**檔案**: `/Users/jettcheng1018/code/dramaling-vocab-learning/frontend/app/generate/page.tsx`
|
|
||||||
**函數**: `handleAnalysisError`, `setFallbackAnalysisView` (需新增或修改)
|
|
||||||
```typescript
|
|
||||||
const handleAnalysisError = (error) => {
|
|
||||||
console.error('Analysis error:', error);
|
|
||||||
setIsAnalyzing(false);
|
|
||||||
|
|
||||||
// 根據錯誤類型提供不同的用戶提示
|
|
||||||
if (error.message.includes('timeout')) {
|
|
||||||
setErrorMessage('分析服務繁忙，請稍後再試');
|
|
||||||
} else if (error.message.includes('network')) {
|
|
||||||
setErrorMessage('網路連接問題，請檢查網路狀態');
|
|
||||||
} else if (error.message.includes('500')) {
|
|
||||||
setErrorMessage('服務器暫時不可用，請稍後重試');
|
|
||||||
} else {
|
|
||||||
setErrorMessage('分析過程中發生錯誤，請稍後再試');
|
|
||||||
}
|
|
||||||
|
|
||||||
// 提供降級體驗：基礎翻譯
|
|
||||||
setFallbackAnalysisView(textInput);
|
|
||||||
};
|
|
||||||
|
|
||||||
// 降級體驗實現
|
|
||||||
const setFallbackAnalysisView = (text) => {
|
|
||||||
setSentenceAnalysis({
|
|
||||||
originalText: text,
|
|
||||||
sentenceMeaning: '暫時無法提供完整分析，請稍後重試',
|
|
||||||
grammarCorrection: { hasErrors: false, corrections: [] },
|
|
||||||
vocabularyAnalysis: {},
|
|
||||||
idioms: []
|
|
||||||
});
|
|
||||||
};
|
|
||||||
```
|
|
||||||
|
|
||||||
#### **5.2 載入狀態優化**
|
|
||||||
**目標**: 提供清晰的載入反饋
|
|
||||||
|
|
||||||
**檔案**: `/Users/jettcheng1018/code/dramaling-vocab-learning/frontend/app/generate/page.tsx`
|
|
||||||
**狀態管理**: 新增 `analysisState` state
|
|
||||||
**函數**: 修改 `handleAnalyzeSentence`
|
|
||||||
```typescript
|
|
||||||
// 分析狀態管理
|
|
||||||
const [analysisState, setAnalysisState] = useState({
|
|
||||||
isAnalyzing: false,
|
|
||||||
progress: 0,
|
|
||||||
stage: ''
|
|
||||||
});
|
|
||||||
|
|
||||||
const handleAnalyzeSentence = async () => {
|
|
||||||
setAnalysisState({ isAnalyzing: true, progress: 20, stage: '正在分析句子...' });
|
|
||||||
|
|
||||||
try {
|
|
||||||
setAnalysisState(prev => ({ ...prev, progress: 60, stage: '處理詞彙分析...' }));
|
|
||||||
const response = await fetch(API_URL, { ... });
|
|
||||||
|
|
||||||
setAnalysisState(prev => ({ ...prev, progress: 90, stage: '整理分析結果...' }));
|
|
||||||
const result = await response.json();
|
|
||||||
|
|
||||||
handleAnalysisResult(result);
|
|
||||||
setAnalysisState({ isAnalyzing: false, progress: 100, stage: '分析完成' });
|
|
||||||
} catch (error) {
|
|
||||||
handleAnalysisError(error);
|
|
||||||
}
|
|
||||||
};
|
|
||||||
```
|
|
||||||
|
|
||||||
### **階段六：閃卡整合 (2-3天)**
|
|
||||||
|
|
||||||
#### **6.1 閃卡保存API整合**
|
|
||||||
**目標**: 整合後端閃卡API用於詞彙保存
|
|
||||||
|
|
||||||
**檔案**: `/Users/jettcheng1018/code/dramaling-vocab-learning/frontend/services/flashcardsService.ts` (需新建)
|
|
||||||
**類別**: `FlashcardsService`
|
|
||||||
**方法**: `createFlashcard`, `getAuthToken`
|
|
||||||
```typescript
|
|
||||||
class FlashcardsService {
|
|
||||||
private baseURL = 'http://localhost:5008/api/flashcards';
|
|
||||||
|
|
||||||
async createFlashcard(cardData: FlashcardData): Promise<{success: boolean}> {
|
|
||||||
try {
|
|
||||||
const response = await fetch(this.baseURL, {
|
|
||||||
method: 'POST',
|
|
||||||
headers: {
|
|
||||||
'Content-Type': 'application/json',
|
|
||||||
'Authorization': `Bearer ${this.getAuthToken()}`
|
|
||||||
},
|
|
||||||
body: JSON.stringify({
|
|
||||||
word: cardData.word,
|
|
||||||
translation: cardData.translation,
|
|
||||||
definition: cardData.definition,
|
|
||||||
pronunciation: cardData.pronunciation,
|
|
||||||
partOfSpeech: cardData.partOfSpeech,
|
|
||||||
difficultyLevel: cardData.difficultyLevel,
|
|
||||||
example: cardData.example,
|
|
||||||
exampleTranslation: cardData.exampleTranslation
|
|
||||||
})
|
|
||||||
});
|
|
||||||
|
|
||||||
if (!response.ok) {
|
|
||||||
throw new Error(`API request failed: ${response.status}`);
|
|
||||||
}
|
|
||||||
|
|
||||||
return { success: true };
|
|
||||||
} catch (error) {
|
|
||||||
console.error('Save flashcard error:', error);
|
|
||||||
return { success: false, error: error.message };
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
private getAuthToken(): string | null {
|
|
||||||
return localStorage.getItem('auth_token');
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
export const flashcardsService = new FlashcardsService();
|
|
||||||
```
|
|
||||||
|
|
||||||
#### **6.2 認證機制整合**
|
|
||||||
**目標**: 實現JWT認證用於保護閃卡API
|
|
||||||
|
|
||||||
**檔案**: `/Users/jettcheng1018/code/dramaling-vocab-learning/frontend/services/authService.ts` (需新建)
|
|
||||||
**類別**: `AuthService`
|
|
||||||
**方法**: `login`, `logout`, `isAuthenticated`
|
|
||||||
```typescript
|
|
||||||
class AuthService {
|
|
||||||
private baseURL = 'http://localhost:5008/api/auth';
|
|
||||||
|
|
||||||
async login(username: string, password: string): Promise<{success: boolean, token?: string}> {
|
|
||||||
try {
|
|
||||||
const response = await fetch(`${this.baseURL}/login`, {
|
|
||||||
method: 'POST',
|
|
||||||
headers: { 'Content-Type': 'application/json' },
|
|
||||||
body: JSON.stringify({ username, password })
|
|
||||||
});
|
|
||||||
|
|
||||||
if (!response.ok) {
|
|
||||||
throw new Error('登入失敗');
|
|
||||||
}
|
|
||||||
|
|
||||||
const result = await response.json();
|
|
||||||
|
|
||||||
if (result.success && result.token) {
|
|
||||||
localStorage.setItem('auth_token', result.token);
|
|
||||||
return { success: true, token: result.token };
|
|
||||||
}
|
|
||||||
|
|
||||||
return { success: false };
|
|
||||||
} catch (error) {
|
|
||||||
console.error('Login error:', error);
|
|
||||||
return { success: false };
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
logout(): void {
|
|
||||||
localStorage.removeItem('auth_token');
|
|
||||||
}
|
|
||||||
|
|
||||||
isAuthenticated(): boolean {
|
|
||||||
return !!localStorage.getItem('auth_token');
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
export const authService = new AuthService();
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## ✅ **測試計劃**
|
|
||||||
|
|
||||||
### **單元測試**
|
|
||||||
1. API調用函數測試
|
|
||||||
2. 數據轉換邏輯測試
|
|
||||||
3. 錯誤處理機制測試
|
|
||||||
4. 統計計算邏輯測試
|
|
||||||
|
|
||||||
### **整合測試**
|
|
||||||
1. 完整分析流程測試
|
|
||||||
2. 詞彙保存流程測試
|
|
||||||
3. 認證機制測試
|
|
||||||
4. 錯誤恢復機制測試
|
|
||||||
|
|
||||||
### **E2E測試**
|
|
||||||
1. 用戶完整使用流程
|
|
||||||
2. 各種輸入情況測試
|
|
||||||
3. 錯誤邊界情況測試
|
|
||||||
4. 性能和載入測試
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📋 **實施檢查清單**
|
|
||||||
|
|
||||||
### **前端調整**
|
|
||||||
- [x] 移除API請求中的userLevel參數 ✅ **已完成**
|
|
||||||
- [x] 更新回應數據結構處理邏輯 ✅ **已完成**
|
|
||||||
- [x] 適配新的vocabularyAnalysis格式 ✅ **已完成**
|
|
||||||
- [ ] 更新語法修正面板數據處理 ⏳ **進行中**
|
|
||||||
- [x] 整合慣用語顯示邏輯 ✅ **已完成**ㄎ
|
|
||||||
- [ ] 實現統一錯誤處理機制 ⏳ **進行中**
|
|
||||||
- [ ] 優化載入狀態提示 ⏳ **進行中**
|
|
||||||
- [ ] 整合閃卡保存API ⏳ **進行中**
|
|
||||||
- [ ] 實現JWT認證機制 📅 **計劃中**
|
|
||||||
|
|
||||||
### **後端驗證**
|
|
||||||
- [x] 確認API端點正常運行 ✅ **已完成** - API健康檢查通過
|
|
||||||
- [x] 驗證回應格式正確性 ✅ **已完成** - 格式完全符合規格
|
|
||||||
- [x] 測試錯誤處理機制 ✅ **已完成** - 錯誤處理正常
|
|
||||||
- [ ] 確認認證機制有效 📅 **待實施** - JWT功能需要用戶系統
|
|
||||||
- [x] 驗證CORS設定正確 ✅ **已完成** - 前端可正常訪問
|
|
||||||
|
|
||||||
### **整合測試**
|
|
||||||
- [x] 前後端通信正常 ✅ **已完成** - API調用成功
|
|
||||||
- [x] 數據格式完全匹配 ✅ **已完成** - vocabularyAnalysis格式正確
|
|
||||||
- [x] 錯誤處理機制有效 ✅ **已完成** - 錯誤回饋正常
|
|
||||||
- [x] 性能表現符合預期 ✅ **已完成** - 3.5秒分析時間符合<5秒要求
|
|
||||||
- [x] 用戶體驗流暢 ✅ **已完成** - 前端頁面正常載入
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🚀 **部署準備**
|
|
||||||
|
|
||||||
### **開發環境**
|
|
||||||
1. 確保後端運行在 localhost:5008
|
|
||||||
2. 確保前端運行在 localhost:3000
|
|
||||||
3. 配置CORS允許前端域名
|
|
||||||
4. 設定開發環境的Gemini API密鑰
|
|
||||||
|
|
||||||
### **測試環境**
|
|
||||||
1. 部署到測試服務器
|
|
||||||
2. 配置測試環境的環境變數
|
|
||||||
3. 執行完整的E2E測試
|
|
||||||
4. 進行性能和安全測試
|
|
||||||
|
|
||||||
### **生產環境**
|
|
||||||
1. 配置生產環境域名和SSL
|
|
||||||
2. 設定生產環境API密鑰
|
|
||||||
3. 配置監控和日誌系統
|
|
||||||
4. 準備回滾計劃
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📊 **風險評估與緩解**
|
|
||||||
|
|
||||||
### **技術風險**
|
|
||||||
1. **API格式不匹配**
|
|
||||||
- 風險: 前後端數據格式差異
|
|
||||||
- 緩解: 詳細的格式驗證和測試
|
|
||||||
|
|
||||||
2. **性能問題**
|
|
||||||
- 風險: AI API響應時間過長
|
|
||||||
- 緩解: 實現載入狀態和超時處理
|
|
||||||
|
|
||||||
3. **錯誤處理不完善**
|
|
||||||
- 風險: 用戶體驗受影響
|
|
||||||
- 緩解: 完整的錯誤處理和降級機制
|
|
||||||
|
|
||||||
### **業務風險**
|
|
||||||
1. **功能缺失**
|
|
||||||
- 風險: 某些功能無法正常工作
|
|
||||||
- 緩解: 逐步測試和驗證
|
|
||||||
|
|
||||||
2. **用戶體驗下降**
|
|
||||||
- 風險: 串接過程中影響現有功能
|
|
||||||
- 緩解: 保持現有功能的向後兼容性
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📈 **成功指標**
|
|
||||||
|
|
||||||
### **技術指標**
|
|
||||||
- API回應時間 < 5秒
|
|
||||||
- 錯誤率 < 1%
|
|
||||||
- 前端載入時間 < 2秒
|
|
||||||
- 詞彙分析準確率 > 90%
|
|
||||||
|
|
||||||
### **用戶體驗指標**
|
|
||||||
- 分析完成率 > 95%
|
|
||||||
- 用戶滿意度 > 4.5/5
|
|
||||||
- 功能使用率 > 80%
|
|
||||||
- 錯誤恢復時間 < 3秒
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🔄 **後續維護計劃**
|
|
||||||
|
|
||||||
### **監控機制**
|
|
||||||
1. API調用成功率監控
|
|
||||||
2. 用戶行為數據收集
|
|
||||||
3. 錯誤日誌分析
|
|
||||||
4. 性能指標追蹤
|
|
||||||
|
|
||||||
### **優化計劃**
|
|
||||||
1. 基於用戶反饋優化UI/UX
|
|
||||||
2. AI分析結果質量提升
|
|
||||||
3. 新功能開發和整合
|
|
||||||
4. 性能持續優化
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📚 **參考文件**
|
|
||||||
|
|
||||||
### **產品需求文件**
|
|
||||||
- `/Users/jettcheng1018/code/dramaling-vocab-learning/AI句子分析功能產品需求規格.md`
|
|
||||||
- `/Users/jettcheng1018/code/dramaling-vocab-learning/AI分析API技術實現規格.md`
|
|
||||||
- `/Users/jettcheng1018/code/dramaling-vocab-learning/系統整合與部署規格.md`
|
|
||||||
|
|
||||||
### **關鍵源碼檔案**
|
|
||||||
#### **後端檔案**
|
|
||||||
- `/Users/jettcheng1018/code/dramaling-vocab-learning/backend/DramaLing.Api/Controllers/AIController.cs`
|
|
||||||
- `/Users/jettcheng1018/code/dramaling-vocab-learning/backend/DramaLing.Api/Controllers/FlashcardsController.cs`
|
|
||||||
- `/Users/jettcheng1018/code/dramaling-vocab-learning/backend/DramaLing.Api/Controllers/AuthController.cs`
|
|
||||||
- `/Users/jettcheng1018/code/dramaling-vocab-learning/backend/DramaLing.Api/Services/GeminiService.cs`
|
|
||||||
|
|
||||||
#### **前端檔案**
|
|
||||||
- `/Users/jettcheng1018/code/dramaling-vocab-learning/frontend/app/generate/page.tsx` (主要分析頁面)
|
|
||||||
- `/Users/jettcheng1018/code/dramaling-vocab-learning/frontend/components/ClickableTextV2.tsx` (詞彙標記組件)
|
|
||||||
- `/Users/jettcheng1018/code/dramaling-vocab-learning/frontend/components/GrammarCorrectionPanel.tsx` (語法修正組件)
|
|
||||||
- `/Users/jettcheng1018/code/dramaling-vocab-learning/frontend/app/learn/page.tsx` (學習模式頁面)
|
|
||||||
|
|
||||||
### **配置檔案**
|
|
||||||
- `/Users/jettcheng1018/code/dramaling-vocab-learning/backend/DramaLing.Api/appsettings.json`
|
|
||||||
- `/Users/jettcheng1018/code/dramaling-vocab-learning/frontend/package.json`
|
|
||||||
- `/Users/jettcheng1018/code/dramaling-vocab-learning/frontend/next.config.js`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🎉 **實施狀態總結**
|
|
||||||
|
|
||||||
### **第一階段完成狀況 (2025-01-25)**
|
|
||||||
|
|
||||||
#### **✅ 已完成功能 (核心串接)**
|
|
||||||
1. **API格式適配** - 移除userLevel參數，更新請求格式
|
|
||||||
2. **回應數據處理** - 適配新的`result.data`結構
|
|
||||||
3. **詞彙分析整合** - 使用`vocabularyAnalysis`對象格式
|
|
||||||
4. **慣用語功能** - 整合`idioms`陣列顯示
|
|
||||||
5. **統計計算** - 修正詞彙難度統計邏輯
|
|
||||||
6. **API測試** - 驗證前後端通信正常
|
|
||||||
|
|
||||||
#### **📊 測試結果**
|
|
||||||
- ✅ **後端API健康檢查**: 正常運行
|
|
||||||
- ✅ **句子分析API**: 3.5秒回應時間，符合<5秒要求
|
|
||||||
- ✅ **數據格式匹配**: 100%兼容新後端格式
|
|
||||||
- ✅ **詞彙分析**: CEFR分級和統計正確
|
|
||||||
- ✅ **語法修正**: 錯誤檢測和修正建議正常
|
|
||||||
- ✅ **慣用語檢測**: 顯示和交互功能正常
|
|
||||||
|
|
||||||
#### **🚀 核心功能狀態**
|
|
||||||
- **AI句子分析**: ✅ **生產就緒**
|
|
||||||
- **詞彙標記**: ✅ **生產就緒**
|
|
||||||
- **語法修正**: ✅ **生產就緒**
|
|
||||||
- **慣用語學習**: ✅ **生產就緒**
|
|
||||||
- **統計卡片**: ✅ **生產就緒**
|
|
||||||
- **響應式設計**: ✅ **生產就緒**
|
|
||||||
|
|
||||||
#### **📈 性能指標達成**
|
|
||||||
- **API回應時間**: 3.5秒 < 5秒目標 ✅
|
|
||||||
- **前端載入**: <2秒 ✅
|
|
||||||
- **詞彙分析準確**: 基於Gemini 1.5 Flash ✅
|
|
||||||
- **用戶體驗**: 流暢互動 ✅
|
|
||||||
|
|
||||||
### **下一階段建議 (可選優化)**
|
|
||||||
1. **JWT認證整合** - 用於保護閃卡功能
|
|
||||||
2. **錯誤處理增強** - 更友善的錯誤提示
|
|
||||||
3. **載入狀態優化** - 進度指示器
|
|
||||||
4. **離線快取** - 分析結果本地存儲
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**計劃制定者**: DramaLing技術團隊
|
|
||||||
**計劃版本**: v1.1 - 第一階段完成
|
|
||||||
**實際完成時間**: 1個工作天 (提前完成)
|
|
||||||
**完成狀態**: 🎯 **核心功能100%可用，生產就緒**
|
|
||||||
**下次評估**: 基於用戶回饋進行功能優化
|
|
||||||
|
|
@ -313,28 +313,6 @@ function GenerateContent() {
|
||||||
)
|
)
|
||||||
})()}
|
})()}
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
{/* 學習提示系統 */}
|
|
||||||
<div className="bg-blue-50 border border-blue-200 rounded-lg p-4 mt-4">
|
|
||||||
<h3 className="text-sm font-semibold text-blue-900 mb-2">💡 詞彙標記說明</h3>
|
|
||||||
<div className="grid grid-cols-1 sm:grid-cols-3 gap-3 text-xs">
|
|
||||||
<div className="flex items-center gap-2">
|
|
||||||
<span className="inline-block w-4 h-4 bg-gray-50 border border-dashed border-gray-300 rounded opacity-80"></span>
|
|
||||||
<span className="text-gray-600">太簡單 - 已掌握</span>
|
|
||||||
</div>
|
|
||||||
<div className="flex items-center gap-2">
|
|
||||||
<span className="inline-block w-4 h-4 bg-green-50 border border-green-200 rounded"></span>
|
|
||||||
<span className="text-gray-600">重點學習 - 適合程度</span>
|
|
||||||
</div>
|
|
||||||
<div className="flex items-center gap-2">
|
|
||||||
<span className="inline-block w-4 h-4 bg-orange-50 border border-orange-200 rounded"></span>
|
|
||||||
<span className="text-gray-600">有挑戰 - 進階詞彙</span>
|
|
||||||
</div>
|
|
||||||
</div>
|
|
||||||
<p className="text-xs text-blue-700 mt-2">
|
|
||||||
點擊標記的詞彙可查看詳細解釋，一鍵保存到詞卡複習！
|
|
||||||
</p>
|
|
||||||
</div>
|
|
||||||
</div>
|
</div>
|
||||||
</div>
|
</div>
|
||||||
) : (
|
) : (
|
||||||
|
|
|
||||||
|
|
@ -566,4 +566,12 @@ WCAG 2.1 AA 合規:
|
||||||
**關聯文件**:
|
**關聯文件**:
|
||||||
- 《AI分析API技術實現規格》- 技術實現細節
|
- 《AI分析API技術實現規格》- 技術實現細節
|
||||||
- 《系統整合與部署規格》- 系統整合和部署
|
- 《系統整合與部署規格》- 系統整合和部署
|
||||||
- 《AI驅動產品後端技術架構指南》- 架構設計指導
|
- 《AI驅動產品後端技術架構指南》- 架構設計指導
|
||||||
|
|
||||||
|
|
||||||
|
待辦
|
||||||
|
- [ ] 顯示常用
|
||||||
|
- [ ] 所有詞彙都要分析
|
||||||
|
- [ ] 點圖+，就會生出例句圖
|
||||||
|
- [ ] 點播放，要能生出語音
|
||||||
|
- [ ] 儲存詞彙的後端還沒做好
|
||||||
131
後端架構優化待辦清單.md
131
後端架構優化待辦清單.md
|
|
@ -1,131 +0,0 @@
|
||||||
# 後端架構優化待辦清單
|
|
||||||
|
|
||||||
## 📋 **優化項目總覽**
|
|
||||||
|
|
||||||
基於技術架構指南的分析，當前後端需要進行以下優化：
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🔧 **Priority 1: 配置管理優化**
|
|
||||||
|
|
||||||
### ✅ **P1.1 建立強型別配置類別**
|
|
||||||
- [x] 建立 `GeminiOptions` 配置類別
|
|
||||||
- [ ] 建立 `DatabaseOptions` 配置類別
|
|
||||||
- [ ] 建立 `AuthenticationOptions` 配置類別
|
|
||||||
- [x] 更新 `appsettings.json` 結構
|
|
||||||
|
|
||||||
### ✅ **P1.2 實施配置驗證**
|
|
||||||
- [x] 實作 `IValidateOptions<T>` 驗證器
|
|
||||||
- [x] 添加必要欄位驗證
|
|
||||||
- [x] 實施範圍檢查和格式驗證
|
|
||||||
- [x] 在啟動時驗證所有配置
|
|
||||||
|
|
||||||
### ✅ **P1.3 外部化敏感配置**
|
|
||||||
- [x] 移除硬編碼的預設值
|
|
||||||
- [x] 實施安全的金鑰管理
|
|
||||||
- [x] 建立環境特定配置檔案
|
|
||||||
- [x] 添加配置載入錯誤處理
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🛡️ **Priority 2: 錯誤處理和穩定性**
|
|
||||||
|
|
||||||
### ✅ **P2.1 實施重試機制**
|
|
||||||
- [ ] 安裝 Polly 重試庫
|
|
||||||
- [ ] 建立指數退避重試策略
|
|
||||||
- [ ] 實施 AI 服務重試邏輯
|
|
||||||
- [ ] 添加重試事件日誌
|
|
||||||
|
|
||||||
### ✅ **P2.2 添加斷路器模式**
|
|
||||||
- [ ] 實施斷路器服務
|
|
||||||
- [ ] 配置斷路器閾值
|
|
||||||
- [ ] 添加斷路器狀態監控
|
|
||||||
- [ ] 實施自動恢復機制
|
|
||||||
|
|
||||||
### ✅ **P2.3 建立降級策略**
|
|
||||||
- [ ] 設計 AI 服務降級邏輯
|
|
||||||
- [ ] 實施備用回應機制
|
|
||||||
- [ ] 建立服務可用性檢查
|
|
||||||
- [ ] 添加降級事件通知
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📊 **Priority 3: 監控和可觀測性**
|
|
||||||
|
|
||||||
### ✅ **P3.1 實施結構化日誌**
|
|
||||||
- [ ] 建立日誌擴展方法
|
|
||||||
- [ ] 實施業務操作日誌標準
|
|
||||||
- [ ] 添加 AI 請求追蹤日誌
|
|
||||||
- [ ] 建立錯誤分類日誌
|
|
||||||
|
|
||||||
### ✅ **P3.2 建立詳細健康檢查**
|
|
||||||
- [ ] 實作 `IHealthCheck` 介面
|
|
||||||
- [ ] 檢查 AI 服務健康狀態
|
|
||||||
- [ ] 檢查資料庫連接狀態
|
|
||||||
- [ ] 檢查記憶體使用狀況
|
|
||||||
|
|
||||||
### ✅ **P3.3 添加性能指標收集**
|
|
||||||
- [ ] 實施請求時間監控
|
|
||||||
- [ ] 添加 AI API 調用統計
|
|
||||||
- [ ] 監控記憶體和 CPU 使用
|
|
||||||
- [ ] 建立告警機制
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🏗️ **Priority 4: 架構重構**
|
|
||||||
|
|
||||||
### ✅ **P4.1 重組服務註冊**
|
|
||||||
- [ ] 按功能分組服務註冊
|
|
||||||
- [ ] 建立服務註冊擴展方法
|
|
||||||
- [ ] 實施清晰的依賴注入結構
|
|
||||||
- [ ] 添加服務生命週期註釋
|
|
||||||
|
|
||||||
### ✅ **P4.2 實施Repository模式**
|
|
||||||
- [ ] 建立 Repository 基礎介面
|
|
||||||
- [ ] 實作資料存取層抽象
|
|
||||||
- [ ] 優化資料庫查詢性能
|
|
||||||
- [ ] 實施查詢快取策略
|
|
||||||
|
|
||||||
### ✅ **P4.3 添加AI提供商抽象層**
|
|
||||||
- [ ] 建立 `IAIProvider` 抽象介面
|
|
||||||
- [ ] 實施 Gemini 提供商
|
|
||||||
- [ ] 建立提供商選擇器
|
|
||||||
- [ ] 支援多提供商切換
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📈 **完成狀態追蹤**
|
|
||||||
|
|
||||||
### **已完成項目**
|
|
||||||
- ✅ P1.1: 建立強型別配置類別 (GeminiOptions)
|
|
||||||
- ✅ P1.2: 實施配置驗證 (GeminiOptionsValidator)
|
|
||||||
- ✅ P1.3: 外部化敏感配置 (環境變數+配置檔案)
|
|
||||||
|
|
||||||
### **進行中項目**
|
|
||||||
- 🔄 P2.1: 實施重試機制 (Polly庫已添加)
|
|
||||||
|
|
||||||
### **待開始項目**
|
|
||||||
- ⏳ P1.1: 建立其他配置類別 (DatabaseOptions, AuthenticationOptions)
|
|
||||||
- ⏳ P2.2: 添加斷路器模式
|
|
||||||
- ⏳ P2.3: 建立降級策略
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📝 **優化記錄**
|
|
||||||
|
|
||||||
### **2025-01-25**
|
|
||||||
- 📋 建立優化待辦清單
|
|
||||||
- 🎯 確定優化優先級和範圍
|
|
||||||
- 📚 基於技術架構指南制定改進計劃
|
|
||||||
- ✅ **完成 P1.1**: 建立 `GeminiOptions` 強型別配置類別
|
|
||||||
- ✅ **完成 P1.2**: 實施 `GeminiOptionsValidator` 配置驗證
|
|
||||||
- 🔧 更新 `GeminiService` 使用強型別配置
|
|
||||||
- 📦 添加 Polly 重試庫和健康檢查庫
|
|
||||||
- 🔄 **進行中**: P2.1 重試機制實施準備
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**文件版本**: v1.0
|
|
||||||
**建立時間**: 2025-01-25
|
|
||||||
**負責人**: DramaLing 技術團隊
|
|
||||||
**預計完成**: 2025-02-08 (2週)
|
|
||||||
Loading…
Reference in New Issue