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. ユーザー体験の向上

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

## 処理フローの統合図

```mermaid
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コールが必要
- ⚠️ クライアント側のポーリング処理
- ⚠️ 状態管理の複雑性

## 環境変数と設定

### 必須環境変数

```bash
# 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
```

### ダミーモード

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

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

## 関連ドキュメント

- [HTML生成シーケンス図](./html-generation-sequence.md)
- [画像生成シーケンス図](./image-generation-sequence.md)
- [APIリファレンス](../../image-generation-api.md)