# 機能設計書 3-ゲストログイン

## 概要

本ドキュメントは、Shopware 6 Storefrontにおけるゲストログイン機能の設計仕様を記述する。ゲスト顧客が過去の注文を確認するためにログインする機能である。

### 本機能の処理概要

**業務上の目的・背景**：ECサイトでは、会員登録をせずにゲストとして注文することが可能である。しかし、注文後に注文状況を確認したり、注文内容を変更したりする必要が生じる場合がある。本機能により、ゲスト顧客がメールアドレスと注文時の情報を使用して一時的にログインし、注文情報にアクセスできるようになる。

**機能の利用シーン**：ゲストとして注文した顧客が、注文確認メールに記載されたリンクから注文状況を確認したい場合、または注文の支払い方法を変更したい場合に使用される。

**主要な処理内容**：
1. ゲストログインページの表示
2. redirectToパラメータがない場合はエラーメッセージを表示してログインページへリダイレクト
3. 既にログイン済みの場合はリダイレクト先へ遷移
4. 待ち時間やログインエラーがある場合はフラッシュメッセージを表示
5. ゲストログインフォームを表示

**関連システム・外部連携**：特になし

**権限による制御**：未ログイン状態のゲスト顧客が使用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 13 | ゲストログインページ | 主機能 | ゲスト顧客の注文確認用ログイン（AuthController::guestLoginPage） |

## 機能種別

認証処理 / 画面表示

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| redirectTo | string | Yes | ログイン後のリダイレクト先ルート名 | 存在しない場合はエラー |
| redirectParameters | string | No | リダイレクト時のパラメータ（JSON形式） | - |
| waitTime | int | No | レート制限による待ち時間（秒） | - |
| loginError | bool | No | ログインエラーフラグ | - |

### 入力データソース

- クエリパラメータ（GETリクエスト）
- リクエスト属性（フォワード時）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| page | AccountLoginPage | ログインページデータ |
| redirectTo | string | リダイレクト先ルート名 |
| redirectParameters | string | リダイレクトパラメータ（JSON） |

### 出力先

- 画面表示（Twigテンプレート）
- フラッシュメッセージ（エラー時）

## 処理フロー

### 処理シーケンス

```
1. リクエスト受信
   └─ AuthController::guestLoginPage がGETリクエストを受け取る

2. redirectToパラメータチェック
   └─ nullまたは空の場合はエラーメッセージを追加してログインページへリダイレクト

3. ログイン状態チェック
   └─ 既にログイン済みの場合はredirectTo先へリダイレクト

4. 待ち時間チェック
   └─ waitTimeが設定されている場合はINFOメッセージを表示

5. ログインエラーチェック
   └─ loginErrorが設定されている場合はDANGERメッセージを表示

6. ページデータ読み込み
   └─ AccountLoginPageLoader::load でページデータを取得

7. フック実行
   └─ AccountGuestLoginPageLoadedHook を実行

8. レスポンス生成
   └─ guest-auth.html.twigテンプレートをレンダリング
```

### フローチャート

```mermaid
flowchart TD
    A[ゲストログインページ開始] --> B{redirectToあり?}
    B -->|No| C[エラーメッセージ追加]
    C --> D[ログインページへリダイレクト]
    B -->|Yes| E{ログイン済み?}
    E -->|Yes| F[redirectTo先へリダイレクト]
    E -->|No| G{waitTimeあり?}
    G -->|Yes| H[待ち時間メッセージ表示]
    G -->|No| I{loginErrorあり?}
    H --> I
    I -->|Yes| J[エラーメッセージ表示]
    I -->|No| K[ページデータ読み込み]
    J --> K
    K --> L[AccountGuestLoginPageLoadedHook]
    L --> M[ゲストログインフォーム表示]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | リダイレクト先必須 | redirectToパラメータがない場合はゲストログインページとして無効 | ページアクセス時 |
| BR-002 | 既存ログインのリダイレクト | 既にログイン済みの場合は認証処理をスキップしてリダイレクト | ログイン済み時 |
| BR-003 | レート制限メッセージ | waitTimeが設定されている場合はログイン試行制限のメッセージを表示 | waitTime > 0時 |

### 計算ロジック

- 特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ページデータ取得 | - | SELECT | AccountLoginPageLoader経由で必要なデータを取得 |

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

- ゲストログインページ表示自体はデータベース操作を伴わない
- 実際のログイン処理は AuthController::login が担当

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | フラッシュメッセージ（DANGER） | redirectToがない場合 | ログインページへリダイレクト |
| - | フラッシュメッセージ（DANGER） | loginError=trueの場合 | ゲストログインページでエラー表示 |
| - | フラッシュメッセージ（INFO） | waitTimeが設定されている場合 | 待ち時間を表示 |

### リトライ仕様

- waitTime秒後に再試行可能

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

- ページ表示のみのためトランザクションは使用しない

## パフォーマンス要件

- ページ表示は300ms以内のレスポンスを目標

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

- redirectToパラメータがない場合は直接アクセスとみなしエラー扱い
- ゲストログインは注文確認など限定的な機能へのアクセスに使用

## 備考

- ゲストログインは通常のログインと同じ AuthController::login でPOST処理される
- ゲストログインフォームは guest-auth.html.twig テンプレートで表示

---

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

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

### 推奨読解順序

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

ページローダーが返すデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | AccountLoginPage.php | `src/Storefront/Page/Account/Login/AccountLoginPage.php` | ログインページのデータ構造 |
| 1-2 | AccountGuestLoginPageLoadedHook.php | `src/Storefront/Page/Account/Login/AccountGuestLoginPageLoadedHook.php` | フックイベントの構造 |

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

StorefrontのゲストログインページリクエストはAuthControllerで受け付けられる。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | AuthController.php | `src/Storefront/Controller/AuthController.php` | guestLoginPage()メソッド（104-151行目） |

**主要処理フロー**:
1. **112-114行目**: redirectToの取得とnullチェック
2. **113-118行目**: redirectToがない場合はエラーメッセージを追加してリダイレクト
3. **121-127行目**: 既にログイン済みの場合はリダイレクト
4. **131-134行目**: waitTimeが設定されている場合はINFOメッセージ
5. **138-140行目**: loginErrorが設定されている場合はDANGERメッセージ
6. **142行目**: AccountLoginPageLoader::load呼び出し
7. **144行目**: AccountGuestLoginPageLoadedHookを実行
8. **146-150行目**: guest-auth.html.twigをレンダリング

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

```
AuthController::guestLoginPage (Storefront)
    │
    ├─ redirectToパラメータチェック
    │      └─ [なし] addFlash + redirectToRoute
    │
    ├─ context.getCustomer() チェック
    │      └─ [ログイン済み] createActionResponse
    │
    ├─ waitTime/loginError チェック
    │      └─ addFlash (必要に応じて)
    │
    ├─ AccountLoginPageLoader::load
    │
    ├─ AccountGuestLoginPageLoadedHook (dispatch)
    │
    └─ renderStorefront('guest-auth.html.twig')
```

### データフロー図

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

redirectTo, ───▶ AuthController::guestLoginPage
redirectParameters,         │
waitTime,                   ▼
loginError             パラメータ検証
                           │
                     ┌─────┴─────┐
                     ▼           ▼
              redirectTo?   ログイン済み?
              (なし)         (あり)
                     │           │
                     ▼           ▼
              ログインページ  リダイレクト先
              へリダイレクト

                     [正常フロー]
                           │
                           ▼
                     AccountLoginPageLoader::load
                           │
                           ▼
                     AccountGuestLoginPageLoadedHook
                           │
                           ▼
                     guest-auth.html.twig ───▶ [画面表示]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| AuthController.php | `src/Storefront/Controller/AuthController.php` | コントローラ | ゲストログインページエンドポイント |
| AccountLoginPageLoader.php | `src/Storefront/Page/Account/Login/AccountLoginPageLoader.php` | ローダー | ログインページデータの読み込み |
| AccountLoginPage.php | `src/Storefront/Page/Account/Login/AccountLoginPage.php` | ページ | ログインページのデータモデル |
| AccountGuestLoginPageLoadedHook.php | `src/Storefront/Page/Account/Login/AccountGuestLoginPageLoadedHook.php` | フック | ページロード後のフック |
| guest-auth.html.twig | `src/Storefront/Resources/views/storefront/page/account/guest-auth.html.twig` | テンプレート | ゲストログインフォーム表示 |
