# AI驅動產品後端技術架構指南

## 📋 **文件資訊**

- **文件名稱**: AI驅動產品後端技術架構指南
- **版本**: v1.0
- **建立日期**: 2025-01-25
- **最後更新**: 2025-01-25
- **負責團隊**: DramaLing技術架構團隊
- **適用產品**: AI驅動的語言學習、內容分析、智能推薦等產品

---

## 🎯 **架構設計原則**

### **核心設計理念**

#### **高效率 (High Performance)**
```yaml
響應速度:
  - API響應時間 < 500ms (不含AI處理)
  - AI處理時間 < 5秒
  - 資料庫查詢 < 100ms
  - 快取命中率 > 80%

並發處理:
  - 支援1000+併發請求
  - 優雅降級機制
  - 資源池化管理
  - 非同步處理優先
```

#### **好維護 (Maintainability)**
```yaml
程式碼品質:
  - 單一職責原則 (SRP)
  - 依賴注入 (DI)
  - 介面隔離 (ISP)
  - 開放封閉原則 (OCP)

文檔完整性:
  - API文檔自動生成
  - 程式碼註釋覆蓋率 > 60%
  - 架構決策記錄 (ADR)
  - 部署流程文檔化
```

#### **穩定性 (Stability)**
```yaml
錯誤處理:
  - 全局異常處理
  - 優雅降級策略
  - 重試機制設計
  - 斷路器模式

監控告警:
  - 健康檢查端點
  - 關鍵指標監控
  - 自動告警機制
  - 日誌追蹤完整
```

---

## 🏗️ **分層架構設計**

### **整體架構圖**

```
┌─────────────────────────────────────────────────────────────┐
│                        🌐 API Gateway                        │
│                    (Authentication, Rate Limiting)           │
└─────────────────────┬───────────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────────┐
│                   📡 Controllers Layer                       │
│              (Request Handling, Validation)                  │
└─────────────────────┬───────────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────────┐
│                   🔧 Services Layer                         │
│              (Business Logic, AI Integration)                │
└─────────────────────┬───────────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────────┐
│                   💾 Data Access Layer                      │
│              (Repository Pattern, EF Core)                   │
└─────────────────────┬───────────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────────┐
│                   🗄️ Data Storage Layer                     │
│            (Database, Cache, External APIs)                  │
└─────────────────────────────────────────────────────────────┘
```

### **分層職責定義**

#### **1. Controllers Layer (控制器層)**
**職責**: 處理HTTP請求、參數驗證、回應格式化
```csharp
[ApiController]
[Route("api/[controller]")]
public class AIController : ControllerBase
{
    private readonly IAIAnalysisService _aiService;
    private readonly ILogger<AIController> _logger;

    // ✅ 好的實踐：單一職責，只處理HTTP層邏輯
    [HttpPost("analyze")]
    public async Task<ActionResult<AnalysisResponse>> Analyze(
        [FromBody] AnalysisRequest request)
    {
        // 1. 輸入驗證
        if (!ModelState.IsValid)
            return BadRequest(ModelState);

        // 2. 委派給服務層
        var result = await _aiService.AnalyzeAsync(request);

        // 3. 格式化回應
        return Ok(result);
    }
}
```

#### **2. Services Layer (服務層)**
**職責**: 業務邏輯實現、AI服務整合、快取策略
```csharp
public interface IAIAnalysisService
{
    Task<AnalysisResult> AnalyzeAsync(AnalysisRequest request);
}

public class AIAnalysisService : IAIAnalysisService
{
    private readonly IGeminiService _geminiService;
    private readonly ICacheService _cacheService;
    private readonly IAnalysisRepository _repository;

    // ✅ 好的實踐：依賴注入，介面隔離
    public async Task<AnalysisResult> AnalyzeAsync(AnalysisRequest request)
    {
        // 1. 快取檢查
        var cached = await _cacheService.GetAsync(request.InputText);
        if (cached != null) return cached;

        // 2. AI服務調用
        var aiResult = await _geminiService.AnalyzeAsync(request.InputText);

        // 3. 業務邏輯處理
        var processedResult = ProcessAIResult(aiResult, request);

        // 4. 快取存儲
        await _cacheService.SetAsync(request.InputText, processedResult);

        // 5. 持久化
        await _repository.SaveAnalysisAsync(processedResult);

        return processedResult;
    }
}
```

#### **3. Data Access Layer (資料存取層)**
**職責**: 資料庫操作、查詢優化、事務管理
```csharp
public interface IAnalysisRepository
{
    Task<AnalysisResult?> GetCachedAnalysisAsync(string inputHash);
    Task SaveAnalysisAsync(AnalysisResult result);
    Task<IEnumerable<AnalysisStats>> GetUsageStatsAsync(DateTime from, DateTime to);
}

public class AnalysisRepository : IAnalysisRepository
{
    private readonly DramaLingDbContext _context;

    // ✅ 好的實踐：Repository模式，查詢優化
    public async Task<AnalysisResult?> GetCachedAnalysisAsync(string inputHash)
    {
        return await _context.AnalysisCache
            .AsNoTracking()  // 性能優化：只讀查詢
            .Where(a => a.InputHash == inputHash && a.ExpiresAt > DateTime.UtcNow)
            .Select(a => new AnalysisResult  // 投影查詢：只選需要的欄位
            {
                Data = a.CachedData,
                CreatedAt = a.CreatedAt
            })
            .FirstOrDefaultAsync();
    }
}
```

---

## 🤖 **AI整合架構模式**

### **AI服務抽象層設計**

#### **多AI提供商支援架構**
```csharp
// ✅ 策略模式：支援多個AI提供商
public interface IAIProvider
{
    string ProviderName { get; }
    Task<AIResponse> AnalyzeAsync(AIRequest request);
    bool IsAvailable { get; }
    decimal CostPerRequest { get; }
}

public class GeminiProvider : IAIProvider
{
    public string ProviderName => "Google Gemini";

    public async Task<AIResponse> AnalyzeAsync(AIRequest request)
    {
        // Gemini特定實現
    }
}

public class OpenAIProvider : IAIProvider
{
    public string ProviderName => "OpenAI GPT";

    public async Task<AIResponse> AnalyzeAsync(AIRequest request)
    {
        // OpenAI特定實現
    }
}

// AI提供商選擇器
public class AIProviderSelector
{
    private readonly IEnumerable<IAIProvider> _providers;

    public IAIProvider SelectBestProvider(AIRequest request)
    {
        // 基於成本、可用性、性能選擇最佳提供商
        return _providers
            .Where(p => p.IsAvailable)
            .OrderBy(p => p.CostPerRequest)
            .First();
    }
}
```

### **AI請求優化模式**

#### **智能批次處理**
```csharp
public class BatchAIProcessor
{
    private readonly Queue<AIRequest> _requestQueue = new();
    private readonly Timer _batchTimer;

    public async Task<AIResponse> ProcessAsync(AIRequest request)
    {
        // ✅ 批次處理：提高AI API效率
        _requestQueue.Enqueue(request);

        if (_requestQueue.Count >= BatchSize || IsTimeoutReached())
        {
            await ProcessBatchAsync();
        }

        return await GetResultAsync(request.Id);
    }

    private async Task ProcessBatchAsync()
    {
        var batch = DrainQueue();
        var batchPrompt = CombineRequests(batch);
        var response = await _aiProvider.AnalyzeAsync(batchPrompt);
        var results = SplitResponse(response, batch);

        // 分發結果給等待的請求
        foreach (var result in results)
        {
            _resultStore.SetResult(result.RequestId, result);
        }
    }
}
```

#### **智能快取策略**
```csharp
public class IntelligentCacheService
{
    private readonly IMemoryCache _memoryCache;
    private readonly IDistributedCache _distributedCache;
    private readonly IDatabase _database;

    // ✅ 多層快取：記憶體 → Redis → 資料庫
    public async Task<T?> GetAsync<T>(string key) where T : class
    {
        // L1: 記憶體快取 (最快)
        if (_memoryCache.TryGetValue(key, out T? memoryResult))
            return memoryResult;

        // L2: 分散式快取 (Redis)
        var distributedResult = await _distributedCache.GetStringAsync(key);
        if (distributedResult != null)
        {
            var result = JsonSerializer.Deserialize<T>(distributedResult);
            _memoryCache.Set(key, result, TimeSpan.FromMinutes(5));
            return result;
        }

        // L3: 資料庫快取 (持久化)
        var dbResult = await GetFromDatabaseAsync<T>(key);
        if (dbResult != null)
        {
            await SetMultiLevelCacheAsync(key, dbResult);
            return dbResult;
        }

        return null;
    }

    // 智能過期策略
    public async Task SetAsync<T>(string key, T value, TimeSpan? expiry = null)
    {
        var smartExpiry = CalculateSmartExpiry(key, value);

        // 同時更新多層快取
        _memoryCache.Set(key, value, smartExpiry);
        await _distributedCache.SetStringAsync(key, JsonSerializer.Serialize(value),
            new DistributedCacheEntryOptions { SlidingExpiration = smartExpiry });
        await SaveToDatabaseAsync(key, value, smartExpiry);
    }
}
```

---

## 🔧 **程式碼組織結構**

### **專案結構範本**

```
DramaLing.Api/
├── 📁 Controllers/          # API控制器
│   ├── AIController.cs      # AI分析相關端點
│   ├── AuthController.cs    # 認證相關端點
│   └── BaseController.cs    # 共用控制器基類
├── 📁 Services/             # 業務服務層
│   ├── AI/                  # AI相關服務
│   │   ├── IGeminiService.cs
│   │   ├── GeminiService.cs
│   │   ├── IPromptBuilder.cs
│   │   └── PromptBuilder.cs
│   ├── Cache/               # 快取服務
│   │   ├── ICacheService.cs
│   │   ├── MemoryCacheService.cs
│   │   └── RedisCacheService.cs
│   └── Core/                # 核心業務服務
│       ├── IAnalysisService.cs
│       └── AnalysisService.cs
├── 📁 Models/               # 資料模型
│   ├── Entities/            # 資料庫實體
│   ├── DTOs/               # 資料傳輸對象
│   └── Requests/           # API請求模型
├── 📁 Data/                # 資料存取層
│   ├── DbContext.cs        # EF Core上下文
│   ├── Repositories/       # Repository實現
│   └── Migrations/         # 資料庫遷移
├── 📁 Infrastructure/      # 基礎設施
│   ├── Middleware/         # 中介軟體
│   ├── Filters/           # 過濾器
│   ├── Extensions/        # 擴展方法
│   └── Configuration/     # 配置管理
├── 📁 Utils/              # 工具類
│   ├── Helpers/           # 輔助函數
│   ├── Constants/         # 常數定義
│   └── Validators/        # 驗證器
└── Program.cs             # 應用程式入口
```

### **依賴注入最佳實踐**

#### **服務註冊配置**
```csharp
// Program.cs
public static void Main(string[] args)
{
    var builder = WebApplication.CreateBuilder(args);

    // ✅ 分層註冊：按類型組織
    RegisterControllers(builder);
    RegisterBusinessServices(builder);
    RegisterDataServices(builder);
    RegisterInfrastructureServices(builder);
    RegisterAIServices(builder);

    var app = builder.Build();
    ConfigureMiddleware(app);
    app.Run();
}

// 業務服務註冊
private static void RegisterBusinessServices(WebApplicationBuilder builder)
{
    builder.Services.AddScoped<IAnalysisService, AnalysisService>();
    builder.Services.AddScoped<IUserService, UserService>();
    builder.Services.AddScoped<IFlashcardService, FlashcardService>();
}

// AI服務註冊
private static void RegisterAIServices(WebApplicationBuilder builder)
{
    // ✅ 工廠模式：支援多AI提供商
    builder.Services.AddSingleton<IAIProviderFactory, AIProviderFactory>();
    builder.Services.AddScoped<IGeminiService, GeminiService>();
    builder.Services.AddScoped<IPromptBuilder, PromptBuilder>();

    // ✅ 配置模式：強型別配置
    builder.Services.Configure<GeminiOptions>(
        builder.Configuration.GetSection("Gemini"));

    // ✅ HttpClient工廠：連接池管理
    builder.Services.AddHttpClient<IGeminiService, GeminiService>(client =>
    {
        client.Timeout = TimeSpan.FromSeconds(30);
        client.DefaultRequestHeaders.Add("User-Agent", "DramaLing/1.0");
    });
}
```

---

## 🚀 **性能優化策略**

### **資料庫性能優化**

#### **Entity Framework最佳實踐**
```csharp
public class OptimizedAnalysisRepository : IAnalysisRepository
{
    private readonly DramaLingDbContext _context;

    // ✅ 查詢優化：AsNoTracking + 投影
    public async Task<IEnumerable<AnalysisDto>> GetRecentAnalysesAsync(int userId, int count)
    {
        return await _context.Analyses
            .AsNoTracking()  // 關閉變更追蹤：提升查詢性能
            .Where(a => a.UserId == userId)
            .OrderByDescending(a => a.CreatedAt)
            .Take(count)
            .Select(a => new AnalysisDto  // 投影查詢：只查詢需要的欄位
            {
                Id = a.Id,
                InputText = a.InputText,
                CreatedAt = a.CreatedAt,
                Summary = a.Summary
            })
            .ToListAsync();
    }

    // ✅ 批次操作：減少資料庫往返
    public async Task SaveMultipleAnalysesAsync(IEnumerable<Analysis> analyses)
    {
        _context.Analyses.AddRange(analyses);  // 批次新增
        await _context.SaveChangesAsync();    // 單次提交
    }

    // ✅ 連接分離：讀寫分離
    public async Task<AnalysisStats> GetAnalysisStatsAsync(int userId)
    {
        using var readOnlyContext = CreateReadOnlyContext();
        return await readOnlyContext.Analyses
            .Where(a => a.UserId == userId)
            .GroupBy(a => a.UserId)
            .Select(g => new AnalysisStats
            {
                TotalCount = g.Count(),
                LastAnalysisDate = g.Max(a => a.CreatedAt)
            })
            .FirstOrDefaultAsync();
    }
}
```

### **AI服務性能優化**

#### **請求合併與批次處理**
```csharp
public class OptimizedAIService : IAIAnalysisService
{
    private readonly IBatchProcessor<AIRequest, AIResponse> _batchProcessor;
    private readonly ICircuitBreaker _circuitBreaker;

    // ✅ 請求合併：減少AI API調用次數
    public async Task<AnalysisResult> AnalyzeAsync(AnalysisRequest request)
    {
        var aiRequest = new AIRequest
        {
            Id = Guid.NewGuid(),
            InputText = request.InputText,
            Timestamp = DateTime.UtcNow
        };

        // 批次處理：自動合併相近時間的請求
        var aiResponse = await _batchProcessor.ProcessAsync(aiRequest);

        return TransformToAnalysisResult(aiResponse);
    }

    // ✅ 斷路器模式：防止AI服務故障影響整體系統
    public async Task<AIResponse> CallAIWithCircuitBreakerAsync(AIRequest request)
    {
        return await _circuitBreaker.ExecuteAsync(async () =>
        {
            var response = await _aiProvider.CallAsync(request);

            if (!response.IsSuccessful)
                throw new AIServiceException(response.ErrorMessage);

            return response;
        });
    }
}
```

### **快取優化策略**

#### **多層快取架構**
```csharp
public class HybridCacheService : ICacheService
{
    private readonly IMemoryCache _l1Cache;      // L1: 程序內快取
    private readonly IDistributedCache _l2Cache; // L2: Redis分散式快取
    private readonly ICacheRepository _l3Cache;  // L3: 資料庫快取

    // ✅ 智能快取：根據數據特性選擇策略
    public async Task<T?> GetAsync<T>(string key) where T : class
    {
        var cacheStrategy = DetermineCacheStrategy<T>();

        return cacheStrategy switch
        {
            CacheStrategy.Fast => await GetFromL1Async<T>(key),
            CacheStrategy.Distributed => await GetFromL2Async<T>(key),
            CacheStrategy.Persistent => await GetFromL3Async<T>(key),
            _ => await GetFromMultiLevelAsync<T>(key)
        };
    }

    // 智能過期策略
    private TimeSpan CalculateExpiry(string key, object value)
    {
        return key switch
        {
            var k when k.StartsWith("analysis:") => TimeSpan.FromHours(24),
            var k when k.StartsWith("user:") => TimeSpan.FromMinutes(30),
            var k when k.StartsWith("stats:") => TimeSpan.FromMinutes(5),
            _ => TimeSpan.FromMinutes(15)
        };
    }

    // ✅ 快取預熱：提前載入熱點資料
    public async Task WarmupCacheAsync()
    {
        var hotData = await _repository.GetHotDataAsync();
        var tasks = hotData.Select(data =>
            SetAsync($"warmup:{data.Id}", data, TimeSpan.FromHours(1)));

        await Task.WhenAll(tasks);
    }
}
```

---

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

### **全局異常處理中介軟體**

```csharp
public class GlobalExceptionHandlingMiddleware
{
    private readonly RequestDelegate _next;
    private readonly ILogger<GlobalExceptionHandlingMiddleware> _logger;

    public async Task InvokeAsync(HttpContext context)
    {
        try
        {
            await _next(context);
        }
        catch (Exception ex)
        {
            await HandleExceptionAsync(context, ex);
        }
    }

    // ✅ 結構化錯誤處理：不同異常類型對應不同處理策略
    private async Task HandleExceptionAsync(HttpContext context, Exception exception)
    {
        var response = exception switch
        {
            ValidationException validationEx => CreateValidationErrorResponse(validationEx),
            AIServiceException aiEx => CreateAIServiceErrorResponse(aiEx),
            DatabaseException dbEx => CreateDatabaseErrorResponse(dbEx),
            UnauthorizedAccessException authEx => CreateUnauthorizedResponse(authEx),
            _ => CreateGenericErrorResponse(exception)
        };

        // 記錄錯誤日誌
        _logger.LogError(exception, "Request failed: {Method} {Path}",
            context.Request.Method, context.Request.Path);

        // 返回結構化錯誤回應
        context.Response.StatusCode = response.StatusCode;
        context.Response.ContentType = "application/json";
        await context.Response.WriteAsync(JsonSerializer.Serialize(response));
    }
}
```

### **重試與斷路器模式**

```csharp
public class ResilientAIService : IAIAnalysisService
{
    private readonly IAIProvider _primaryProvider;
    private readonly IAIProvider _fallbackProvider;
    private readonly ICircuitBreaker _circuitBreaker;

    // ✅ 重試機制：指數退避
    public async Task<AIResponse> CallWithRetryAsync(AIRequest request)
    {
        var retryPolicy = Policy
            .Handle<AIServiceException>()
            .Or<HttpRequestException>()
            .WaitAndRetryAsync(
                retryCount: 3,
                sleepDurationProvider: retryAttempt =>
                    TimeSpan.FromSeconds(Math.Pow(2, retryAttempt)), // 指數退避：2^n秒
                onRetry: (outcome, timespan, retryCount, context) =>
                {
                    _logger.LogWarning("AI service retry {RetryCount} after {Delay}ms",
                        retryCount, timespan.TotalMilliseconds);
                });

        return await retryPolicy.ExecuteAsync(async () =>
        {
            return await _circuitBreaker.ExecuteAsync(async () =>
            {
                try
                {
                    return await _primaryProvider.AnalyzeAsync(request);
                }
                catch (AIServiceException)
                {
                    // ✅ 降級策略：使用備用提供商
                    _logger.LogWarning("Primary AI provider failed, using fallback");
                    return await _fallbackProvider.AnalyzeAsync(request);
                }
            });
        });
    }
}
```

---

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

### **結構化日誌設計**

#### **日誌標準化**
```csharp
public static class LoggerExtensions
{
    // ✅ 結構化日誌：便於查詢和分析
    public static void LogAIRequest(this ILogger logger, string requestId,
        string inputText, string provider, double processingTime)
    {
        logger.LogInformation("AI Request Completed: {RequestId} Provider: {Provider} " +
            "InputLength: {InputLength} ProcessingTime: {ProcessingTime}ms",
            requestId, provider, inputText.Length, processingTime);
    }

    public static void LogBusinessOperation(this ILogger logger, string operation,
        string userId, bool success, Dictionary<string, object>? additionalData = null)
    {
        using var scope = logger.BeginScope(new Dictionary<string, object>
        {
            ["Operation"] = operation,
            ["UserId"] = userId,
            ["Success"] = success,
            ["Timestamp"] = DateTime.UtcNow,
            ["AdditionalData"] = additionalData ?? new Dictionary<string, object>()
        });

        if (success)
            logger.LogInformation("Business operation completed successfully");
        else
            logger.LogWarning("Business operation failed");
    }
}
```

### **健康檢查系統**

```csharp
public class AIServiceHealthCheck : IHealthCheck
{
    private readonly IGeminiService _geminiService;
    private readonly ICacheService _cacheService;
    private readonly DramaLingDbContext _dbContext;

    // ✅ 全面健康檢查：AI服務、快取、資料庫
    public async Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context, CancellationToken cancellationToken = default)
    {
        var checks = new List<(string Name, Task<bool> Check)>
        {
            ("Gemini API", CheckGeminiHealthAsync()),
            ("Cache Service", CheckCacheHealthAsync()),
            ("Database", CheckDatabaseHealthAsync()),
            ("Memory Usage", CheckMemoryUsageAsync())
        };

        var results = await Task.WhenAll(checks.Select(async check =>
        {
            try
            {
                var isHealthy = await check.Check;
                return (check.Name, IsHealthy: isHealthy, Error: (string?)null);
            }
            catch (Exception ex)
            {
                return (check.Name, IsHealthy: false, Error: ex.Message);
            }
        }));

        var failedChecks = results.Where(r => !r.IsHealthy).ToList();

        if (failedChecks.Any())
        {
            var errors = string.Join(", ", failedChecks.Select(f => $"{f.Name}: {f.Error}"));
            return HealthCheckResult.Unhealthy($"Failed checks: {errors}");
        }

        return HealthCheckResult.Healthy("All systems operational");
    }
}
```

---

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

### **多層安全防護**

#### **API安全中介軟體**
```csharp
public class SecurityMiddleware
{
    private readonly RequestDelegate _next;
    private readonly ILogger<SecurityMiddleware> _logger;

    public async Task InvokeAsync(HttpContext context)
    {
        // ✅ 輸入驗證：防止注入攻擊
        if (!await ValidateInputSafetyAsync(context))
        {
            context.Response.StatusCode = 400;
            await context.Response.WriteAsync("Invalid input detected");
            return;
        }

        // ✅ 速率限制：防止濫用
        if (!await CheckRateLimitAsync(context))
        {
            context.Response.StatusCode = 429;
            await context.Response.WriteAsync("Rate limit exceeded");
            return;
        }

        // ✅ 請求追蹤：安全稽核
        var requestId = Guid.NewGuid().ToString();
        context.Items["RequestId"] = requestId;

        using var scope = _logger.BeginScope(new Dictionary<string, object>
        {
            ["RequestId"] = requestId,
            ["UserId"] = context.User?.Identity?.Name ?? "Anonymous",
            ["IPAddress"] = context.Connection.RemoteIpAddress?.ToString(),
            ["UserAgent"] = context.Request.Headers["User-Agent"].ToString()
        });

        await _next(context);
    }

    private async Task<bool> ValidateInputSafetyAsync(HttpContext context)
    {
        // 檢查惡意模式
        var suspiciousPatterns = new[]
        {
            @"<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>",  // XSS
            @"(\bUNION\b|\bSELECT\b|\bINSERT\b|\bDELETE\b)",      // SQL注入
            @"(javascript:|data:|vbscript:)",                       // 協議注入
        };

        var body = await ReadRequestBodyAsync(context);
        return !suspiciousPatterns.Any(pattern =>
            Regex.IsMatch(body, pattern, RegexOptions.IgnoreCase));
    }
}
```

### **API金鑰管理**

#### **安全配置管理**
```csharp
public class SecureConfigurationService
{
    private readonly IConfiguration _configuration;
    private readonly IKeyVault _keyVault;  // Azure Key Vault 或 AWS Secrets Manager

    // ✅ 多層金鑰管理：環境變數 > Key Vault > 配置檔案
    public async Task<string> GetAPIKeyAsync(string serviceName)
    {
        // 優先級1: 環境變數（容器化部署）
        var envKey = Environment.GetEnvironmentVariable($"{serviceName.ToUpper()}_API_KEY");
        if (!string.IsNullOrEmpty(envKey))
            return envKey;

        // 優先級2: Key Vault（生產環境）
        if (_keyVault != null)
        {
            var vaultKey = await _keyVault.GetSecretAsync($"{serviceName}-api-key");
            if (!string.IsNullOrEmpty(vaultKey))
                return vaultKey;
        }

        // 優先級3: 配置檔案（開發環境）
        var configKey = _configuration[$"ApiKeys:{serviceName}"];
        if (!string.IsNullOrEmpty(configKey))
            return configKey;

        throw new InvalidOperationException($"API key for {serviceName} not found");
    }

    // ✅ 金鑰輪換：定期更新API金鑰
    public async Task RotateAPIKeyAsync(string serviceName)
    {
        var newKey = await GenerateNewKeyAsync(serviceName);
        await _keyVault.SetSecretAsync($"{serviceName}-api-key", newKey);

        // 通知相關服務更新金鑰
        await NotifyKeyRotationAsync(serviceName, newKey);
    }
}
```

---

## 📈 **可擴展性設計**

### **微服務準備架構**

#### **服務邊界定義**
```csharp
// ✅ 領域驅動設計：按業務領域劃分服務
namespace DramaLing.AI.Domain
{
    // AI分析聚合根
    public class AnalysisAggregate
    {
        public AnalysisId Id { get; private set; }
        public string InputText { get; private set; }
        public AnalysisResult Result { get; private set; }
        public AnalysisStatus Status { get; private set; }

        // 業務邏輯封裝在聚合內
        public void MarkAsCompleted(AnalysisResult result)
        {
            if (Status != AnalysisStatus.Processing)
                throw new InvalidOperationException("Analysis is not in processing state");

            Result = result;
            Status = AnalysisStatus.Completed;

            // 發布領域事件
            AddDomainEvent(new AnalysisCompletedEvent(Id, result));
        }
    }
}

// 服務介面定義
public interface IAIAnalysisDomainService
{
    Task<AnalysisAggregate> StartAnalysisAsync(string inputText);
    Task CompleteAnalysisAsync(AnalysisId id, AnalysisResult result);
}
```

#### **事件驅動架構**
```csharp
public class EventDrivenAIService
{
    private readonly IEventBus _eventBus;
    private readonly IAIProvider _aiProvider;

    // ✅ 事件驅動：解耦業務流程
    public async Task<AnalysisResult> ProcessAnalysisAsync(AnalysisRequest request)
    {
        // 1. 發布分析開始事件
        await _eventBus.PublishAsync(new AnalysisStartedEvent
        {
            RequestId = request.Id,
            InputText = request.InputText,
            Timestamp = DateTime.UtcNow
        });

        try
        {
            // 2. 執行AI分析
            var result = await _aiProvider.AnalyzeAsync(request);

            // 3. 發布分析完成事件
            await _eventBus.PublishAsync(new AnalysisCompletedEvent
            {
                RequestId = request.Id,
                Result = result,
                ProcessingTime = result.ProcessingTime
            });

            return result;
        }
        catch (Exception ex)
        {
            // 4. 發布分析失敗事件
            await _eventBus.PublishAsync(new AnalysisFailedEvent
            {
                RequestId = request.Id,
                Error = ex.Message,
                Timestamp = DateTime.UtcNow
            });

            throw;
        }
    }
}

// 事件處理器
public class AnalysisEventHandler :
    IEventHandler<AnalysisCompletedEvent>,
    IEventHandler<AnalysisFailedEvent>
{
    public async Task HandleAsync(AnalysisCompletedEvent eventData)
    {
        // 更新統計資料、發送通知、清理資源等
        await UpdateAnalysisStatsAsync(eventData);
        await NotifyUserAsync(eventData.RequestId, "分析完成");
    }

    public async Task HandleAsync(AnalysisFailedEvent eventData)
    {
        // 錯誤恢復、告警、重試邏輯等
        await LogFailureAsync(eventData);
        await TriggerRetryIfNecessaryAsync(eventData);
    }
}
```

---

## 🔧 **配置管理最佳實踐**

### **強型別配置**

```csharp
// ✅ 配置類別：型別安全的配置管理
public class AIServiceOptions
{
    public const string SectionName = "AIService";

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

    [Range(1, 300)]
    public int MaxInputLength { get; set; } = 300;

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

    public RetryOptions Retry { get; set; } = new();
    public CacheOptions Cache { get; set; } = new();
}

public class RetryOptions
{
    public int MaxAttempts { get; set; } = 3;
    public int BaseDelayMs { get; set; } = 1000;
    public bool UseExponentialBackoff { get; set; } = true;
}

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

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

        if (options.TimeoutSeconds <= 0)
            failures.Add("Timeout must be positive");

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

// 註冊配置
builder.Services.Configure<AIServiceOptions>(
    builder.Configuration.GetSection(AIServiceOptions.SectionName));
builder.Services.AddSingleton<IValidateOptions<AIServiceOptions>, AIServiceOptionsValidator>();
```

### **環境特定配置**

```csharp
// appsettings.Development.json
{
  "AIService": {
    "GeminiApiKey": "dev-key",
    "TimeoutSeconds": 10,
    "Cache": {
      "EnableDistributed": false,
      "DefaultExpiry": "00:05:00"
    }
  },
  "Logging": {
    "LogLevel": {
      "DramaLing.AI": "Debug"
    }
  }
}

// appsettings.Production.json
{
  "AIService": {
    "TimeoutSeconds": 30,
    "Cache": {
      "EnableDistributed": true,
      "DefaultExpiry": "01:00:00"
    }
  },
  "Logging": {
    "LogLevel": {
      "DramaLing.AI": "Information"
    }
  }
}
```

---

## 🧪 **測試架構設計**

### **測試金字塔實作**

#### **單元測試 (70%)**
```csharp
public class AIAnalysisServiceTests
{
    private readonly Mock<IGeminiService> _mockGeminiService;
    private readonly Mock<ICacheService> _mockCacheService;
    private readonly AIAnalysisService _service;

    // ✅ 純邏輯測試：快速、可靠、獨立
    [Test]
    public async Task AnalyzeAsync_WithCachedResult_ReturnsCachedData()
    {
        // Arrange
        var request = new AnalysisRequest { InputText = "test sentence" };
        var cachedResult = new AnalysisResult { /* ... */ };

        _mockCacheService.Setup(c => c.GetAsync<AnalysisResult>(It.IsAny<string>()))
            .ReturnsAsync(cachedResult);

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

        // Assert
        Assert.That(result, Is.EqualTo(cachedResult));
        _mockGeminiService.Verify(g => g.AnalyzeAsync(It.IsAny<string>()), Times.Never);
    }

    // ✅ 錯誤情境測試
    [Test]
    public async Task AnalyzeAsync_WhenAIServiceFails_ThrowsAIServiceException()
    {
        // Arrange
        _mockCacheService.Setup(c => c.GetAsync<AnalysisResult>(It.IsAny<string>()))
            .ReturnsAsync((AnalysisResult?)null);
        _mockGeminiService.Setup(g => g.AnalyzeAsync(It.IsAny<string>()))
            .ThrowsAsync(new HttpRequestException("API unavailable"));

        var request = new AnalysisRequest { InputText = "test sentence" };

        // Act & Assert
        Assert.ThrowsAsync<AIServiceException>(() => _service.AnalyzeAsync(request));
    }
}
```

#### **整合測試 (20%)**
```csharp
public class AIControllerIntegrationTests : IClassFixture<WebApplicationFactory<Program>>
{
    private readonly WebApplicationFactory<Program> _factory;
    private readonly HttpClient _client;

    // ✅ 真實環境測試：包含所有中介軟體和配置
    [Test]
    public async Task AnalyzeSentence_WithValidInput_ReturnsSuccessResponse()
    {
        // Arrange
        var request = new AnalysisRequest
        {
            InputText = "She just join the team",
            AnalysisMode = "full"
        };

        // Act
        var response = await _client.PostAsJsonAsync("/api/ai/analyze-sentence", request);

        // Assert
        response.EnsureSuccessStatusCode();
        var result = await response.Content.ReadFromJsonAsync<AnalysisResponse>();

        Assert.That(result.Success, Is.True);
        Assert.That(result.Data, Is.Not.Null);
        Assert.That(result.Data.VocabularyAnalysis, Is.Not.Empty);
    }
}
```

#### **E2E測試 (10%)**
```csharp
public class AIAnalysisE2ETests
{
    private readonly TestServer _server;
    private readonly HttpClient _client;

    // ✅ 端到端測試：包含真實的AI API調用
    [Test]
    [Category("E2E")]
    public async Task CompleteAnalysisWorkflow_WithRealAI_ProducesValidResults()
    {
        // 此測試使用真實的AI API，運行時間較長
        // 適合在CI/CD流程中定期執行

        var testSentences = new[]
        {
            "She just join the team, so let's cut her some slack.",
            "The implementation was challenging but rewarding.",
            "Could you please review the documentation?"
        };

        foreach (var sentence in testSentences)
        {
            var request = new AnalysisRequest { InputText = sentence };
            var response = await _client.PostAsJsonAsync("/api/ai/analyze-sentence", request);

            response.EnsureSuccessStatusCode();
            var result = await response.Content.ReadFromJsonAsync<AnalysisResponse>();

            // 驗證AI分析品質
            Assert.That(result.Data.VocabularyAnalysis.Count, Is.GreaterThan(0));
            Assert.That(result.Data.SentenceMeaning, Is.Not.Empty);

            // 驗證CEFR等級分配合理性
            Assert.That(result.Data.VocabularyAnalysis.Values
                .All(v => Enum.IsDefined(typeof(CEFRLevel), v.DifficultyLevel)), Is.True);
        }
    }
}
```

---

## 🔄 **部署與DevOps架構**

### **容器化配置**

#### **Dockerfile最佳實踐**
```dockerfile
# ✅ 多階段建置：減小鏡像大小
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src

# ✅ 快取優化：先複製專案檔案
COPY ["DramaLing.Api/DramaLing.Api.csproj", "DramaLing.Api/"]
COPY ["DramaLing.Core/DramaLing.Core.csproj", "DramaLing.Core/"]
RUN dotnet restore "DramaLing.Api/DramaLing.Api.csproj"

# 複製原始碼並建置
COPY . .
WORKDIR "/src/DramaLing.Api"
RUN dotnet build "DramaLing.Api.csproj" -c Release -o /app/build

# 發布應用程式
FROM build AS publish
RUN dotnet publish "DramaLing.Api.csproj" -c Release -o /app/publish --no-restore

# ✅ 執行階段：使用最小鏡像
FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS final
WORKDIR /app

# ✅ 安全設定：非root用戶
RUN adduser --disabled-password --gecos '' appuser && chown -R appuser /app
USER appuser

COPY --from=publish /app/publish .

# ✅ 健康檢查：容器監控
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD curl -f http://localhost:5000/health || exit 1

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

#### **Kubernetes部署配置**
```yaml
# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: dramaling-api
spec:
  replicas: 3  # ✅ 高可用：多實例部署
  strategy:
    type: RollingUpdate  # ✅ 零停機部署
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  template:
    spec:
      containers:
      - name: api
        image: dramaling/api:latest
        resources:  # ✅ 資源限制：防止資源爭用
          requests:
            memory: "256Mi"
            cpu: "250m"
          limits:
            memory: "512Mi"
            cpu: "500m"
        env:  # ✅ 外部化配置
        - name: ASPNETCORE_ENVIRONMENT
          value: "Production"
        - name: GEMINI_API_KEY
          valueFrom:
            secretKeyRef:
              name: ai-api-keys
              key: gemini-key
        livenessProbe:  # ✅ 自動恢復
          httpGet:
            path: /health
            port: 5000
          initialDelaySeconds: 30
          periodSeconds: 30
        readinessProbe:  # ✅ 流量控制
          httpGet:
            path: /health/ready
            port: 5000
          initialDelaySeconds: 5
          periodSeconds: 5
```

---

## 📊 **監控指標設計**

### **關鍵性能指標 (KPIs)**

#### **業務指標監控**
```csharp
public class BusinessMetricsService
{
    private readonly IMetricsCollector _metrics;

    // ✅ 業務指標：追蹤產品健康度
    public void RecordAnalysisMetrics(AnalysisResult result)
    {
        // AI分析成功率
        _metrics.Increment("ai.analysis.completed", new[]
        {
            new KeyValuePair<string, object>("provider", result.Provider),
            new KeyValuePair<string, object>("processing_time", result.ProcessingTime)
        });

        // 詞彙複雜度分布
        _metrics.Histogram("vocabulary.difficulty.distribution",
            result.VocabularyAnalysis.Values.Select(v => GetDifficultyScore(v.DifficultyLevel)));

        // 用戶參與度
        _metrics.Increment("user.engagement", new[]
        {
            new KeyValuePair<string, object>("feature", "ai_analysis"),
            new KeyValuePair<string, object>("session_id", result.SessionId)
        });
    }

    // ✅ 異常指標：快速發現問題
    public void RecordErrorMetrics(Exception exception, string operation)
    {
        _metrics.Increment("errors.total", new[]
        {
            new KeyValuePair<string, object>("operation", operation),
            new KeyValuePair<string, object>("error_type", exception.GetType().Name),
            new KeyValuePair<string, object>("severity", GetErrorSeverity(exception))
        });
    }
}
```

#### **技術指標監控**
```csharp
public class TechnicalMetricsMiddleware
{
    private readonly RequestDelegate _next;
    private readonly IMetricsCollector _metrics;

    public async Task InvokeAsync(HttpContext context)
    {
        var stopwatch = Stopwatch.StartNew();
        var path = context.Request.Path.Value;
        var method = context.Request.Method;

        try
        {
            await _next(context);
        }
        finally
        {
            stopwatch.Stop();

            // ✅ 請求指標：API性能監控
            _metrics.Histogram("http.request.duration", stopwatch.ElapsedMilliseconds, new[]
            {
                new KeyValuePair<string, object>("method", method),
                new KeyValuePair<string, object>("path", path),
                new KeyValuePair<string, object>("status_code", context.Response.StatusCode)
            });

            // 記憶體使用指標
            var memoryUsage = GC.GetTotalMemory(false);
            _metrics.Gauge("system.memory.usage", memoryUsage);

            // 資料庫連接池指標
            _metrics.Gauge("database.connection_pool.active",
                GetActiveConnectionCount());
        }
    }
}
```

---

## 📚 **程式碼品質標準**

### **編碼規範**

#### **命名規範**
```csharp
// ✅ 清晰的命名：表達意圖，而非實現
public class SentenceAnalysisService  // 而非 AIService
{
    // 方法命名：動詞 + 名詞，表達業務意圖
    public async Task<AnalysisResult> AnalyzeEnglishSentenceAsync(string sentence)
    {
        // 變數命名：有意義的業務術語
        var grammarCheckResult = await CheckGrammarAsync(sentence);
        var vocabularyAnalysis = await AnalyzeVocabularyAsync(sentence);
        var idiomDetection = await DetectIdiomsAsync(sentence);

        return BuildAnalysisResult(grammarCheckResult, vocabularyAnalysis, idiomDetection);
    }

    // ✅ 私有方法：體現實現細節
    private async Task<GrammarCheckResult> CheckGrammarAsync(string sentence)
    {
        var prompt = _promptBuilder.BuildGrammarCheckPrompt(sentence);
        var aiResponse = await _aiProvider.CallAsync(prompt);
        return _grammarParser.Parse(aiResponse);
    }
}
```

#### **錯誤處理規範**
```csharp
// ✅ 自訂異常：明確的錯誤分類
public abstract class DramaLingException : Exception
{
    public string ErrorCode { get; }
    public Dictionary<string, object> Context { get; }

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

public class AIServiceException : DramaLingException
{
    public AIServiceException(string provider, string aiErrorMessage,
        string? originalPrompt = null)
        : base("AI_SERVICE_ERROR", $"AI service '{provider}' failed: {aiErrorMessage}")
    {
        Context["Provider"] = provider;
        Context["AIErrorMessage"] = aiErrorMessage;
        if (originalPrompt != null)
            Context["OriginalPrompt"] = originalPrompt;
    }
}

// 使用範例
public async Task<AnalysisResult> AnalyzeAsync(string inputText)
{
    try
    {
        return await _aiProvider.AnalyzeAsync(inputText);
    }
    catch (HttpRequestException ex) when (ex.Message.Contains("timeout"))
    {
        throw new AIServiceException(_aiProvider.Name, "Request timeout", inputText);
    }
    catch (JsonException ex)
    {
        throw new AIServiceException(_aiProvider.Name, "Invalid response format", inputText);
    }
}
```

---

## 🔮 **未來擴展架構**

### **AI模型演進支援**

#### **模型版本管理**
```csharp
public class AIModelManager
{
    private readonly Dictionary<string, IAIProvider> _providers;
    private readonly IConfiguration _configuration;

    // ✅ 版本控制：支援AI模型A/B測試
    public async Task<AnalysisResult> AnalyzeWithVersionAsync(string inputText,
        string? modelVersion = null)
    {
        var version = modelVersion ?? GetDefaultModelVersion();
        var provider = GetProviderForVersion(version);

        var result = await provider.AnalyzeAsync(inputText);

        // 記錄模型性能
        await RecordModelPerformanceAsync(version, result);

        return result;
    }

    // ✅ 藍綠部署：無縫模型升級
    public async Task<bool> CanaryDeploymentAsync(string newModelVersion, double trafficPercentage)
    {
        var canaryProvider = GetProviderForVersion(newModelVersion);
        var testResults = await RunCanaryTestsAsync(canaryProvider);

        if (testResults.ErrorRate < 0.01 && testResults.PerformanceIndex > 0.95)
        {
            await GraduallyMigrateTrafficAsync(newModelVersion, trafficPercentage);
            return true;
        }

        return false;
    }
}
```

### **多租戶架構準備**

#### **租戶隔離設計**
```csharp
public class TenantContext
{
    public string TenantId { get; set; }
    public string DatabaseConnection { get; set; }
    public AIServiceConfiguration AIConfig { get; set; }
    public Dictionary<string, object> CustomSettings { get; set; }
}

public class MultiTenantAIService : IAIAnalysisService
{
    private readonly ITenantResolver _tenantResolver;
    private readonly IServiceProvider _serviceProvider;

    // ✅ 租戶隔離：每個租戶獨立配置
    public async Task<AnalysisResult> AnalyzeAsync(AnalysisRequest request)
    {
        var tenant = await _tenantResolver.GetCurrentTenantAsync();

        // 使用租戶特定的AI配置
        var aiProvider = _serviceProvider.GetKeyedService<IAIProvider>(tenant.AIConfig.Provider);

        // 使用租戶特定的提示詞範本
        var prompt = BuildTenantSpecificPrompt(request.InputText, tenant);

        return await aiProvider.AnalyzeAsync(prompt);
    }
}
```

---

## 📋 **實施檢查清單**

### **架構實施階段**

#### **Phase 1: 基礎架構 (第1-2週)**
- [ ] 建立分層架構基礎專案結構
- [ ] 實作依賴注入容器配置
- [ ] 建立基礎API控制器和中介軟體
- [ ] 設定Entity Framework和資料庫遷移
- [ ] 實作基本的健康檢查和日誌系統

#### **Phase 2: AI整合 (第3-4週)**
- [ ] 實作AI提供商抽象層
- [ ] 建立智能快取系統
- [ ] 實作Prompt管理和版本控制
- [ ] 建立錯誤處理和重試機制
- [ ] 設定監控指標和告警

#### **Phase 3: 優化與安全 (第5-6週)**
- [ ] 實作性能優化策略
- [ ] 建立全面的安全防護
- [ ] 完善測試套件 (單元/整合/E2E)
- [ ] 設定CI/CD流程
- [ ] 建立生產環境監控

### **品質檢查標準**

#### **程式碼品質**
```yaml
覆蓋率要求:
  - 單元測試覆蓋率: > 80%
  - 業務邏輯覆蓋率: > 90%
  - 關鍵路徑覆蓋率: 100%

性能基準:
  - API回應時間: P95 < 500ms
  - AI處理時間: P95 < 5s
  - 資料庫查詢: P95 < 100ms
  - 記憶體使用: < 500MB per instance

安全檢查:
  - 輸入驗證: 100%覆蓋
  - SQL注入防護: 已驗證
  - XSS防護: 已驗證
  - API金鑰安全: 已驗證
```

---

## 🎓 **最佳實踐總結**

### **核心原則**

1. **單一職責**: 每個類別、方法都有明確單一的職責
2. **依賴倒置**: 依賴抽象而非具體實現
3. **開放封閉**: 對擴展開放，對修改封閉
4. **介面隔離**: 客戶端不應依賴不需要的介面
5. **最小驚訝**: 程式碼行為符合直覺期望

### **AI特定最佳實踐**

1. **Prompt版本化**: 將Prompt當作程式碼管理
2. **多提供商支援**: 避免供應商鎖定
3. **智能快取**: 減少昂貴的AI API調用
4. **優雅降級**: AI服務故障時的備援策略
5. **成本監控**: 追蹤和優化AI API使用成本

### **維護性保證**

1. **文檔驅動**: 架構決策和變更都要記錄
2. **自動化測試**: 確保重構和擴展的安全性
3. **監控完整**: 從業務指標到技術指標全覆蓋
4. **配置外部化**: 所有環境特定配置都外部化
5. **日誌結構化**: 便於查詢、分析和告警

---

**文件版本**: v1.0
**技術架構**: .NET 8 + Entity Framework + AI整合
**最後更新**: 2025-01-25
**下次審查**: 2025-02-25

**參考實現**: DramaLing AI語言學習平台
**適用範圍**: 中小型AI驅動產品 (< 10萬用戶)