feat: 新增例句圖生成功能產品需求規格書

- 完整的兩階段圖片生成架構設計 (Gemini + Replicate) - 雙環境儲存策略 (開發用本地，生產用雲端) - 詳細的資料庫設計、API規範和成本控制策略 - 包含完整的開發里程碑和風險評估 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-09-24 18:29:20 +08:00 · 2025-09-24 18:29:20 +08:00 · 9ac992cdbf
parent b45f2ef4c1
commit 9ac992cdbf
1 changed files with 607 additions and 0 deletions
--- a/EXAMPLE_IMAGE_GENERATION_PRD.md
+++ b/EXAMPLE_IMAGE_GENERATION_PRD.md
@ -0,0 +1,607 @@
+# 例句圖生成功能產品需求規格書 (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
+- **負責人**：產品開發團隊
+- **審核狀態**：待審核
+
+---
+
+*本文檔將隨著開發進展持續更新，確保與實際實現保持同步。如有疑問或建議，請聯繫產品團隊。*