# AI分析API技術實現規格

## 📋 **文件資訊**

- **文件名稱**: AI分析API技術實現規格
- **版本**: v2.0
- **建立日期**: 2025-01-25
- **最後更新**: 2025-01-25
- **負責團隊**: DramaLing後端技術團隊
- **對應產品需求**: 《AI句子分析功能產品需求規格》

---

## 🛠 **技術架構概述**

### **系統架構設計**
```yaml
分層架構:
  - API Gateway: 認證、限流、路由
  - Controllers: HTTP請求處理、參數驗證
  - Services: 業務邏輯、AI整合
  - Data Access: 資料庫操作、快取管理
  - External APIs: AI服務、第三方整合

技術棧:
  - 語言: C# / .NET 8
  - 框架: ASP.NET Core Web API
  - AI服務: Google Gemini 1.5 Flash
  - 資料庫: SQLite (開發) / PostgreSQL (生產)
  - 快取: Redis (生產) / In-Memory (開發)
  - 監控: Application Insights
```

### **核心設計原則**
- **單一職責**: 每個服務類別職責明確
- **依賴注入**: 基於介面的鬆耦合設計
- **配置外部化**: 強型別配置管理
- **錯誤恢復**: 重試機制和降級策略
- **可觀測性**: 結構化日誌和健康檢查

---

## 📡 **API端點設計**

### **核心分析端點**

#### **POST /api/ai/analyze-sentence**
**功能**: 智能英文句子分析

**請求格式**:
```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
  }
}
```

**回應格式**:
```json
{
  "success": true,
  "processingTime": 2.34,
  "data": {
    "analysisId": "uuid-string",
    "originalText": "原始輸入文本",
    "grammarCorrection": {
      "hasErrors": true,
      "correctedText": "修正後文本",
      "corrections": [
        {
          "position": { "start": 9, "end": 13 },
          "error": "join",
          "correction": "joined",
          "type": "時態錯誤",
          "explanation": "第三人稱單數過去式應使用 'joined'",
          "severity": "high"
        }
      ]
    },
    "sentenceMeaning": "中文翻譯",
    "vocabularyAnalysis": {
      "word": {
        "word": "詞彙",
        "translation": "中文翻譯",
        "definition": "英文定義",
        "partOfSpeech": "詞性",
        "pronunciation": "/IPA發音/",
        "difficultyLevel": "A1-C2",
        "frequency": "high/medium/low",
        "synonyms": ["同義詞陣列"],
        "example": "例句",
        "exampleTranslation": "例句翻譯"
      }
    },
    "idioms": [
      {
        "idiom": "cut someone some slack",
        "translation": "對某人寬容一點",
        "definition": "to be more lenient or forgiving",
        "pronunciation": "/發音/",
        "difficultyLevel": "B2",
        "frequency": "medium",
        "synonyms": ["be lenient", "give leeway"],
        "example": "例句",
        "exampleTranslation": "例句翻譯"
      }
    ],
    "metadata": {
      "analysisModel": "gemini-1.5-flash",
      "analysisVersion": "2.0",
      "processingDate": "2025-01-25T10:30:00Z"
    }
  }
}
```

#### **GET /api/ai/health**
**功能**: 服務健康檢查

**回應格式**:
```json
{
  "status": "Healthy",
  "service": "AI Analysis Service",
  "timestamp": "2025-01-25T10:30:00Z",
  "version": "2.0",
  "dependencies": {
    "geminiApi": "healthy",
    "database": "healthy",
    "cache": "healthy"
  }
}
```

---

## 🤖 **AI集成架構**

### **Prompt工程設計**

#### **核心Prompt模板**
```text
You are an English learning assistant. Analyze this sentence 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"
    }
  ]
}

**Analysis Guidelines:**
1. **Grammar Check**: Detect tense errors, subject-verb agreement, preposition usage, word order
2. **Vocabulary Analysis**: Include ALL significant words (exclude articles: a, an, the)
3. **CEFR Levels**: Assign accurate A1-C2 levels for each word
4. **Idioms**: Identify any idiomatic expressions or phrasal verbs
5. **Translations**: Use Traditional Chinese (Taiwan standard)

**IMPORTANT**: Return ONLY the JSON object, no additional text or explanation.
```

### **AI服務配置**

#### **Gemini API配置**
```yaml
模型配置:
  - 模型: gemini-1.5-flash
  - 溫度: 0.7 (平衡創造性和準確性)
  - 最大輸出: 2000 tokens
  - 超時: 30秒

重試策略:
  - 最大重試: 3次
  - 退避策略: 指數退避 (1s, 2s, 4s)
  - 重試條件: 網路錯誤、超時、5xx錯誤
  - 熔斷條件: 連續失敗 > 5次

降級策略:
  - 備用回應: 基礎翻譯和詞性分析
  - 快取回退: 相似句子的歷史分析結果
  - 服務狀態: 實時監控和告警
```

---

## 🔧 **數據模型設計**

### **請求模型**

#### **SentenceAnalysisRequest**
```csharp
public class SentenceAnalysisRequest
{
    [Required]
    [StringLength(300, MinimumLength = 1)]
    public string InputText { get; set; } = string.Empty;

    public string AnalysisMode { get; set; } = "full";

    public AnalysisOptions? Options { get; set; }
}

public class AnalysisOptions
{
    public bool IncludeGrammarCheck { get; set; } = true;
    public bool IncludeVocabularyAnalysis { get; set; } = true;
    public bool IncludeTranslation { get; set; } = true;
    public bool IncludeIdiomDetection { get; set; } = true;
    public bool IncludeExamples { get; set; } = true;
}
```

### **回應模型**

#### **核心資料模型**
```csharp
public class SentenceAnalysisResponse
{
    public bool Success { get; set; } = true;
    public double ProcessingTime { get; set; }
    public SentenceAnalysisData? Data { get; set; }
    public string? Message { get; set; }
}

public class SentenceAnalysisData
{
    public string AnalysisId { get; set; } = Guid.NewGuid().ToString();
    public string OriginalText { get; set; } = string.Empty;
    public GrammarCorrectionDto? GrammarCorrection { get; set; }
    public string SentenceMeaning { get; set; } = string.Empty;
    public Dictionary<string, VocabularyAnalysisDto> VocabularyAnalysis { get; set; } = new();
    public List<IdiomDto> Idioms { get; set; } = new();
    public AnalysisMetadata Metadata { get; set; } = new();
}
```

#### **詳細模型定義**
```csharp
public class VocabularyAnalysisDto
{
    public string Word { get; set; } = string.Empty;
    public string Translation { get; set; } = string.Empty;
    public string Definition { get; set; } = string.Empty;
    public string PartOfSpeech { get; set; } = string.Empty;
    public string Pronunciation { get; set; } = string.Empty;
    public string DifficultyLevel { get; set; } = string.Empty;
    public string Frequency { get; set; } = string.Empty;
    public List<string> Synonyms { get; set; } = new();
    public string? Example { get; set; }
    public string? ExampleTranslation { get; set; }
}

public class IdiomDto
{
    public string Idiom { get; set; } = string.Empty;
    public string Translation { get; set; } = string.Empty;
    public string Definition { get; set; } = string.Empty;
    public string Pronunciation { get; set; } = string.Empty;
    public string DifficultyLevel { get; set; } = string.Empty;
    public string Frequency { get; set; } = string.Empty;
    public List<string> Synonyms { get; set; } = new();
    public string? Example { get; set; }
    public string? ExampleTranslation { get; set; }
}

public class GrammarCorrectionDto
{
    public bool HasErrors { get; set; }
    public string CorrectedText { get; set; } = string.Empty;
    public List<GrammarErrorDto> Corrections { get; set; } = new();
}

public class GrammarErrorDto
{
    public ErrorPosition Position { get; set; } = new();
    public string Error { get; set; } = string.Empty;
    public string Correction { get; set; } = string.Empty;
    public string Type { get; set; } = string.Empty;
    public string Explanation { get; set; } = string.Empty;
    public string Severity { get; set; } = "medium";
}
```

---

## 🔧 **服務層架構**

### **核心服務設計**

#### **IGeminiService介面**
```csharp
public interface IGeminiService
{
    Task<SentenceAnalysisData> AnalyzeSentenceAsync(string inputText, AnalysisOptions options);
    Task<bool> HealthCheckAsync();
    Task<string> GetModelVersionAsync();
}
```

#### **服務實現重點**
```csharp
public class GeminiService : IGeminiService
{
    private readonly HttpClient _httpClient;
    private readonly IOptions<GeminiOptions> _options;
    private readonly ILogger<GeminiService> _logger;

    // ✅ 強型別配置注入
    public GeminiService(HttpClient httpClient, IOptions<GeminiOptions> options, ILogger<GeminiService> logger)
    {
        _httpClient = httpClient;
        _options = options;
        _logger = logger;

        ConfigureHttpClient();
    }

    // ✅ 結構化錯誤處理
    public async Task<SentenceAnalysisData> AnalyzeSentenceAsync(string inputText, AnalysisOptions options)
    {
        try
        {
            var prompt = BuildPrompt(inputText, options);
            var aiResponse = await CallGeminiAPIWithRetry(prompt);
            return ParseResponse(inputText, aiResponse);
        }
        catch (HttpRequestException ex)
        {
            throw new AIServiceException("Gemini", "Network error", ex);
        }
        catch (JsonException ex)
        {
            throw new AIServiceException("Gemini", "Invalid response format", ex);
        }
    }
}
```

### **配置管理架構**

#### **強型別配置**
```csharp
public class GeminiOptions
{
    public const string SectionName = "Gemini";

    [Required]
    public string ApiKey { get; set; } = string.Empty;

    [Range(1, 120)]
    public int TimeoutSeconds { get; set; } = 30;

    [Range(1, 10)]
    public int MaxRetries { get; set; } = 3;

    public string Model { get; set; } = "gemini-1.5-flash";
    public double Temperature { get; set; } = 0.7;
    public int MaxOutputTokens { get; set; } = 2000;
}

// 配置驗證器
public class GeminiOptionsValidator : IValidateOptions<GeminiOptions>
{
    public ValidateOptionsResult Validate(string name, GeminiOptions options)
    {
        var failures = new List<string>();

        if (string.IsNullOrWhiteSpace(options.ApiKey))
            failures.Add("Gemini API key is required");

        if (!IsValidApiKey(options.ApiKey))
            failures.Add("Invalid Gemini API key format");

        return failures.Any()
            ? ValidateOptionsResult.Fail(failures)
            : ValidateOptionsResult.Success;
    }
}
```

---

## 🛡️ **錯誤處理與穩定性**

### **異常層次結構**
```csharp
public abstract class DramaLingException : Exception
{
    public string ErrorCode { get; }
    public Dictionary<string, object> Context { get; }

    protected DramaLingException(string errorCode, string message) : base(message)
    {
        ErrorCode = errorCode;
        Context = new Dictionary<string, object>();
    }
}

public class AIServiceException : DramaLingException
{
    public AIServiceException(string provider, string details)
        : base("AI_SERVICE_ERROR", $"AI service '{provider}' failed: {details}")
    {
        Context["Provider"] = provider;
        Context["Details"] = details;
    }
}

public class ValidationException : DramaLingException
{
    public ValidationException(string field, string message)
        : base("VALIDATION_ERROR", $"Validation failed for {field}: {message}")
    {
        Context["Field"] = field;
    }
}
```

### **錯誤回應標準**
```json
{
  "success": false,
  "error": {
    "code": "AI_SERVICE_ERROR",
    "message": "AI服務暫時不可用",
    "details": {
      "provider": "gemini",
      "originalError": "Network timeout"
    },
    "suggestions": [
      "請稍後重試",
      "如果問題持續，請聯繫客服"
    ]
  },
  "timestamp": "2025-01-25T10:30:00Z",
  "requestId": "uuid-string"
}
```

### **重試與熔斷機制**
```csharp
// 使用Polly實現重試策略
services.AddHttpClient<IGeminiService, GeminiService>()
    .AddPolicyHandler(GetRetryPolicy())
    .AddPolicyHandler(GetCircuitBreakerPolicy());

private static IAsyncPolicy<HttpResponseMessage> GetRetryPolicy()
{
    return HttpPolicyExtensions
        .HandleTransientHttpError()
        .WaitAndRetryAsync(
            retryCount: 3,
            sleepDurationProvider: retryAttempt =>
                TimeSpan.FromSeconds(Math.Pow(2, retryAttempt)),
            onRetry: (outcome, timespan, retryCount, context) =>
            {
                logger.LogWarning("Retry {RetryCount} after {Delay}ms",
                    retryCount, timespan.TotalMilliseconds);
            });
}
```

---

## 📊 **性能優化設計**

### **快取策略**
```yaml
多層快取架構:
  L1: 應用程序記憶體快取 (5分鐘)
  L2: Redis分散式快取 (1小時)
  L3: 資料庫持久快取 (24小時)

快取鍵設計:
  - 格式: "analysis:{hash(inputText)}"
  - 過期: 基於內容複雜度動態調整
  - 清理: 背景服務定期清理過期快取

快取命中率目標: > 70%
```

### **資料庫優化**
```csharp
// 查詢優化範例
public async Task<AnalysisCache> GetCachedAnalysisAsync(string inputText)
{
    var textHash = ComputeHash(inputText);

    return await _context.AnalysisCache
        .AsNoTracking()  // 只讀查詢優化
        .Where(c => c.InputTextHash == textHash && c.ExpiresAt > DateTime.UtcNow)
        .Select(c => new AnalysisCache  // 投影查詢，只選需要的欄位
        {
            Id = c.Id,
            CachedData = c.CachedData,
            CreatedAt = c.CreatedAt
        })
        .FirstOrDefaultAsync();
}
```

---

## 🔒 **安全架構設計**

### **API安全**
```yaml
認證機制:
  - JWT Bearer Token認證
  - Token過期時間: 24小時
  - 刷新機制: Refresh Token

授權控制:
  - 角色基礎存取控制 (RBAC)
  - 資源級別權限
  - API速率限制

輸入驗證:
  - 參數類型檢查
  - 字符長度限制
  - XSS防護過濾
  - SQL注入防護
```

### **資料安全**
```yaml
傳輸安全:
  - TLS 1.3強制加密
  - HSTS標頭
  - 安全標頭 (CSP, X-Frame-Options)

存儲安全:
  - 敏感資料加密
  - API金鑰安全管理
  - 個人資料匿名化
  - 定期安全掃描
```

---

## 🧪 **測試策略**

### **測試金字塔**
```yaml
單元測試 (70%):
  - 服務邏輯測試
  - 配置驗證測試
  - 錯誤處理測試
  - Mock外部依賴

整合測試 (20%):
  - API端點測試
  - 資料庫整合測試
  - 快取系統測試
  - 健康檢查測試

E2E測試 (10%):
  - 完整分析流程測試
  - 真實AI API測試
  - 性能基準測試
  - 安全滲透測試
```

### **測試案例設計**
```csharp
[TestFixture]
public class AIAnalysisServiceTests
{
    [Test]
    public async Task AnalyzeAsync_WithValidInput_ReturnsAnalysisResult()
    {
        // Arrange
        var request = new AnalysisRequest { InputText = "She just joined the team." };

        // Act
        var result = await _service.AnalyzeAsync(request);

        // Assert
        Assert.That(result.VocabularyAnalysis.Count, Is.GreaterThan(0));
        Assert.That(result.SentenceMeaning, Is.Not.Empty);
    }

    [Test]
    public async Task AnalyzeAsync_WhenAIServiceFails_ThrowsAIServiceException()
    {
        // 測試AI服務故障時的錯誤處理
    }
}
```

---

## 📈 **監控與可觀測性**

### **日誌標準**
```csharp
// 結構化日誌擴展
public static class LoggerExtensions
{
    public static void LogAIRequest(this ILogger logger, string requestId,
        string inputText, string provider, double processingTime)
    {
        logger.LogInformation("AI Request: {RequestId} Provider: {Provider} " +
            "Length: {Length} Time: {Time}ms",
            requestId, provider, inputText.Length, processingTime);
    }
}
```

### **健康檢查**
```csharp
public class AIServiceHealthCheck : IHealthCheck
{
    public async Task<HealthCheckResult> CheckHealthAsync(HealthCheckContext context,
        CancellationToken cancellationToken = default)
    {
        var checks = new Dictionary<string, bool>
        {
            ["gemini_api"] = await CheckGeminiHealthAsync(),
            ["database"] = await CheckDatabaseHealthAsync(),
            ["cache"] = await CheckCacheHealthAsync()
        };

        var failedChecks = checks.Where(c => !c.Value).Select(c => c.Key).ToList();

        return failedChecks.Any()
            ? HealthCheckResult.Unhealthy($"Failed: {string.Join(", ", failedChecks)}")
            : HealthCheckResult.Healthy("All systems operational");
    }
}
```

### **性能指標**
```yaml
關鍵指標:
  - API回應時間分佈 (P50, P95, P99)
  - AI API調用成功率
  - 快取命中率
  - 記憶體和CPU使用率
  - 錯誤率和異常分佈

告警閾值:
  - 回應時間P95 > 5秒
  - 錯誤率 > 5%
  - AI API失敗率 > 10%
  - 記憶體使用 > 80%
```

---

## 🚀 **部署與配置**

### **環境配置**
```yaml
Development:
  - Database: SQLite
  - Cache: In-Memory
  - AI Provider: Gemini (測試Key)
  - Logging: Debug Level

Production:
  - Database: PostgreSQL (HA)
  - Cache: Redis Cluster
  - AI Provider: Gemini (生產Key)
  - Logging: Information Level
  - Monitoring: Application Insights
```

### **Docker配置**
```dockerfile
FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base
WORKDIR /app
EXPOSE 5008

FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY ["DramaLing.Api.csproj", "."]
RUN dotnet restore

COPY . .
RUN dotnet publish -c Release -o /app/publish

FROM base AS final
WORKDIR /app
COPY --from=build /app/publish .

HEALTHCHECK --interval=30s --timeout=3s \
  CMD curl -f http://localhost:5008/health || exit 1

ENTRYPOINT ["dotnet", "DramaLing.Api.dll"]
```

---

## 📋 **開發指導**

### **程式碼規範**
```yaml
命名規範:
  - 類別: PascalCase (UserService)
  - 方法: PascalCase (AnalyzeAsync)
  - 參數: camelCase (inputText)
  - 常數: UPPER_CASE (MAX_LENGTH)

註釋規範:
  - 公開API: 完整XML註釋
  - 複雜邏輯: 行內註釋解釋
  - 業務邏輯: 意圖說明註釋
  - TODO: 使用標準格式

錯誤處理:
  - 自訂異常類型
  - 結構化錯誤回應
  - 日誌記錄完整
  - 用戶友善訊息
```

### **API設計原則**
```yaml
RESTful設計:
  - 使用標準HTTP動詞
  - 資源導向URL設計
  - 狀態碼語義明確
  - 一致的回應格式

版本管理:
  - URL版本控制 (/api/v1/)
  - 向下相容保證
  - 淘汰策略明確
  - 版本變更文檔

安全實踐:
  - 最小權限原則
  - 輸入驗證完整
  - 輸出編碼安全
  - 審計日誌記錄
```

---

## 🔄 **變更管理**

### **API版本演進**
- **v1.0**: 基礎分析功能 (2025-01-20)
- **v1.1**: 移除userLevel，簡化API (2025-01-25)
- **v2.0**: 重構技術規格，標準化設計 (2025-01-25)

### **技術債務管理**
```yaml
已解決:
  - 硬編碼配置移除
  - 強型別配置實施
  - API規格標準化

待解決:
  - 重試機制實施
  - 健康檢查完善
  - 監控指標實施
  - 性能優化
```

---

**文件版本**: v2.0
**技術負責人**: DramaLing後端技術團隊
**最後更新**: 2025-01-25
**下次審查**: 2025-02-25

**關聯文件**:
- 《AI句子分析功能產品需求規格》- 業務需求和用戶故事
- 《系統整合與部署規格》- 整合和部署細節
- 《AI驅動產品後端技術架構指南》- 架構設計指導原則