# 画面設計書 1-ホームページ

## 概要

本ドキュメントは、Shopware 6 Storefrontにおけるホームページ（トップページ）の画面設計書である。ショップの入口となる画面であり、CMSコンテンツを基盤とした柔軟なレイアウト構成を提供する。

### 本画面の処理概要

ホームページはECサイトの顔となるトップページであり、顧客が最初に目にする重要な画面である。CMSシステムと連携し、管理者が設定したレイアウト（バナー、商品一覧、テキストブロック等）を動的に表示する。

**業務上の目的・背景**：ホームページは顧客がショップにアクセスした際の最初の接点となる画面である。ブランドイメージの訴求、プロモーション商品の露出、主要カテゴリへの誘導など、マーケティング上の重要な役割を担う。CMSベースの設計により、技術知識がなくてもマーケティング担当者がコンテンツを自由に編集できる点が業務課題の解決に貢献している。

**画面へのアクセス方法**：ショップのルートURL（例: https://example.com/）にアクセスすることで表示される。ヘッダーのロゴクリック、パンくずリストのホームリンク、各種ナビゲーションからも遷移可能である。

**主要な操作・処理内容**：
1. CMSページコンテンツの読み込みと表示（NavigationPageLoaderによるページデータ取得）
2. ヘッダー・フッターの共通コンポーネント表示（ESI経由での非同期読み込み対応）
3. ナビゲーションメニューの表示（カテゴリツリーの展開）
4. 商品カードやバナーなどのCMSブロック要素の描画
5. 検索機能へのアクセスポイント提供

**画面遷移**：
- 遷移元：ブラウザ直接アクセス、ログイン後のリダイレクト、各画面のロゴリンク
- 遷移先：カテゴリページ、商品詳細ページ、検索結果ページ、カートページ、アカウントページ

**権限による表示制御**：基本的に全ユーザーがアクセス可能。ログイン状態によりヘッダーのアカウントメニュー表示が変化する（ゲスト時：ログイン/登録リンク、ログイン時：マイアカウントリンク）。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 57 | ホームページ表示 | 主機能 | ショップトップページの表示処理（NavigationController::home） |
| 60 | ヘッダー表示 | 補助機能 | 共通ヘッダーの表示処理 |
| 61 | フッター表示 | 補助機能 | 共通フッターの表示処理 |

## 画面種別

トップページ / CMS表示

## URL/ルーティング

| 項目 | 値 |
|------|-----|
| URL | `/` |
| ルート名 | `frontend.home.page` |
| HTTPメソッド | GET |
| HTTPキャッシュ | 有効 |

## 入出力項目

### 入力項目

本画面は入力フォームを持たないが、以下のクエリパラメータを受け付ける可能性がある。

| 項目名 | パラメータ名 | 必須 | 型 | 説明 |
|--------|-------------|------|-----|------|
| - | - | - | - | 本画面固有の入力パラメータなし |

### 出力データ

| 項目名 | データソース | 説明 |
|--------|-------------|------|
| page | NavigationPageLoader | ページ全体のデータオブジェクト |
| page.cmsPage | CMS設定 | CMSページレイアウト情報 |
| page.category | カテゴリテーブル | 現在のナビゲーションカテゴリ |
| context | SalesChannelContext | 販売チャネルコンテキスト |

## 表示項目

| セクション | 表示項目 | 説明 |
|-----------|---------|------|
| ヘッダー | ロゴ | ショップロゴ画像 |
| ヘッダー | メインナビゲーション | カテゴリメニュー |
| ヘッダー | 検索バー | 商品検索入力フィールド |
| ヘッダー | カートアイコン | カート内商品数バッジ付き |
| ヘッダー | アカウントメニュー | ログイン/マイアカウントリンク |
| コンテンツ | パンくずリスト | 現在位置の階層表示 |
| コンテンツ | CMSブロック | 管理画面で設定されたCMSコンテンツ |
| フッター | フッターナビゲーション | 各種リンク（会社情報、利用規約等） |
| フッター | ニュースレター登録 | メール購読フォーム |

## イベント仕様

### 1-ページ読み込み

ブラウザでルートURLにアクセスすると、NavigationController::homeメソッドが実行される。

**処理フロー**：
1. NavigationPageLoaderがリクエストとSalesChannelContextを受け取る
2. 販売チャネルに設定されたホームカテゴリのCMSページを取得
3. CMSページのセクション・ブロック・スロットを解決
4. NavigationPageLoadedHookを発火し、拡張ポイントを提供
5. Twigテンプレート`@Storefront/storefront/page/content/index.html.twig`でレンダリング

### 2-ナビゲーションクリック

ヘッダーのカテゴリリンクをクリックすると、該当カテゴリページへ遷移する。

### 3-検索実行

検索バーにキーワードを入力してEnterキーまたは検索ボタンを押下すると、検索結果ページへ遷移する。

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| ページ表示 | - | SELECT | データ参照のみ、更新なし |

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

### テーブル別更新項目詳細

該当なし（読み取り専用画面）

## メッセージ仕様

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

## 例外処理

| 例外条件 | 対応 |
|---------|------|
| CMSページ未設定 | 空のコンテンツエリアが表示される |
| 販売チャネル無効 | 503エラーページへリダイレクト |
| カテゴリ未発見 | 404エラーページへリダイレクト |

## 備考

- HTTPキャッシュが有効であり、パフォーマンス最適化のためESI（Edge Side Includes）によるヘッダー/フッターの部分キャッシュに対応している
- SEO対応として、metaタグやOpen Graphタグがhead部分に出力される
- レスポンシブデザインに対応し、モバイル端末ではオフキャンバスメニューに切り替わる

---

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

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

### 推奨読解順序

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

まず、ページ表示に使用されるデータ構造を把握することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | NavigationPage.php | `src/Storefront/Page/Navigation/NavigationPage.php` | ページオブジェクトの構造、cmsPage/categoryプロパティの役割を理解 |
| 1-2 | CategoryEntity.php | `src/Core/Content/Category/CategoryEntity.php` | カテゴリエンティティの構造、CMSページとの関連を確認 |

**読解のコツ**: ShopwareのPageオブジェクトはStructを継承しており、getter/setterでプロパティにアクセスする。`getXxx()`メソッドの戻り値の型を確認することでデータ構造が把握できる。

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

処理の起点となるコントローラーを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | NavigationController.php | `src/Storefront/Controller/NavigationController.php` | homeメソッドがエントリーポイント、Routeアノテーションでルーティング設定を確認 |

**主要処理フロー**:
1. **56-57行目**: homeメソッドの定義、Request/SalesChannelContextを引数に受け取る
2. **58行目**: NavigationPageLoaderを呼び出してページデータを取得
3. **60行目**: NavigationPageLoadedHookでフック処理を実行
4. **62行目**: Twigテンプレートをレンダリングして返却

#### Step 3: ページローダーを理解する

ページデータの構築ロジックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | NavigationPageLoader.php | `src/Storefront/Page/Navigation/NavigationPageLoader.php` | loadメソッドでカテゴリとCMSページの取得処理を確認 |

**主要処理フロー**:
- カテゴリIDの取得（リクエストまたはコンテキストから）
- CMSPageLoaderを使用したCMSページデータの解決
- ページオブジェクトの構築と返却

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

画面のレンダリング構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | index.html.twig | `src/Storefront/Resources/views/storefront/page/content/index.html.twig` | base.html.twigを継承、cms_contentブロックでCMSページを描画 |
| 4-2 | base.html.twig | `src/Storefront/Resources/views/storefront/base.html.twig` | ヘッダー/フッター/メインコンテンツの全体レイアウト |
| 4-3 | detail.html.twig | `src/Storefront/Resources/views/storefront/page/content/detail.html.twig` | CMSセクション・ブロックの繰り返し描画ロジック |

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

```
NavigationController::home()
    |
    +-- NavigationPageLoader::load()
    |       |
    |       +-- GenericPageLoader::load()
    |       |       +-- HeaderPageletLoader (ESI)
    |       |       +-- FooterPageletLoader (ESI)
    |       |
    |       +-- CategoryRoute::load()
    |       |
    |       +-- CmsPageLoader::load()
    |               +-- CmsSlotResolver
    |
    +-- NavigationPageLoadedHook (イベント発火)
    |
    +-- renderStorefront()
            +-- index.html.twig
                    +-- base.html.twig
                    +-- detail.html.twig (CMSコンテンツ)
```

### データフロー図

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

HTTP Request      -->  NavigationController
    |                       |
    v                       v
SalesChannelContext   NavigationPageLoader
                           |
                           v
                      CategoryRoute
                           |
                           v
                      CmsPageLoader         -->  NavigationPage
                           |                          |
                           v                          v
                      Database              -->  Twig Template
                      (category,                      |
                       cms_page,                      v
                       cms_section,             HTML Response
                       cms_block,
                       cms_slot)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| NavigationController.php | `src/Storefront/Controller/NavigationController.php` | コントローラー | ルーティングエントリーポイント |
| NavigationPageLoader.php | `src/Storefront/Page/Navigation/NavigationPageLoader.php` | ページローダー | ページデータの構築 |
| NavigationPage.php | `src/Storefront/Page/Navigation/NavigationPage.php` | データ構造 | ページオブジェクト定義 |
| index.html.twig | `src/Storefront/Resources/views/storefront/page/content/index.html.twig` | テンプレート | メインテンプレート |
| base.html.twig | `src/Storefront/Resources/views/storefront/base.html.twig` | テンプレート | ベースレイアウト |
| detail.html.twig | `src/Storefront/Resources/views/storefront/page/content/detail.html.twig` | テンプレート | CMSコンテンツ描画 |
| header.html.twig | `src/Storefront/Resources/views/storefront/layout/header.html.twig` | テンプレート | ヘッダー部品 |
| footer.html.twig | `src/Storefront/Resources/views/storefront/layout/footer.html.twig` | テンプレート | フッター部品 |
| breadcrumb.html.twig | `src/Storefront/Resources/views/storefront/layout/breadcrumb.html.twig` | テンプレート | パンくずリスト |
