dramaling-vocab-learning/backend/DramaLing.Api/Configuration/README.md

# 配置管理說明

## 概述
DramaLing API 使用 ASP.NET Core 標準配置系統，支援多環境配置、環境變數覆蓋、強型別配置驗證。

## 配置文件結構

```
Configuration/
├── README.md                        # 本文檔
├── appsettings.json                 # 主要配置檔案
├── appsettings.Development.json     # 開發環境配置
├── appsettings.Production.json      # 生產環境配置 (未建立)
├── appsettings.OptionsVocabulary.json # 詞彙選項配置
└── [Models/Configuration/]          # 強型別配置類別
    ├── GeminiOptions.cs            # Gemini 配置
    └── GeminiOptionsValidator.cs   # Gemini 配置驗證器
```

## 環境變數優先級

配置來源優先級 (由高到低)：
1. **環境變數**
2. **appsettings.{Environment}.json**
3. **appsettings.json**
4. **預設值**

## 核心配置項目

### 資料庫連接
```json
{
  "ConnectionStrings": {
    "DefaultConnection": "Data Source=dramaling.db"
  }
}
```

**環境變數覆蓋**：
- `DRAMALING_DB_CONNECTION` - 資料庫連接字串
- `USE_INMEMORY_DB=true` - 使用記憶體資料庫

### Gemini AI 配置
```json
{
  "Gemini": {
    "ApiKey": "your-gemini-api-key",
    "Model": "gemini-1.5-flash",
    "BaseUrl": "https://generativelanguage.googleapis.com/v1beta/models/",
    "MaxTokens": 2048,
    "Temperature": 0.1,
    "TopP": 0.95,
    "TopK": 64,
    "Timeout": 30
  }
}
```

**環境變數覆蓋**：
- `DRAMALING_GEMINI_API_KEY` - Gemini API 金鑰
- `DRAMALING_GEMINI_MODEL` - 模型名稱

### Supabase 認證配置
```json
{
  "Supabase": {
    "Url": "https://your-project.supabase.co",
    "JwtSecret": "your-jwt-secret"
  }
}
```

**環境變數覆蓋**：
- `DRAMALING_SUPABASE_URL` - Supabase 專案 URL
- `DRAMALING_SUPABASE_JWT_SECRET` - JWT 密鑰

### Replicate 服務配置
```json
{
  "Replicate": {
    "ApiKey": "your-replicate-api-key",
    "BaseUrl": "https://api.replicate.com/v1/",
    "DefaultModel": "black-forest-labs/flux-schnell",
    "Timeout": 300
  }
}
```

**環境變數覆蓋**：
- `DRAMALING_REPLICATE_API_KEY` - Replicate API 金鑰

### Azure Speech 服務配置
```json
{
  "AzureSpeech": {
    "SubscriptionKey": "your-azure-speech-key",
    "Region": "eastus",
    "Language": "en-US",
    "Voice": "en-US-JennyNeural"
  }
}
```

**環境變數覆蓋**：
- `DRAMALING_AZURE_SPEECH_KEY` - Azure Speech 金鑰
- `DRAMALING_AZURE_SPEECH_REGION` - Azure Speech 區域

## 強型別配置

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

    public string ApiKey { get; set; } = string.Empty;
    public string Model { get; set; } = "gemini-1.5-flash";
    public string BaseUrl { get; set; } = "https://generativelanguage.googleapis.com/v1beta/models/";
    public int MaxTokens { get; set; } = 2048;
    public double Temperature { get; set; } = 0.1;
    public double TopP { get; set; } = 0.95;
    public int TopK { get; set; } = 64;
    public int Timeout { get; set; } = 30;
}
```

### 配置驗證
```csharp
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 (options.MaxTokens <= 0)
            failures.Add("MaxTokens must be greater than 0");

        return failures.Count > 0
            ? ValidateOptionsResult.Fail(failures)
            : ValidateOptionsResult.Success;
    }
}
```

## 配置註冊

在 `ServiceCollectionExtensions.cs` 中：

```csharp
public static IServiceCollection AddAIServices(this IServiceCollection services, IConfiguration configuration)
{
    // 強型別配置
    services.Configure<GeminiOptions>(configuration.GetSection(GeminiOptions.SectionName));
    services.AddSingleton<IValidateOptions<GeminiOptions>, GeminiOptionsValidator>();

    // 其他服務註冊...
    return services;
}
```

## 環境配置最佳實踐

### 開發環境 (appsettings.Development.json)
```json
{
  "Logging": {
    "LogLevel": {
      "Default": "Debug",
      "System": "Information",
      "Microsoft": "Information"
    }
  },
  "ConnectionStrings": {
    "DefaultConnection": "Data Source=dramaling_dev.db"
  }
}
```

### 生產環境配置原則
1. **敏感資料**: 全部使用環境變數
2. **連接逾時**: 增加逾時設定
3. **日誌等級**: 設為 Warning 或 Error
4. **快取設定**: 啟用分散式快取

### Docker Compose 環境變數
```yaml
version: '3.8'
services:
  dramaling-api:
    image: dramaling-api
    environment:
      - ASPNETCORE_ENVIRONMENT=Production
      - DRAMALING_DB_CONNECTION=Server=db;Database=dramaling;Uid=root;Pwd=password
      - DRAMALING_GEMINI_API_KEY=${GEMINI_API_KEY}
      - DRAMALING_SUPABASE_URL=${SUPABASE_URL}
      - DRAMALING_SUPABASE_JWT_SECRET=${SUPABASE_JWT_SECRET}
      - DRAMALING_REPLICATE_API_KEY=${REPLICATE_API_KEY}
```

## 配置安全性

### 敏感資料保護
1. **永不提交**: 敏感配置不可提交到版本控制
2. **環境變數**: 生產環境使用環境變數
3. **Azure Key Vault**: 考慮使用 Azure Key Vault
4. **加密**: 敏感配置在傳輸和儲存時加密

### .gitignore 設定
```
# 敏感配置文件
appsettings.Production.json
appsettings.*.local.json
*.secrets.json

# 環境變數文件
.env
.env.local
.env.production
```

## 配置驗證

### 啟動時驗證
```csharp
public static void Main(string[] args)
{
    var builder = WebApplication.CreateBuilder(args);

    // 配置驗證
    builder.Services.AddOptions<GeminiOptions>()
           .Bind(builder.Configuration.GetSection(GeminiOptions.SectionName))
           .ValidateDataAnnotations()
           .ValidateOnStart();

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

### 健康檢查整合
```csharp
builder.Services.AddHealthChecks()
                .AddCheck<ConfigurationHealthCheck>("configuration");
```

## 故障排除

### 常見問題
1. **配置未載入**: 檢查檔案名稱和環境變數
2. **環境變數無效**: 確認變數名稱正確
3. **強型別配置失敗**: 檢查配置驗證器

### 偵錯配置
```csharp
// 在 Program.cs 中加入偵錯輸出
var configuration = builder.Configuration;
Console.WriteLine($"Environment: {builder.Environment.EnvironmentName}");
Console.WriteLine($"Gemini API Key: {configuration["Gemini:ApiKey"]}");
```

---

**版本**: 1.0
**建立日期**: 2025-09-30
**維護者**: DramaLing 開發團隊