# 例句圖生成功能產品需求規格書 (PRD)

## 1. 功能概述

### 1.1 產品目標
為 DramaLing 詞彙學習平台開發智能例句圖生成功能，通過視覺化例句提升用戶學習效果和記憶保留率。

### 1.2 核心價值主張
- **視覺記憶增強**：圖像結合文字，提高記憶效果 40-60%
- **學習體驗優化**：直觀的視覺內容降低理解門檻
- **個性化學習**：根據用戶程度和偏好生成適配內容
- **成本效益平衡**：智能緩存和批量處理控制 AI 生成成本

### 1.3 目標用戶
- **主要用戶**：英語學習者（A1-C2 所有等級）
- **使用場景**：詞卡複習、新詞學習、例句理解
- **預期效果**：提升學習效率 30%，延長學習時間 25%

## 2. 系統架構設計

### 2.1 雙環境架構策略

#### 2.1.1 開發環境 (Development)
```
本地圖片儲存架構
├── wwwroot/images/examples/     # 靜態圖片存放
├── LocalImageStorageService     # 本地檔案管理
├── 快速測試與迭代             # 零雲端成本
└── 完整功能驗證               # 生產前測試
```

#### 2.1.2 生產環境 (Production)
```
雲端圖片儲存架構
├── AWS S3 / Azure Blob         # 雲端圖片儲存
├── CDN 加速分發               # 全球訪問優化
├── 自動備份與容災             # 數據安全保障
└── 彈性擴展與監控             # 效能管理
```

### 2.2 核心系統元件

#### 2.2.1 圖片生成引擎
- **AI 圖片生成服務** (DALL-E 3 / Midjourney API)
- **圖片品質檢測**：自動過濾不當或低品質內容
- **批量處理佇列**：非同步處理大量生成請求
- **生成參數優化**：根據學習等級調整圖片風格

#### 2.2.2 智能快取系統
- **語意快取**：類似例句共享相同圖片
- **多層快取策略**：記憶體 → 資料庫 → 檔案系統
- **快取失效機制**：基於使用頻率和時間的清理
- **預生成策略**：熱門詞彙預先生成圖片

#### 2.2.3 儲存抽象層
```csharp
public interface IImageStorageService
{
    Task<string> SaveImageAsync(Stream imageStream, string fileName);
    Task<string> GetImageUrlAsync(string imagePath);
    Task<bool> DeleteImageAsync(string imagePath);
    Task<StorageInfo> GetStorageInfoAsync();
}

// 實現類別
- LocalImageStorageService    // 開發環境
- CloudImageStorageService    // 生產環境
- HybridImageStorageService   // 混合策略
```

## 3. 資料庫設計

### 3.1 核心數據表結構

#### 3.1.1 例句圖片表 (example_images)
```sql
CREATE TABLE example_images (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    relative_path VARCHAR(500) NOT NULL,      -- 圖片相對路徑
    alt_text VARCHAR(200),                    -- 圖片描述文字
    generation_prompt TEXT,                   -- AI 生成時的提示詞
    generation_provider VARCHAR(50),          -- 生成服務供應商
    file_size INTEGER,                        -- 檔案大小 (bytes)
    image_width INTEGER,                      -- 圖片寬度
    image_height INTEGER,                     -- 圖片高度
    content_hash VARCHAR(64) UNIQUE,          -- 內容雜湊值 (防重複)
    quality_score DECIMAL(3,2),               -- 品質評分 (0.00-1.00)
    moderation_status VARCHAR(20) DEFAULT 'pending', -- 審核狀態
    moderation_notes TEXT,                    -- 審核備註
    access_count INTEGER DEFAULT 0,           -- 存取次數統計
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

#### 3.1.2 詞卡圖片關聯表 (flashcard_example_images)
```sql
CREATE TABLE flashcard_example_images (
    flashcard_id UUID REFERENCES flashcards(id) ON DELETE CASCADE,
    example_image_id UUID REFERENCES example_images(id) ON DELETE CASCADE,
    display_order INTEGER DEFAULT 1,         -- 顯示順序
    is_primary BOOLEAN DEFAULT false,        -- 是否為主要圖片
    context_relevance DECIMAL(3,2),          -- 語境相關度評分
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (flashcard_id, example_image_id)
);
```

#### 3.1.3 圖片生成請求表 (image_generation_requests)
```sql
CREATE TABLE image_generation_requests (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES user_profiles(id) ON DELETE CASCADE,
    flashcard_id UUID REFERENCES flashcards(id) ON DELETE CASCADE,
    request_prompt TEXT NOT NULL,            -- 生成請求提示詞
    generation_status VARCHAR(20) DEFAULT 'pending', -- 狀態: pending/processing/completed/failed
    generated_image_id UUID REFERENCES example_images(id),
    error_message TEXT,                      -- 錯誤訊息
    cost_credits DECIMAL(10,4),              -- 消耗的積分成本
    processing_time_ms INTEGER,              -- 處理時間 (毫秒)
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    completed_at TIMESTAMP
);
```

### 3.2 索引優化策略
```sql
-- 查詢效能索引
CREATE INDEX idx_example_images_content_hash ON example_images(content_hash);
CREATE INDEX idx_example_images_access_count ON example_images(access_count DESC);
CREATE INDEX idx_flashcard_images_primary ON flashcard_example_images(flashcard_id, is_primary);
CREATE INDEX idx_generation_requests_status ON image_generation_requests(generation_status, created_at);
```

## 4. API 設計規範

### 4.1 核心 API 端點

#### 4.1.1 生成例句圖片
```http
POST /api/flashcards/{flashcardId}/generate-example-image
Authorization: Bearer {token}
Content-Type: application/json

Request Body:
{
  "prompt": "A business meeting scene where someone is bringing up a topic",
  "style": "cartoon|realistic|minimal",     // 圖片風格
  "priority": "normal|high|low",           // 生成優先級
  "dimensions": {
    "width": 512,
    "height": 512
  },
  "additionalContext": {                   // 額外語境資訊
    "difficultyLevel": "B1",
    "scenario": "business",
    "learnerPreferences": ["visual", "colorful"]
  }
}

Response:
{
  "success": true,
  "data": {
    "requestId": "uuid",
    "status": "processing|completed",
    "estimatedTimeMinutes": 2,
    "imageUrl": "https://cdn.dramaling.com/images/examples/uuid.png", // 完成後才有
    "costCredits": 1.5,
    "queuePosition": 3                     // 佇列中的位置
  }
}
```

#### 4.1.2 獲取圖片生成狀態
```http
GET /api/image-generation/requests/{requestId}/status
Authorization: Bearer {token}

Response:
{
  "success": true,
  "data": {
    "status": "completed",
    "imageUrl": "https://cdn.dramaling.com/images/examples/uuid.png",
    "qualityScore": 0.95,
    "alternativeImages": [                 // 同時生成的其他選項
      {
        "imageUrl": "https://cdn.dramaling.com/images/examples/uuid-alt1.png",
        "qualityScore": 0.87
      }
    ],
    "completedAt": "2025-09-24T10:30:00Z"
  }
}
```

#### 4.1.3 批量管理例句圖片
```http
GET /api/admin/example-images
Authorization: Bearer {adminToken}
Query Parameters:
- status: pending|approved|rejected
- provider: dalle3|midjourney
- qualityScore: 0.8+ (minimum score)
- dateFrom: 2025-09-01
- dateTo: 2025-09-30
- page: 1
- pageSize: 50

Response:
{
  "success": true,
  "data": {
    "images": [...],
    "pagination": {
      "currentPage": 1,
      "totalPages": 10,
      "totalCount": 487
    },
    "statistics": {
      "pendingCount": 23,
      "approvedCount": 450,
      "rejectedCount": 14,
      "averageQualityScore": 0.89
    }
  }
}
```

## 5. 用戶體驗設計

### 5.1 互動流程設計

#### 5.1.1 主要使用流程
```
1. 用戶在詞卡頁面點擊「生成例句圖」
   ↓
2. 系統檢查現有圖片：
   - 有圖片 → 直接顯示
   - 無圖片 → 進入生成流程
   ↓
3. 圖片生成流程：
   - 顯示生成中動畫 (預估 1-3 分鐘)
   - 提供取消選項
   - 實時更新進度狀態
   ↓
4. 生成完成：
   - 自動刷新顯示新圖片
   - 提供「重新生成」選項
   - 收集用戶滿意度回饋
```

#### 5.1.2 錯誤處理與回退機制
```
生成失敗處理：
├── 網路錯誤 → 自動重試 3 次
├── AI 服務限制 → 提示稍後再試
├── 內容不當 → 顯示預設圖片
└── 積分不足 → 引導購買或升級
```

### 5.2 視覺設計規範

#### 5.2.1 圖片容器設計
```css
.example-image-container {
  width: 100%;
  max-width: 400px;
  aspect-ratio: 4/3;
  border-radius: 12px;
  overflow: hidden;
  border: 2px solid var(--border-color);
  background: linear-gradient(135deg, #f5f5f5, #e8e8e8);
}

.loading-state {
  display: flex;
  flex-direction: column;
  justify-content: center;
  align-items: center;
  height: 100%;
  background: var(--loading-bg);
}

.generate-button {
  background: linear-gradient(135deg, #667eea, #764ba2);
  color: white;
  border: none;
  border-radius: 8px;
  padding: 12px 24px;
  cursor: pointer;
  transition: transform 0.2s, box-shadow 0.2s;
}
```

#### 5.2.2 載入動畫設計
- **初始載入**：脈衝效果，顯示 "正在生成圖片..."
- **處理中**：進度條，顯示預估剩餘時間
- **完成**：淡入效果，圖片平滑顯示

## 6. 技術實現細節

### 6.1 AI 圖片生成整合

#### 6.1.1 提示詞優化策略
```csharp
public class PromptBuilder
{
    public string BuildPrompt(Flashcard flashcard)
    {
        var basePrompt = $"Create an educational illustration for the English word '{flashcard.Word}'";
        var context = $"Context: {flashcard.Example}";
        var style = GetStyleForDifficulty(flashcard.DifficultyLevel);
        var constraints = "Style: clean, educational, appropriate for language learning";

        return $"{basePrompt}. {context}. {style}. {constraints}";
    }

    private string GetStyleForDifficulty(string level)
    {
        return level switch
        {
            "A1" or "A2" => "Simple cartoon style with bright colors",
            "B1" or "B2" => "Semi-realistic style with clear details",
            "C1" or "C2" => "Realistic style with nuanced visual elements",
            _ => "Balanced educational illustration"
        };
    }
}
```

#### 6.1.2 品質檢測機制
```csharp
public class ImageQualityValidator
{
    public async Task<QualityResult> ValidateAsync(Stream imageStream)
    {
        var results = await Task.WhenAll(
            CheckImageClarity(imageStream),
            CheckContentAppropriateness(imageStream),
            CheckEducationalRelevance(imageStream)
        );

        return new QualityResult
        {
            OverallScore = results.Average(r => r.Score),
            Issues = results.SelectMany(r => r.Issues).ToList(),
            Approved = results.All(r => r.Score >= 0.7)
        };
    }
}
```

### 6.2 儲存服務實現

#### 6.2.1 環境配置
```json
// appsettings.Development.json
{
  "ImageStorage": {
    "Provider": "Local",
    "Local": {
      "BasePath": "wwwroot/images/examples",
      "BaseUrl": "https://localhost:5001/images/examples",
      "MaxFileSize": 5242880,  // 5MB
      "AllowedFormats": ["png", "jpg", "webp"]
    }
  }
}

// appsettings.Production.json
{
  "ImageStorage": {
    "Provider": "AWS",
    "AWS": {
      "BucketName": "dramaling-example-images",
      "Region": "ap-northeast-1",
      "CDNDomain": "https://cdn.dramaling.com",
      "AccessKeyId": "{from-environment}",
      "SecretAccessKey": "{from-environment}"
    }
  }
}
```

#### 6.2.2 儲存服務實現
```csharp
public class ImageStorageFactory
{
    public static IImageStorageService Create(IConfiguration config, ILogger logger)
    {
        var provider = config["ImageStorage:Provider"];

        return provider.ToLower() switch
        {
            "local" => new LocalImageStorageService(config, logger),
            "aws" => new AwsImageStorageService(config, logger),
            "azure" => new AzureImageStorageService(config, logger),
            _ => throw new NotSupportedException($"Storage provider '{provider}' not supported")
        };
    }
}
```

## 7. 成本控制與優化策略

### 7.1 智能成本管理

#### 7.1.1 積分系統設計
- **新用戶**：免費 10 張圖片生成額度
- **基礎用戶**：每月 50 張額度
- **進階用戶**：每月 200 張額度
- **企業用戶**：無限制

#### 7.1.2 生成優化策略
- **語意去重**：檢測類似例句，共享圖片資源
- **批量處理**：合併相似請求，降低 API 呼叫成本
- **離峰生成**：非繁忙時段優先處理，降低服務成本
- **品質預篩**：提示詞優化，提高首次生成成功率

### 7.2 快取策略優化

#### 7.2.1 多層快取架構
```
L1: 記憶體快取 (1小時) → 最熱門圖片
L2: Redis 快取 (24小時) → 常用圖片
L3: 資料庫快取 (永久) → 所有已生成圖片
L4: CDN 快取 (30天) → 公共訪問圖片
```

#### 7.2.2 預生成策略
- **熱門詞彙**：基於學習統計，預先生成高頻詞彙圖片
- **新詞預測**：AI 預測可能成為熱門的新詞彙
- **季節性內容**：節慶、時事相關詞彙提前準備

## 8. 監控與分析指標

### 8.1 關鍵效能指標 (KPIs)

#### 8.1.1 生成效能指標
- **生成成功率**：目標 ≥ 95%
- **平均生成時間**：目標 ≤ 90 秒
- **圖片品質評分**：目標平均 ≥ 0.85
- **用戶滿意度**：目標 ≥ 4.2/5.0

#### 8.1.2 業務影響指標
- **學習效果提升**：使用例句圖 vs 純文字的記憶測試對比
- **用戶參與度**：有圖片詞卡的複習頻率 vs 無圖片詞卡
- **留存率影響**：使用例句圖功能用戶的留存率提升
- **付費轉換**：例句圖功能對付費訂閱的貢獻度

### 8.2 實時監控告警

#### 8.2.1 系統健康監控
```yaml
alerts:
  - name: high_generation_failure_rate
    condition: failure_rate > 0.1  # 10%失敗率告警
    duration: 5m
    action: slack_notification

  - name: slow_generation_time
    condition: avg_generation_time > 120s
    duration: 3m
    action: email_alert

  - name: storage_quota_warning
    condition: storage_usage > 0.85  # 85%容量告警
    action: admin_dashboard_alert
```

## 9. 開發里程碑與排程

### 9.1 Phase 1: 核心功能開發 (4-6 週)

#### Week 1-2: 基礎架構
- [ ] 資料庫 schema 設計與建立
- [ ] 儲存抽象層實現 (本地 + 雲端)
- [ ] 基礎 API 端點開發
- [ ] AI 圖片生成服務整合

#### Week 3-4: 前端整合
- [ ] 詞卡頁面新增圖片生成功能
- [ ] 載入狀態與動畫實現
- [ ] 錯誤處理與用戶回饋機制
- [ ] 響應式設計適配

#### Week 5-6: 優化與測試
- [ ] 快取機制實現
- [ ] 批量處理佇列開發
- [ ] 單元測試與整合測試
- [ ] 效能測試與優化

### 9.2 Phase 2: 進階功能 (3-4 週)

#### Week 7-8: 智能優化
- [ ] 提示詞優化引擎
- [ ] 圖片品質自動檢測
- [ ] 語意去重機制
- [ ] 預生成策略實現

#### Week 9-10: 管理功能
- [ ] 管理後台圖片審核
- [ ] 成本統計與報表
- [ ] 用戶積分系統整合
- [ ] 監控告警系統

### 9.3 Phase 3: 上線與優化 (2-3 週)

#### Week 11-12: 生產部署
- [ ] 雲端儲存服務配置
- [ ] CDN 設定與優化
- [ ] 生產環境部署測試
- [ ] 灰度發布與 A/B 測試

#### Week 13: 後續優化
- [ ] 用戶回饋收集與分析
- [ ] 效能調優與成本優化
- [ ] 新功能規劃
- [ ] 文檔完善與團隊培訓

## 10. 風險評估與應對策略

### 10.1 技術風險

#### 10.1.1 AI 服務依賴風險
- **風險**：第三方 AI 服務中斷或限制
- **機率**：中等
- **影響**：高
- **應對策略**：
  - 多供應商備援 (DALL-E 3 + Midjourney + Stable Diffusion)
  - 離線 fallback 機制 (預設圖片庫)
  - 服務降級策略 (優雅處理失敗)

#### 10.1.2 儲存成本失控風險
- **風險**：圖片儲存成本超出預算
- **機率**：低
- **影響**：中等
- **應對策略**：
  - 自動清理未使用圖片機制
  - 壓縮與格式優化 (WebP)
  - 儲存層級管理 (熱/溫/冷數據分層)

### 10.2 產品風險

#### 10.2.1 用戶接受度風險
- **風險**：用戶對 AI 生成圖片品質不滿意
- **機率**：中等
- **影響**：中等
- **應對策略**：
  - 提供手動上傳選項
  - 多候選圖片讓用戶選擇
  - 持續的品質改進機制

#### 10.2.2 內容合規風險
- **風險**：AI 生成不當內容
- **機率**：低
- **影響**：高
- **應對策略**：
  - 多層內容過濾機制
  - 人工審核流程
  - 用戶舉報與快速處理機制

## 11. 成功指標與驗證方式

### 11.1 量化成功指標

#### 11.1.1 技術指標
- 圖片生成成功率 ≥ 95%
- 平均生成時間 ≤ 90 秒
- 系統可用性 ≥ 99.5%
- 圖片載入速度 ≤ 2 秒

#### 11.1.2 業務指標
- 用戶對圖片品質滿意度 ≥ 4.2/5.0
- 使用例句圖功能的詞卡複習率提升 ≥ 30%
- 用戶留存率提升 ≥ 15%
- 功能使用率 ≥ 60% (活躍用戶中)

### 11.2 驗證方式

#### 11.2.1 A/B 測試設計
- **測試組 A**：使用例句圖功能的用戶
- **對照組 B**：僅使用文字例句的用戶
- **測試指標**：學習效果、用戶參與度、留存率
- **測試週期**：4-6 週

#### 11.2.2 用戶回饋收集
- 功能滿意度問卷調查
- 用戶訪談與深度回饋
- 應用商店評分變化追蹤
- 客服反饋問題分析

---

## 文檔版本資訊

- **版本**：v1.0
- **創建日期**：2025-09-24
- **最後更新**：2025-09-24
- **負責人**：產品開發團隊
- **審核狀態**：待審核

---

*本文檔將隨著開發進展持續更新，確保與實際實現保持同步。如有疑問或建議，請聯繫產品團隊。*