From 9ac992cdbfa51c54d2c6b84d73e56f3f88b1bad3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=84=AD=E6=B2=9B=E8=BB=92?= Date: Wed, 24 Sep 2025 18:29:20 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E6=96=B0=E5=A2=9E=E4=BE=8B=E5=8F=A5?= =?UTF-8?q?=E5=9C=96=E7=94=9F=E6=88=90=E5=8A=9F=E8=83=BD=E7=94=A2=E5=93=81?= =?UTF-8?q?=E9=9C=80=E6=B1=82=E8=A6=8F=E6=A0=BC=E6=9B=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 完整的兩階段圖片生成架構設計 (Gemini + Replicate) - 雙環境儲存策略 (開發用本地，生產用雲端) - 詳細的資料庫設計、API規範和成本控制策略 - 包含完整的開發里程碑和風險評估 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- EXAMPLE_IMAGE_GENERATION_PRD.md | 607 ++++++++++++++++++++++++++++++++ 1 file changed, 607 insertions(+) create mode 100644 EXAMPLE_IMAGE_GENERATION_PRD.md diff --git a/EXAMPLE_IMAGE_GENERATION_PRD.md b/EXAMPLE_IMAGE_GENERATION_PRD.md new file mode 100644 index 0000000..e33c73e --- /dev/null +++ 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 SaveImageAsync(Stream imageStream, string fileName); + Task GetImageUrlAsync(string imagePath); + Task DeleteImageAsync(string imagePath); + Task 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 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 +- **負責人**：產品開發團隊 +- **審核狀態**：待審核 + +--- + +*本文檔將隨著開發進展持續更新，確保與實際實現保持同步。如有疑問或建議，請聯繫產品團隊。* \ No newline at end of file