# 画面設計書 4-商品クイックビュー

## 概要

本ドキュメントは、Shopware 6 Storefrontにおける商品クイックビューの画面設計書である。商品一覧画面からページ遷移せずに商品の概要情報を確認できるモーダル形式のウィジェットである。

### 本画面の処理概要

商品クイックビューは、商品一覧ページやカテゴリページから商品の基本情報を素早く確認するためのモーダルダイアログである。AJAX経由で非同期に読み込まれ、商品画像、名前、価格、説明などの主要情報を表示する。

**業務上の目的・背景**：商品クイックビューは、顧客が商品一覧を閲覧中に興味を持った商品の詳細を確認する際、ページ遷移による文脈の喪失を防ぐ。これにより、複数商品の比較検討がスムーズになり、購買体験を向上させる。特にカテゴリページでの商品探索時に有効であり、コンバージョン率の向上に寄与する。

**画面へのアクセス方法**：商品カードの「クイックビュー」ボタン（虫眼鏡アイコン等）をクリックすることでモーダルが開く。AJAX経由で`/quickview/{productId}`エンドポイントが呼び出される。

**主要な操作・処理内容**：
1. 商品の基本情報取得（MinimalQuickViewPageLoader）
2. 商品画像の表示
3. 商品名、価格、説明の表示
4. 商品詳細ページへのリンク提供
5. モーダルの閉じる操作

**画面遷移**：
- 遷移元：カテゴリページ、検索結果ページ（モーダルとして表示）
- 遷移先：商品詳細ページ（リンククリック時）

**権限による表示制御**：全ユーザーがアクセス可能。特別な権限制御なし。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 29 | クイックビュー | 主機能 | 商品の簡易表示モーダル（ProductController::quickviewMinimal） |
| 39 | 商品追加 | 補助機能 | カートへの商品追加（商品詳細への誘導経由） |

## 画面種別

モーダル / ウィジェット

## URL/ルーティング

| 項目 | 値 |
|------|-----|
| URL | `/quickview/{productId}` |
| ルート名 | `widgets.quickview.minimal` |
| HTTPメソッド | GET |
| XmlHttpRequest | 必須 |

## 入出力項目

### 入力項目

| 項目名 | パラメータ名 | 必須 | 型 | 説明 |
|--------|-------------|------|-----|------|
| 商品ID | productId | 必須 | string(UUID) | 商品のID |

### 出力データ

| 項目名 | データソース | 説明 |
|--------|-------------|------|
| page | MinimalQuickViewPageLoader | クイックビュー用ページオブジェクト |
| page.product | 商品テーブル | 商品エンティティ（簡易版） |

## 表示項目

| セクション | 表示項目 | 説明 |
|-----------|---------|------|
| 画像エリア | 商品画像 | カバー画像（メイン画像） |
| 情報エリア | 商品名 | 商品タイトル（リンク付き） |
| 情報エリア | 商品番号 | 商品のSKU/品番 |
| 情報エリア | メーカー | メーカーロゴまたは名前（リンク付き） |
| 詳細エリア | 商品説明 | 商品の説明文（HTMLサニタイズ済み） |

## イベント仕様

### 1-クイックビュー表示

商品カードのクイックビューボタンをクリックすると、モーダルが表示される。

**処理フロー**：
1. JavaScriptがクリックイベントをキャッチ
2. AJAX経由で`/quickview/{productId}`を呼び出し
3. ProductController::quickviewMinimalが実行される
4. MinimalQuickViewPageLoaderで商品データを取得
5. ProductQuickViewWidgetLoadedHookを発火
6. minimal.html.twigでHTMLをレンダリング
7. モーダルとして表示

### 2-商品詳細へ遷移

商品名リンクをクリックすると、商品詳細ページへ遷移する。

### 3-モーダルを閉じる

モーダル外のクリック、閉じるボタン、Escキーでモーダルが閉じる。

## データベース更新仕様

### 操作別データベース影響一覧

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| クイックビュー表示 | product, product_media, product_manufacturer | SELECT | 商品データ参照のみ |

本画面は表示専用であり、データベースへの書き込み操作は発生しない。

## メッセージ仕様

| メッセージ種別 | 条件 | メッセージ内容 |
|--------------|------|--------------|
| - | - | 本画面固有のメッセージなし |

## 例外処理

| 例外条件 | 対応 |
|---------|------|
| 商品未発見 | モーダルが開かない、またはエラー表示 |
| AJAX通信エラー | ローディング表示のまま、またはエラーメッセージ |

## 備考

- クイックビューは「minimal」版であり、バリアント選択やカート追加機能は含まない
- 商品詳細へのリンクは別タブで開く（target="_blank"）
- 画像がない場合はプレースホルダーアイコンが表示される
- メーカーロゴがある場合は画像表示、ない場合はテキスト表示

---

## コードリーディングガイド

本画面を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | MinimalQuickViewPage.php | `src/Storefront/Page/Product/QuickView/MinimalQuickViewPage.php` | ページオブジェクトの構造 |

**読解のコツ**: MinimalQuickViewPageは最小限の商品情報のみを持つ軽量なページオブジェクトである。

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ProductController.php | `src/Storefront/Controller/ProductController.php` | quickviewMinimalメソッド（130-143行目） |

**主要処理フロー**:
1. **136-138行目**: Routeアノテーションでエンドポイント定義
2. **138行目**: MinimalQuickViewPageLoaderで商品データ取得
3. **140行目**: ProductQuickViewWidgetLoadedHookでフック処理
4. **142行目**: minimal.html.twigでレンダリング

#### Step 3: テンプレート構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | minimal.html.twig | `src/Storefront/Resources/views/storefront/component/product/quickview/minimal.html.twig` | クイックビューテンプレート |

**主要処理フロー**:
- **1-5行目**: 商品名とメーカー情報の取得
- **8-40行目**: 商品画像の表示（メディアタイプに応じた分岐）
- **42-85行目**: 商品情報（名前、番号、メーカー）の表示
- **89-106行目**: 商品説明の表示

### プログラム呼び出し階層図

```
[商品カード クイックビューボタン]
    |
    v
JavaScript (AJAX Request)
    |
    v
ProductController::quickviewMinimal()
    |
    +-- MinimalQuickViewPageLoader::load()
    |       |
    |       +-- ProductRoute::load() (簡易版)
    |
    +-- ProductQuickViewWidgetLoadedHook
    |
    +-- renderStorefront()
            +-- minimal.html.twig
                    |
                    v
            [モーダル表示]
```

### データフロー図

```
[入力]                    [処理]                         [出力]

productId         -->  ProductController
(AJAX)                      |
                           v
                   MinimalQuickViewPageLoader
                           |
                           v
                      ProductRoute
                           |
                           v
                   MinimalQuickViewPage    -->  HTML Fragment
                           |
                           v
                   minimal.html.twig
                           |
                           v
                   [Modal Dialog]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ProductController.php | `src/Storefront/Controller/ProductController.php` | コントローラー | ルーティングエントリーポイント |
| MinimalQuickViewPageLoader.php | `src/Storefront/Page/Product/QuickView/MinimalQuickViewPageLoader.php` | ページローダー | ページデータの構築 |
| MinimalQuickViewPage.php | `src/Storefront/Page/Product/QuickView/MinimalQuickViewPage.php` | データ構造 | ページオブジェクト定義 |
| minimal.html.twig | `src/Storefront/Resources/views/storefront/component/product/quickview/minimal.html.twig` | テンプレート | クイックビューHTML |
| pseudo-modal.html.twig | `src/Storefront/Resources/views/storefront/component/pseudo-modal.html.twig` | テンプレート | モーダル基盤 |
