# 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