# 機能設計書 23-注文詳細表示

## 概要

本ドキュメントは、Shopwareストアフロントにおける注文詳細表示機能の設計を記述したものである。本機能は、特定の注文の詳細情報をディープリンクコードを用いて表示し、ゲスト顧客でも注文状況を確認できるようにする。

### 本機能の処理概要

注文詳細表示機能は、deepLinkCodeをURLパラメータとして受け取り、該当する注文の詳細情報を表示する機能を提供する。

**業務上の目的・背景**：ECサイトにおいて、顧客が特定の注文情報に直接アクセスできることは重要である。特にゲスト顧客（会員登録なしで購入した顧客）にとって、注文完了メールに含まれるリンクから直接注文状況を確認できることは、ユーザビリティ向上に大きく寄与する。また、注文番号を口頭で伝えるよりも、ディープリンクをシェアすることで、カスタマーサポートとのコミュニケーションも円滑になる。

**機能の利用シーン**：
- 注文完了メールに含まれるリンクから注文を確認する場合
- ゲスト顧客が注文状況を確認する場合
- 特定の注文を直接参照したい場合
- カスタマーサポートに注文情報を共有する場合

**主要な処理内容**：
1. deepLinkCodeによる注文の特定
2. ゲスト顧客の場合は認証情報（email/zipcode）の検証
3. 注文詳細情報の取得と表示
4. 認証失敗時のゲストログインページへのリダイレクト

**関連システム・外部連携**：
- AccountOrderPageLoader: 注文ページデータ読み込み
- AbstractOrderRoute: 注文データ取得API
- イベントディスパッチャー: AccountOrderPageLoadedEventの発火

**権限による制御**：
- ログイン不要（deepLinkCodeによるアクセス）
- ゲスト顧客の場合はemail/zipcodeによる追加認証

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 21 | 注文履歴ページ | 主画面 | 注文詳細の展開表示（AccountOrderController::orderSingleOverview） |
| 13 | ゲストログインページ | 遷移先画面 | 認証失敗時のリダイレクト先 |

## 機能種別

CRUD操作（Read） / データ表示 / 認証連携

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| deepLinkCode | string | Yes | 注文識別用のユニークコード | URLパス必須 |
| email | string | No | ゲスト認証用メールアドレス | メール形式（ゲスト認証時必須） |
| zipcode | string | No | ゲスト認証用郵便番号 | 文字列（ゲスト認証時必須） |

### 入力データソース

- URLルートパラメータ（deepLinkCode）
- HTTPリクエストパラメータ（Query/POST）
- SalesChannelContext（顧客情報、セッション情報）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| page | AccountOrderPage | 注文一覧ページオブジェクト（1件のみ） |
| page.orders | EntitySearchResult<OrderCollection> | 注文コレクション（1件） |
| page.deepLinkCode | string | ゲスト用ディープリンクコード |

### 出力先

- HTMLレスポンス（Twigテンプレート: `@Storefront/storefront/page/account/order-history/index.html.twig`）
- リダイレクトレスポンス（認証失敗時: `frontend.account.guest.login.page`）

## 処理フロー

### 処理シーケンス

```
1. orderSingleOverview（GET/POST /account/order/{deepLinkCode}）
   └─ AccountOrderPageLoader.loadを試行
      └─ deepLinkCodeで注文をフィルタ
      └─ ゲスト認証情報の検証
   └─ 成功時: AccountOrderPageLoadedHookを発火
   └─ 成功時: order-history/index.html.twigをレンダリング
   └─ 認証失敗時: ゲストログインページへリダイレクト
```

### フローチャート

```mermaid
flowchart TD
    A[注文詳細画面アクセス] --> B[deepLinkCodeをURLから取得]
    B --> C[AccountOrderPageLoader.load]

    C --> D{例外発生?}
    D -->|GuestNotAuthenticatedException| E[ゲストログインページへリダイレクト]
    D -->|WrongGuestCredentialsException| F[ゲストログインページへリダイレクト<br>loginError=true]
    D -->|CustomerAuthThrottledException| G[ゲストログインページへリダイレクト<br>waitTime表示]
    D -->|No| H[AccountOrderPage取得成功]

    E --> I[リダイレクトパラメータ設定]
    F --> I
    G --> I
    I --> J[RedirectResponse]

    H --> K[AccountOrderPageLoadedHook発火]
    K --> L[Twigレンダリング]
    L --> M[HTMLレスポンス]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-23-01 | deepLinkCode必須 | URLにdeepLinkCodeが含まれていること | 常時 |
| BR-23-02 | ゲスト認証 | ゲスト顧客はemail+zipcodeで認証 | ログイン顧客でない場合 |
| BR-23-03 | 認証失敗リダイレクト | 認証失敗時はゲストログインページへリダイレクト | 認証例外発生時 |
| BR-23-04 | スロットリング | 認証試行回数が上限を超えた場合は一定時間待機が必要 | 認証失敗が連続した場合 |
| BR-23-05 | 1件表示 | deepLinkCodeに一致する注文のみ表示 | 常時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 注文取得 | order | SELECT | deepLinkCodeで注文を取得 |
| トランザクション取得 | order_transaction | SELECT | 関連する決済トランザクション |
| 配送情報取得 | order_delivery | SELECT | 関連する配送情報 |
| 明細取得 | order_line_item | SELECT | 注文明細 |

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

#### order

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | * | deepLinkCode = {deepLinkCode} | URLパラメータで指定 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| GUEST_NOT_AUTHENTICATED | 認証エラー | ゲスト認証情報が未提供 | ゲストログインページへリダイレクト |
| WRONG_GUEST_CREDENTIALS | 認証エラー | email/zipcodeが不正 | ゲストログインページへリダイレクト（loginError=true） |
| CUSTOMER_AUTH_THROTTLED | 認証エラー | 認証試行回数超過 | ゲストログインページへリダイレクト（waitTime表示） |

### リトライ仕様

認証失敗時はゲストログインページにリダイレクトし、再認証を促す。スロットリングが発生した場合は、指定された待機時間後に再試行可能。

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

本機能は参照のみのため、トランザクション制御は不要。

## パフォーマンス要件

- ページ表示: 1秒以内
- deepLinkCodeによる検索はインデックスを使用

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

- deepLinkCodeは推測困難なランダム文字列
- ゲスト認証にはemail + zipcodeの組み合わせが必要
- 認証試行のスロットリング（ブルートフォース攻撃対策）
- NO_STORE属性によりブラウザキャッシュ無効化
- robots: noindex,follow（検索エンジンへのインデックス防止）

## 備考

- 注文一覧表示（No.22）と同じページローダーを使用するが、deepLinkCodeによるフィルタが適用される
- リダイレクト時のパラメータでredirectTo/redirectParametersを設定し、認証成功後に元の画面に戻れるようにする
- loginErrorパラメータで認証エラーの表示を制御

---

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

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

### 推奨読解順序

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

注文一覧表示と共通のデータ構造を使用。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | OrderEntity.php | `src/Core/Checkout/Order/OrderEntity.php` | deepLinkCodeプロパティ（84行目） |
| 1-2 | AccountOrderPage.php | `src/Storefront/Page/Account/Order/AccountOrderPage.php` | deepLinkCodeプロパティ |

**読解のコツ**: deepLinkCodeは注文作成時に自動生成されるユニークな文字列で、URLを知っている人のみがアクセスできる仕組み。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | AccountOrderController.php | `src/Storefront/Controller/AccountOrderController.php` | orderSingleOverviewメソッド |

**主要処理フロー**:
1. **134-160行目**: `orderSingleOverview`メソッド - 注文詳細表示処理
2. **143-156行目**: try-catch による認証例外処理
3. **144行目**: AccountOrderPageLoader.load呼び出し
4. **146行目**: AccountOrderPageLoadedHook発火
5. **147-156行目**: 各種例外のハンドリングとリダイレクト

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

注文取得時のdeepLinkCodeフィルタリングを確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | AccountOrderPageLoader.php | `src/Storefront/Page/Account/Order/AccountOrderPageLoader.php` | createCriteriaのdeepLinkCode処理 |

**主要処理フロー**:
- **152-154行目**: deepLinkCodeによるフィルタ追加

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

```
AccountOrderController
    │
    └─ orderSingleOverview (GET/POST /account/order/{deepLinkCode})
           │
           ├─ try
           │      ├─ AccountOrderPageLoader.load
           │      │      ├─ createCriteria
           │      │      │      └─ EqualsFilter('deepLinkCode', $deepLinkCode)
           │      │      └─ AbstractOrderRoute.load
           │      └─ AccountOrderPageLoadedHook dispatch
           │
           └─ catch
                  ├─ GuestNotAuthenticatedException → リダイレクト
                  ├─ WrongGuestCredentialsException → リダイレクト(loginError=true)
                  └─ CustomerAuthThrottledException → リダイレクト(waitTime)
```

### データフロー図

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

URL (/account/order/{deepLinkCode})
        │
        ▼
┌─────────────────────┐
│ AccountOrder        │
│ Controller          │
│ ::orderSingleOverview│
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│ AccountOrderPage    │
│ Loader              │◄──── order (WHERE deepLinkCode = ?)
└─────────┬───────────┘
          │
          ├───────────────────────┬─────────────────────────────────► HTMLレスポンス
          │                       │                                   (認証成功時)
          │                       │
          │                       ▼
          │               ┌─────────────────────┐
          │               │ Twig Template       │
          │               │ (order-history/     │
          │               │  index.html.twig)   │
          │               └─────────────────────┘
          │
          └───────────────────────────────────────────────────────────► リダイレクト
                                                                        (認証失敗時)
                                                                        → frontend.account.guest.login.page
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| AccountOrderController.php | `src/Storefront/Controller/AccountOrderController.php` | ソース | コントローラー（エントリーポイント） |
| AccountOrderPageLoader.php | `src/Storefront/Page/Account/Order/AccountOrderPageLoader.php` | ソース | ページデータ読み込み |
| AccountOrderPage.php | `src/Storefront/Page/Account/Order/AccountOrderPage.php` | ソース | ページビューモデル |
| OrderEntity.php | `src/Core/Checkout/Order/OrderEntity.php` | ソース | 注文エンティティ（deepLinkCode含む） |
| GuestNotAuthenticatedException.php | `src/Core/Checkout/Order/Exception/GuestNotAuthenticatedException.php` | ソース | ゲスト未認証例外 |
| WrongGuestCredentialsException.php | `src/Core/Checkout/Order/Exception/WrongGuestCredentialsException.php` | ソース | ゲスト認証情報不正例外 |
| CustomerAuthThrottledException.php | `src/Core/Checkout/Customer/Exception/CustomerAuthThrottledException.php` | ソース | 認証スロットリング例外 |
| index.html.twig | `src/Storefront/Resources/views/storefront/page/account/order-history/index.html.twig` | テンプレート | 注文詳細表示テンプレート |
