19 KiB

Raw Blame History

AI生成功能後端API規格

📋 文件資訊

文件名稱: AI生成功能後端API規格
版本: v1.0
建立日期: 2025-01-25
最後更新: 2025-01-25 (修正API規格)
負責團隊: 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服務: Google Gemini 1.5 Flash API (包含結構化Prompt設計)
部署: 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.",
  "analysisMode": "full",
  "options": {
    "includeGrammarCheck": true,
    "includeVocabularyAnalysis": true,
    "includeTranslation": true,
    "includeIdiomDetection": true,
    "includeExamples": true
  }
}

請求參數說明

參數	類型	必需	說明
inputText	string	是	待分析的英文句子 (最多300字)
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",
        "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",
    }
  }
}

錯誤回應格式

{
  "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等級
  frequency: FrequencyLevel     // 使用頻率
  synonyms: string[]            // 同義詞
  example?: string              // 例句
  exampleTranslation?: 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"
}

IdiomDto 模型

interface IdiomDto {
  idiom: string                 // 慣用語本身
  translation: string          // 中文翻譯
  definition: string           // 英文定義
  pronunciation: string        // 發音 (IPA)
  difficultyLevel: CEFRLevel   // CEFR等級
  frequency: FrequencyLevel    // 使用頻率
  synonyms: string[]           // 同義詞或相似表達
  example?: string             // 例句
  exampleTranslation?: string  // 例句翻譯
}

AnalysisMetadata 模型

interface AnalysisMetadata {
  analysisModel: string        // AI模型名稱
  analysisVersion: string      // 分析版本
  processingDate: string       // 處理時間 (ISO 8601)
}

ApiErrorResponse 模型

interface ApiErrorResponse {
  success: boolean             // 固定為 false
  error: ApiError             // 錯誤詳情
  timestamp: string           // 錯誤時間 (ISO 8601)
  requestId: string          // 請求ID
}

interface ApiError {
  code: string               // 錯誤代碼
  message: string           // 錯誤訊息
  details?: object          // 錯誤詳情
  suggestions: string[]     // 建議解決方案
}

枚舉定義

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模板

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指導原則

分析指導方針

語法檢查:
  - 檢測範圍: 時態錯誤、主謂一致、介詞使用、詞序問題
  - 修正原則: 提供自然且正確的英語表達
  - 解釋語言: 使用繁體中文（台灣標準）

詞彙分析:
  - 包含範圍: 所有有意義的詞彙（排除冠詞 a, an, the）
  - CEFR標準: 準確分配A1-C2等級
  - 發音標記: 使用國際音標(IPA)
  - 例句品質: 提供實用且常見的例句

慣用語識別:
  - 識別目標: 慣用語、片語動詞、固定搭配
  - 分類原則: 獨立於vocabularyAnalysis處理
  - 解釋詳度: 提供文化背景和使用場景

翻譯品質:
  - 語言標準: 繁體中文（台灣用法）
  - 自然程度: 符合中文表達習慣
  - 準確性: 保持原文語義完整

Prompt優化策略

結構化輸出控制

**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

**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版本管理

版本演進記錄

v1.0 (2025-01-20):
  - 基礎prompt結構
  - 簡單詞彙分析

v1.5 (2025-01-22):
  - 新增慣用語識別
  - 優化語法檢查

v2.0 (2025-01-25):
  - 結構化JSON輸出
  - 完整資料模型支援
  - 繁體中文本地化
  - 錯誤處理機制

A/B測試配置

// 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認證

認證方式: 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": "gemini-1.5-flash",
  "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."
  analysisMode: "full"

預期結果:
  statusCode: 200
  grammarCorrection.hasErrors: true
  grammarCorrection.corrections.length: 2
  vocabularyAnalysis keys: 16 (不含慣用語)
  idioms.length: 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: 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配置

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.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計算邏輯（前端自行處理統計）

19 KiB Raw Blame History Unescape Escape

AI生成功能後端API規格

📋 文件資訊

🎯 API概述

核心功能

主要特色

🛠 技術架構

架構組成

技術棧要求

📡 API端點規格

API-001: 句子智能分析

端點資訊

請求格式

請求參數說明

成功回應格式

錯誤回應格式

🔧 數據模型規格

VocabularyAnalysis 模型

GrammarCorrection 模型

IdiomDto 模型

AnalysisMetadata 模型

ApiErrorResponse 模型

枚舉定義

🤖 AI Prompt設計規格

Prompt架構設計

核心Prompt模板

Prompt指導原則

分析指導方針

Prompt優化策略

結構化輸出控制

錯誤處理Prompt

Prompt版本管理

版本演進記錄

A/B測試配置

🔒 認證與授權

API認證

權限等級

⚡ 性能要求

響應時間目標

吞吐量要求

資源限制

📊 監控與日誌

關鍵指標

日誌格式

🔄 錯誤處理

錯誤碼定義

錯誤回應範例

🧪 測試規格

API測試案例

TC-001: 正常分析流程

TC-002: 輸入驗證測試

TC-003: 認證測試

性能測試

🚀 部署規格

環境配置

Docker配置

📈 擴展計劃

短期擴展 (1-3個月)

中期擴展 (3-6個月)

長期擴展 (6-12個月)

🔐 安全規格

數據安全

API安全

📋 API文檔規範

OpenAPI規格

文檔內容

19 KiB

Raw Blame History