629 lines
14 KiB
Markdown
629 lines
14 KiB
Markdown
# AI生成功能後端API規格
|
||
|
||
## 📋 **文件資訊**
|
||
|
||
- **文件名稱**: AI生成功能後端API規格
|
||
- **版本**: v1.0
|
||
- **建立日期**: 2025-01-25
|
||
- **最後更新**: 2025-01-25
|
||
- **負責團隊**: 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 API
|
||
部署: 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.",
|
||
"userLevel": "A2",
|
||
"analysisMode": "full",
|
||
"options": {
|
||
"includeGrammarCheck": true,
|
||
"includeVocabularyAnalysis": true,
|
||
"includeTranslation": true,
|
||
"includeIdiomDetection": true,
|
||
"includeExamples": true
|
||
}
|
||
}
|
||
```
|
||
|
||
#### **請求參數說明**
|
||
| 參數 | 類型 | 必需 | 說明 |
|
||
|------|------|------|------|
|
||
| inputText | string | 是 | 待分析的英文句子 (最多300字) |
|
||
| userLevel | string | 是 | 用戶CEFR等級 (A1-C2) |
|
||
| 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": "她是一名老師。",
|
||
"tags": ["basic", "pronoun"]
|
||
},
|
||
"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": "我剛到。",
|
||
"tags": ["time", "adverb"]
|
||
}
|
||
},
|
||
"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": "對他寬容一點，他是新來的。"
|
||
}
|
||
],
|
||
"statistics": {
|
||
"totalWords": 16,
|
||
"uniqueWords": 15,
|
||
"simpleWords": 8,
|
||
"moderateWords": 4,
|
||
"difficultWords": 3,
|
||
"idioms": 1,
|
||
"averageDifficulty": "A2"
|
||
},
|
||
"metadata": {
|
||
"analysisModel": "gemini-pro",
|
||
"analysisVersion": "1.0",
|
||
"processingDate": "2025-01-25T10:30:00Z",
|
||
"userLevel": "A2"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### **錯誤回應格式**
|
||
```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 // 例句翻譯
|
||
tags: 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"
|
||
}
|
||
```
|
||
|
||
### **枚舉定義**
|
||
```typescript
|
||
type CEFRLevel = "A1" | "A2" | "B1" | "B2" | "C1" | "C2"
|
||
type FrequencyLevel = "very_high" | "high" | "medium" | "low" | "very_low"
|
||
type AnalysisMode = "basic" | "full"
|
||
```
|
||
|
||
---
|
||
|
||
## 🔒 **認證與授權**
|
||
|
||
### **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": "gpt-4",
|
||
"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."
|
||
userLevel: "A2"
|
||
analysisMode: "full"
|
||
|
||
預期結果:
|
||
statusCode: 200
|
||
grammarCorrection.hasErrors: true
|
||
grammarCorrection.corrections.length: 2
|
||
vocabularyAnalysis keys: 17 (16個詞 + 1個慣用語)
|
||
statistics.simpleWords: 8
|
||
statistics.moderateWords: 4
|
||
statistics.difficultWords: 3
|
||
statistics.phrases: 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.0
|
||
**API版本**: v1
|
||
**最後更新**: 2025-01-25
|
||
**下次審查**: 2025-02-25 |