14 KiB

Raw Blame History

AI生成功能後端API規格

📋 文件資訊

文件名稱: AI生成功能後端API規格
版本: v1.0
建立日期: 2025-01-25
最後更新: 2025-01-25
負責團隊: DramaLing後端開發團隊
對應前端: /app/generate/page.tsx

🎯 API概述

核心功能

AI生成功能後端API提供智能英文句子分析服務，包含語法檢查、詞彙分析、翻譯和慣用語識別，為前端提供完整的學習數據支援。

主要特色

🤖 AI驅動分析 - 使用先進AI模型進行語言分析
🎯 個人化標記 - 基於用戶CEFR等級的詞彙分類
📊 多維度數據 - 提供詞彙、語法、翻譯、慣用語分析
⚡ 高性能處理 - 支援快速響應和批次處理

🛠 技術架構

架構組成

API Gateway:
  - 路由管理
  - 認證驗證
  - 流量控制
  - 錯誤處理

AI Analysis Service:
  - 語法分析引擎
  - 詞彙分析引擎
  - 翻譯服務
  - 慣用語識別

Database Layer:
  - 詞彙資料庫
  - 用戶數據
  - 分析結果緩存
  - 使用記錄

External Services:
  - AI模型服務
  - 詞典API
  - 翻譯API

技術棧要求

語言: C# / .NET 8
框架: ASP.NET Core Web API
資料庫: PostgreSQL + Redis (緩存)
AI服務: OpenAI GPT / Azure OpenAI
部署: Docker + Kubernetes
監控: Application Insights

📡 API端點規格

API-001: 句子智能分析

端點資訊

POST /api/ai/analyze-sentence
Content-Type: application/json
Authorization: Bearer {token}

請求格式

{
  "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,
    "includePhraseDetection": true,
    "includeExamples": true
  }
}

請求參數說明

參數	類型	必需	說明
inputText	string	是	待分析的英文句子 (最多300字)
userLevel	string	是	用戶CEFR等級 (A1-C2)
analysisMode	string	否	分析模式: "basic"\|"full" (預設: "full")
options	object	否	分析選項配置

成功回應格式

{
  "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",
        "isPhrase": false,
        "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",
        "isPhrase": false,
        "frequency": "high",
        "synonyms": ["recently", "only", "merely"],
        "example": "I just arrived.",
        "exampleTranslation": "我剛到。",
        "tags": ["time", "adverb"]
      },
      "cut someone some slack": {
        "word": "cut someone some slack",
        "translation": "對某人寬容一點",
        "definition": "to be more lenient or forgiving with someone",
        "partOfSpeech": "idiom",
        "pronunciation": "/kʌt ˈsʌmwʌn sʌm slæk/",
        "difficultyLevel": "B2",
        "isPhrase": true,
        "frequency": "medium",
        "synonyms": ["be lenient", "be forgiving", "give leeway"],
        "example": "Cut him some slack, he's new here.",
        "exampleTranslation": "對他寬容一點，他是新來的。",
        "tags": ["idiom", "workplace", "tolerance"]
      }
    },
    "statistics": {
      "totalWords": 16,
      "uniqueWords": 15,
      "simpleWords": 8,
      "moderateWords": 4,
      "difficultWords": 3,
      "phrases": 1,
      "averageDifficulty": "A2"
    },
    "metadata": {
      "analysisModel": "gpt-4",
      "analysisVersion": "1.0",
      "processingDate": "2025-01-25T10:30:00Z",
      "userLevel": "A2"
    }
  }
}

錯誤回應格式

{
  "success": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "輸入文本超過最大長度限制",
    "details": {
      "maxLength": 300,
      "actualLength": 350
    }
  },
  "timestamp": "2025-01-25T10:30:00Z",
  "requestId": "uuid-string"
}

🔧 數據模型規格

VocabularyAnalysis 模型

interface VocabularyAnalysis {
  word: string                    // 詞彙本身
  translation: string            // 中文翻譯
  definition: string             // 英文定義
  partOfSpeech: string          // 詞性
  pronunciation: string         // 發音 (IPA)
  difficultyLevel: CEFRLevel    // CEFR等級
  isPhrase: boolean             // 是否為慣用語
  frequency: FrequencyLevel     // 使用頻率
  synonyms: string[]            // 同義詞
  example?: string              // 例句
  exampleTranslation?: string   // 例句翻譯
  tags: string[]                // 標籤分類
}

GrammarCorrection 模型

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"
}

枚舉定義

type CEFRLevel = "A1" | "A2" | "B1" | "B2" | "C1" | "C2"
type FrequencyLevel = "very_high" | "high" | "medium" | "low" | "very_low"
type AnalysisMode = "basic" | "full"

🔒 認證與授權

API認證

認證方式: Bearer Token (JWT)
Token位置: Authorization Header
Token格式: "Bearer {jwt_token}"
過期時間: 24小時
刷新機制: Refresh Token

權限等級

Guest用戶:
  - 每日5次免費分析
  - 基礎分析功能
  - 無歷史記錄

Premium用戶:
  - 無限制分析
  - 完整分析功能
  - 歷史記錄保存
  - 批次分析

⚡ 性能要求

響應時間目標

基礎分析: < 2秒
完整分析: < 5秒
批次分析: < 10秒 (10句)
錯誤回應: < 500ms

吞吐量要求

並發請求: 100 req/sec
每日請求: 100,000 requests
峰值處理: 200 req/sec

資源限制

輸入文本: 最大300字符
輸出大小: 最大5MB
內存使用: 最大500MB per request
超時設定: 30秒

📊 監控與日誌

關鍵指標

性能指標:
  - 請求響應時間
  - API成功率
  - AI服務響應時間
  - 資料庫查詢時間

業務指標:
  - 每日分析次數
  - 用戶活躍度
  - 錯誤類型分布
  - 詞彙覆蓋率

日誌格式

{
  "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
  }
}

🔄 錯誤處理

錯誤碼定義

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 - 處理超時

錯誤回應範例

{
  "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: 正常分析流程

測試目的: 驗證完整分析功能
輸入數據:
  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: 輸入驗證測試

測試目的: 驗證輸入驗證機制
測試案例:
  - 空字串輸入
  - 超長文本 (>300字符)
  - 無效CEFR等級
  - 純數字輸入
  - 特殊字符輸入

預期結果: 400錯誤與相應錯誤訊息

TC-003: 認證測試

測試目的: 驗證API認證機制
測試案例:
  - 無Token訪問
  - 無效Token
  - 過期Token
  - 權限不足

預期結果: 401/403錯誤

性能測試

負載測試:
  - 100 concurrent users
  - 1000 requests in 10 minutes
  - 目標: 95% requests < 5 seconds

壓力測試:
  - 200 concurrent users
  - 持續20分鐘
  - 目標: API仍然響應

容量測試:
  - 模擬10,000 daily users
  - 24小時持續測試
  - 目標: 系統穩定運行

🚀 部署規格

環境配置

Development:
  database: PostgreSQL 15
  cache: Redis 7
  ai_service: OpenAI API
  replicas: 1
  resources:
    cpu: 0.5 cores
    memory: 1GB

Staging:
  database: PostgreSQL 15 (replica)
  cache: Redis 7 (cluster)
  ai_service: OpenAI API
  replicas: 2
  resources:
    cpu: 1 core
    memory: 2GB

Production:
  database: PostgreSQL 15 (HA cluster)
  cache: Redis 7 (cluster)
  ai_service: Azure OpenAI
  replicas: 5
  resources:
    cpu: 2 cores
    memory: 4GB

Docker配置

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個月)

功能擴展:
  - 批次分析API
  - 文本難度評估
  - 個人化詞彙推薦
  - 學習進度追蹤

技術改進:
  - GraphQL支援
  - WebSocket即時分析
  - 分析結果緩存優化
  - AI模型版本管理

中期擴展 (3-6個月)

多語言支援:
  - 法語分析
  - 德語分析
  - 西班牙語分析

進階功能:
  - 語音分析集成
  - 圖片文字識別
  - 視頻字幕分析
  - 個人化AI調優

長期擴展 (6-12個月)

AI升級:
  - 自訂AI模型訓練
  - 多模態學習分析
  - 即時語言學習建議
  - 預測性學習路徑

企業功能:
  - 團隊管理API
  - 批量用戶管理
  - 詳細分析報告
  - 自訂詞彙庫

🔐 安全規格

數據安全

傳輸安全:
  - TLS 1.3加密
  - API密鑰輪換
  - 請求簽名驗證

數據保護:
  - 個人數據加密存儲
  - 敏感信息遮罩
  - 數據保留政策
  - GDPR合規

API安全

防護措施:
  - 速率限制
  - IP白名單
  - 異常檢測
  - 自動封鎖機制

審計日誌:
  - 完整請求記錄
  - 敏感操作追蹤
  - 異常行為警報
  - 合規性報告

📋 API文檔規範

OpenAPI規格

使用OpenAPI 3.0規範
提供互動式API文檔
自動生成客戶端SDK
版本化API文檔

文檔內容

詳細的端點說明
請求/回應範例
錯誤碼說明
最佳實踐指南

文件版本: v1.0 API版本: v1 最後更新: 2025-01-25 下次審查: 2025-02-25

14 KiB Raw Blame History Unescape Escape

AI生成功能後端API規格

📋 文件資訊

🎯 API概述

核心功能

主要特色

🛠 技術架構

架構組成

技術棧要求

📡 API端點規格

API-001: 句子智能分析

端點資訊

請求格式

請求參數說明

成功回應格式

錯誤回應格式

🔧 數據模型規格

VocabularyAnalysis 模型

GrammarCorrection 模型

枚舉定義

🔒 認證與授權

API認證

權限等級

⚡ 性能要求

響應時間目標

吞吐量要求

資源限制

📊 監控與日誌

關鍵指標

日誌格式

🔄 錯誤處理

錯誤碼定義

錯誤回應範例

🧪 測試規格

API測試案例

TC-001: 正常分析流程

TC-002: 輸入驗證測試

TC-003: 認證測試

性能測試

🚀 部署規格

環境配置

Docker配置

📈 擴展計劃

短期擴展 (1-3個月)

中期擴展 (3-6個月)

長期擴展 (6-12個月)

🔐 安全規格

數據安全

API安全

📋 API文檔規範

OpenAPI規格

文檔內容

14 KiB

Raw Blame History