# 機能設計書 67-エラーページ

## 概要

本ドキュメントは、Shopware Storefrontにおけるエラー発生時のエラーページを表示する機能について、その処理内容、入出力仕様、およびコード構造を記述した機能設計書である。

### 本機能の処理概要

本機能は、アプリケーション内で例外が発生した際に、ユーザーフレンドリーなエラーページを表示する機能である。

**業務上の目的・背景**：ECサイトにおいて、ページが見つからない（404）、サーバーエラー（500）などのエラーが発生した際に、技術的なエラーメッセージではなくユーザーにわかりやすいエラーページを表示することで、ユーザーエクスペリエンスを向上させる。また、404エラーの場合はCMSでカスタマイズ可能なエラーページを表示できる。

**機能の利用シーン**：
- 存在しないURLにアクセスした場合（404エラー）
- アプリケーションエラーが発生した場合（500エラー）
- CAPTCHAバリデーションに失敗した場合
- その他の例外が発生した場合

**主要な処理内容**：
1. 例外を受け取る
2. 例外の種類（404かそれ以外）を判定
3. 404の場合はCMSエラーページの読み込みを試行
4. フラッシュメッセージの設定
5. エラーテンプレートを解決してレンダリング
6. 適切なHTTPステータスコードを設定

**関連システム・外部連携**：ErrorTemplateResolver、ErrorPageLoader、SystemConfigService

**権限による制御**：特別な権限制御なし（すべてのユーザーに表示）

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 28 | 404エラーページ | 主機能 | ページが見つからない場合のエラー表示（ErrorController） |
| 30 | 汎用エラーページ | 主機能 | その他のエラー表示（ErrorController） |

## 機能種別

画面表示 / エラーハンドリング

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| exception | \Throwable | Yes | 発生した例外オブジェクト | - |
| request | Request | Yes | HTTPリクエストオブジェクト | - |
| context | SalesChannelContext | Yes | 販売チャネルコンテキスト | - |
| violations | ConstraintViolationList | No | CAPTCHAバリデーション違反リスト | onCaptchaFailure時のみ |

### 入力データソース

- 例外オブジェクト: 発生した例外の情報
- システム設定: `core.basicInformation.http404Page`（404用CMSページID）
- セッション: フラッシュメッセージ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| page | ErrorPage\|ErrorTemplatePage | エラーページオブジェクト |
| page.cmsPage | CmsPageEntity | CMSページ（404でCMS設定時のみ） |

### 出力先

- HTMLレスポンス
- テンプレート:
  - 404（CMS設定時）: `@Storefront/storefront/page/content/index.html.twig`
  - その他: ErrorTemplateResolverで解決されたテンプレート
  - フォールバック: `@Storefront/storefront/page/error/index.html.twig`
- HTTPステータス: 例外に応じたステータスコード（404, 500等）

## 処理フロー

### 処理シーケンス

```
1. ErrorController::error() が例外を受け取る

2. セッションの確認
   └─ セッションがある場合はフラッシュバッグを操作

3. 例外の種類を判定
   └─ HttpExceptionで404ステータスか確認

4. 404以外の場合
   └─ フラッシュメッセージ（danger）に'error.message-default'を追加

5. navigationIdをリクエスト属性にセット
   └─ 販売チャネルのナビゲーションカテゴリID

6. 404エラーの場合
   ├─ SystemConfigからhttp404PageのCMSページIDを取得
   ├─ CMSページIDがある場合
   │   ├─ ErrorPageLoader::load() でCMSページを取得
   │   └─ index.html.twig でレンダリング
   └─ CMSページIDがない場合
       └─ ErrorTemplateResolver で通常のエラーテンプレートを解決

7. エラーテンプレートのレンダリング

8. ステータスコードの設定
   └─ HttpExceptionの場合はそのステータスコードを使用

9. フラッシュバッグのクリア

10. レスポンスの返却
```

### フローチャート

```mermaid
flowchart TD
    A[例外受信] --> B[セッション確認]
    B --> C{404エラー?}
    C -->|No| D[フラッシュメッセージ追加]
    C -->|Yes| E[navigationIdセット]
    D --> E
    E --> F[SystemConfigから404ページID取得]
    F --> G{CMSページIDあり & 404?}
    G -->|Yes| H[ErrorPageLoader::load]
    H --> I[index.html.twig]
    G -->|No| J[ErrorTemplateResolver]
    J --> K[エラーテンプレート]
    I --> L{HttpException?}
    K --> L
    L -->|Yes| M[ステータスコード設定]
    L -->|No| N[500設定]
    M --> O[フラッシュバッグクリア]
    N --> O
    O --> P[レスポンス返却]

    Q[例外発生: フォールバック] --> R[error/index.html.twig]
    R --> S[500設定]
    S --> P
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 404用CMSページ | 404エラー時にCMSページが設定されていればそれを表示 | 404エラー時 |
| BR-002 | フラッシュメッセージ | 404以外のエラーではフラッシュメッセージにエラーを追加 | 非404エラー時 |
| BR-003 | ステータスコード継承 | HttpExceptionの場合はそのステータスコードを使用 | HttpException発生時 |
| BR-004 | フォールバック | レンダリングに失敗した場合は基本的なエラーテンプレートを使用 | 例外発生時 |
| BR-005 | フラッシュバッグクリア | レンダリング後にフラッシュバッグをクリア | 常時 |

### 計算ロジック

特になし

## データベース操作仕様

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| CMSページ取得 | cms_page | SELECT | 404用CMSページの取得 |

### テーブル別操作詳細

#### cms_page

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | id, sections, blocks, slots等 | id = {404用CMSページID} | 関連するセクション、ブロック、スロットも取得 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | フォールバック | CMSページの読み込み失敗 | 基本的なエラーテンプレートを表示 |
| - | フォールバック | テンプレートレンダリング失敗 | error/index.html.twigを使用 |

### リトライ仕様

リトライ処理なし

## トランザクション仕様

読み取り専用のためトランザクション制御なし

## パフォーマンス要件

- レスポンス時間：200ms以内推奨

## セキュリティ考慮事項

- 本番環境では詳細なエラー情報を表示しない
- XSS対策：Twigのエスケープ機能を使用
- セッションのフラッシュバッグを適切にクリア

## 備考

- 404エラーページはCMSでカスタマイズ可能
- ErrorTemplateResolverにより例外タイプに応じたテンプレートを選択
- CAPTCHAバリデーション失敗時の専用ハンドラーも提供

---

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

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

### 推奨読解順序

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

エラーページのデータ構造を理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ErrorPage.php | `src/Storefront/Page/Navigation/Error/ErrorPage.php` | 404用CMSページを含むエラーページの構造 |

**読解のコツ**: ErrorPageはPageクラスを継承し、CmsPageEntityを保持できる。404エラー時にCMSページが設定されている場合に使用される。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ErrorController.php | `src/Storefront/Controller/ErrorController.php` | error(), onCaptchaFailure()メソッド |

**主要処理フロー**:
1. **35行目**: error()メソッド - メインのエラーハンドリング
2. **36-37行目**: セッションの確認
3. **40-41行目**: 404ステータスの判定
4. **43-45行目**: フラッシュメッセージの追加（404以外）
5. **47行目**: navigationIdの設定
6. **49-51行目**: SystemConfigから404用CMSページIDを取得
7. **52-63行目**: 404かつCMSページ設定時の処理
8. **64-66行目**: HttpExceptionのステータスコード設定
9. **67-75行目**: フォールバック処理
10. **86-109行目**: onCaptchaFailure() - CAPTCHAエラー処理

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

404用CMSページの読み込み処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ErrorPageLoader.php | `src/Storefront/Page/Navigation/Error/ErrorPageLoader.php` | load()メソッド（39-56行目） |

**主要処理フロー**:
- **41行目**: GenericPageLoaderで共通ページデータを取得
- **42行目**: ErrorPageに変換
- **44行目**: CMSページローダーでCMSページを取得
- **46-49行目**: CMSページが存在しない場合は例外
- **51行目**: CMSページをセット
- **53行目**: ErrorPageLoadedEventをディスパッチ

#### Step 4: テンプレートリゾルバを理解する

エラーテンプレートの解決処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | ErrorTemplateResolver.php | `src/Storefront/Framework/Twig/ErrorTemplateResolver.php` | resolve()メソッド |

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

```
ErrorController::error()
    │
    ├─ セッション/フラッシュバッグ処理
    │
    ├─ 404 & CMSページ設定時
    │      └─ ErrorPageLoader::load()
    │             ├─ GenericPageLoader::load()
    │             └─ SalesChannelCmsPageLoader::load()
    │                    └─ ErrorPage (with CmsPage)
    │
    ├─ その他のエラー
    │      └─ ErrorTemplateResolver::resolve()
    │             └─ ErrorTemplatePage
    │
    └─ renderStorefront() → エラーテンプレート

ErrorController::onCaptchaFailure()
    │
    ├─ forwardToRoute() [非Ajax]
    │
    └─ JsonResponse [Ajax]
```

### データフロー図

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

\Throwable ─────────────────────┐
                                ▼
Request ────────────────▶ ErrorController ──────▶ HTML Response
                                │                      │
SalesChannelContext             │                      │
                                ▼                      │
                         例外種類判定                   │
                                │                      │
          ┌─────────────────────┴──────────────────┐   │
          ▼                                        ▼   │
    404 & CMSあり                            その他     │
          │                                        │   │
          ▼                                        ▼   │
    ErrorPageLoader                    ErrorTemplateResolver
          │                                        │   │
          ▼                                        ▼   ▼
    ErrorPage (CMS)                         ErrorTemplatePage
          │                                        │
          └────────────────┬───────────────────────┘
                           ▼
                    Twigレンダリング
                           │
                           ▼
                    HTTPステータス設定
                           │
                           ▼
                    レスポンス返却
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ErrorController.php | `src/Storefront/Controller/ErrorController.php` | コントローラー | エラーページ表示のエントリーポイント |
| ErrorPageLoader.php | `src/Storefront/Page/Navigation/Error/ErrorPageLoader.php` | ローダー | 404用CMSページの読み込み |
| ErrorPageLoaderInterface.php | `src/Storefront/Page/Navigation/Error/ErrorPageLoaderInterface.php` | インターフェース | ローダーのインターフェース定義 |
| ErrorPage.php | `src/Storefront/Page/Navigation/Error/ErrorPage.php` | ページ | エラーページのデータ構造 |
| ErrorPageLoadedEvent.php | `src/Storefront/Page/Navigation/Error/ErrorPageLoadedEvent.php` | イベント | エラーページ読み込み完了イベント |
| ErrorTemplateResolver.php | `src/Storefront/Framework/Twig/ErrorTemplateResolver.php` | リゾルバ | エラーテンプレートの解決 |
