docs/specs/html-preview/content-generation-overview.md

コンテンツ生成の全体フロー

概要

本システムでは、FV（ファーストビュー）、コンテンツHTML、画像生成を分離することで、優れたユーザー体験を提供しています。

なぜ分離されているのか？

1. レスポンス時間の最適化

• FV HTML生成: AIを使った画像生成を含む（3-10秒）
• コンテンツHTML生成: 即座に返却（< 1秒）
• コンテンツ画像生成: バックグラウンドで処理（30-100秒）
• ユーザーは待たずにレイアウトを確認可能

2. Adobe Firefly APIの制約

• 1枚の画像生成に3-10秒必要
• API呼び出しには認証トークンの取得も必要
• 同期処理ではHTTPタイムアウトのリスク

3. ユーザー体験の向上

• プログレッシブな表示により、進捗が視覚的に分かる
• エラーが発生しても部分的な成功を保証
• キャンセルや再試行が容易

処理フローの統合図

graph TB
    subgraph "フェーズ1: FV生成"
        A1[クライアント] -->|POST /html-preview/generate-fv-html| B1[FV HTML生成API]
        B1 --> C1[FVGenerationUseCase]
        C1 --> D1[SimplePipeline]
        D1 --> E1[AI画像生成]
        E1 --> F1[FV HTML + 画像URL]
        F1 -->|3-10秒| A1
    end

    subgraph "フェーズ2: コンテンツHTML生成"
        A[クライアント] -->|POST /html-preview/generate-contents-html| B[HTML生成API]
        B --> C[generateContentsHtmlWithImages]
        C --> D[プレースホルダー付きHTML]
        D -->|即座に返却| A
    end

    subgraph "フェーズ3: コンテンツ画像生成"
        A -->|POST /start-contents-image-generation| E[画像生成開始API]
        E --> F[画像要素抽出]
        F --> G[AIプロンプト生成]
        G --> H[Adobe Firefly並列処理]
        H --> I[画像URL生成]

        A -->|GET /image-generation-status/{batchId}| J[ステータス確認]
        J --> K{新しい画像?}
        K -->|Yes| L[JavaScript更新]
        K -->|No| J
    end

    style A fill:#f9f,stroke:#333,stroke-width:4px
    style A1 fill:#f9f,stroke:#333,stroke-width:4px
    style F1 fill:#9f9,stroke:#333,stroke-width:2px
    style D fill:#9f9,stroke:#333,stroke-width:2px
    style I fill:#9f9,stroke:#333,stroke-width:2px

実装の詳細

FV HTML生成（フェーズ1）

1. /html-preview/generate-fv-html APIを呼び出し
2. FVGenerationUseCaseでSimplePipelineを実行
3. AIを使用してFV画像を生成
4. 生成された画像と一緒にHTMLを返却

コンテンツHTML生成（フェーズ2）

1. /html-preview/generate-contents-html APIを呼び出し
2. ダミーモードの場合は事前生成HTMLを使用
3. 通常モードではHTMLGeneratorでテンプレートベースのHTML生成
4. 各画像位置にプレースホルダーを配置
5. 画像更新用のJavaScriptを含む完全なHTMLを返却

コンテンツ画像生成（フェーズ3）

1. /start-contents-image-generation APIで非同期処理を開始
2. Adobe Firefly認証情報がない場合はモックレスポンス
3. ContentImagesGeneratorで画像要素を抽出
4. ImagePromptGeneratorでAI（Claude/OpenAI）を使用してプロンプト生成
5. FireflyClientで並列に画像を生成
6. クライアントは/image-generation-status/{batchId}でステータスを確認

利点と制約

利点

• ✅ 即座のフィードバック
• ✅ スケーラブルな並列処理
• ✅ 部分的な失敗への耐性
• ✅ プログレッシブな表示

制約

• ⚠️ 追加のAPIコールが必要
• ⚠️ クライアント側のポーリング処理
• ⚠️ 状態管理の複雑性

環境変数と設定

必須環境変数

# Adobe Firefly認証情報（画像生成に必須）
D_FIREFLY_CLIENT_ID=your_client_id
D_FIREFLY_SECRET=your_client_secret

# AI Provider設定
OPENAI_API_KEY=your_openai_key
ANTHROPIC_API_KEY=your_anthropic_key

ダミーモード

開発時にはダミーモードを使用することで高速テストが可能：

POST /html-preview/generate-contents-html?dummyMode=true

関連ドキュメント

• HTML生成シーケンス図
• 画像生成シーケンス図
• APIリファレンス