# 画面設計書 21-注文履歴ページ

## 概要

本ドキュメントは、Shopware 6 Storefrontの注文履歴ページ（Order History Page）の画面設計書である。顧客がマイアカウントから過去の注文を一覧表示・確認するための画面について、機能仕様、データ仕様、画面遷移等を記載する。

### 本画面の処理概要

注文履歴ページは、ログイン済み顧客が自身の過去の注文を確認・管理するための重要な画面である。

**業務上の目的・背景**：顧客は購入後に注文状況の確認、配送状況の追跡、請求書のダウンロード、注文のキャンセルなどを行う必要がある。この画面は顧客のセルフサービスを実現し、カスタマーサポートへの問い合わせを削減する役割を担う。また、ゲスト顧客がdeepLinkCodeを使用して注文を確認できる機能も提供する。

**画面へのアクセス方法**：
- ログイン後、マイアカウントメニューから「注文履歴」をクリック
- ヘッダーのアカウントアイコンからアカウントダッシュボードを経由してアクセス
- ゲスト顧客の場合、注文完了メールに含まれるdeepLinkCodeを使用してアクセス（frontend.account.order.single.page）

**主要な操作・処理内容**：
1. 注文一覧の表示（ページネーション付き）
2. 個別注文の詳細展開表示（配送情報、商品明細、ドキュメント）
3. 注文のキャンセル（cancel状態への遷移）
4. 支払い方法の変更（注文編集画面への遷移）
5. 請求書・納品書等のドキュメントダウンロード
6. デジタル商品のダウンロード

**画面遷移**：
- 遷移元：アカウントホームページ、注文完了ページ、ゲストログインページ
- 遷移先：注文編集ページ（支払い変更）、ホームページ（ログアウト時）

**権限による表示制御**：
- ログインユーザー：全注文履歴を表示
- ゲストユーザー：deepLinkCodeに紐づく単一注文のみ表示
- 未ログインユーザー：ゲストログインページへリダイレクト

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 22 | 注文一覧表示 | 主機能 | 過去の注文一覧表示（AccountOrderController::orderOverview） |
| 23 | 注文詳細表示 | 補助機能 | 注文詳細の展開表示（AccountOrderController::orderSingleOverview） |
| 24 | 注文キャンセル | 補助機能 | 注文のキャンセル（AccountOrderController::cancelOrder） |

## 画面種別

一覧 / 詳細

## URL/ルーティング

| ルート名 | URL | HTTPメソッド | 説明 |
|----------|-----|--------------|------|
| frontend.account.order.page | /account/order | GET, POST | 注文一覧表示 |
| frontend.account.order.single.page | /account/order/{deepLinkCode} | GET, POST | 単一注文表示（ゲスト用） |
| frontend.account.order.cancel | /account/order/cancel | POST | 注文キャンセル |

## 入出力項目

### 入力項目

| 項目名 | パラメータ名 | 型 | 必須 | 説明 |
|--------|-------------|-----|------|------|
| ページ番号 | p | integer | - | ページネーション用のページ番号 |
| ディープリンクコード | deepLinkCode | string | - | ゲスト注文確認用コード |
| メールアドレス | email | string | - | ゲスト認証用 |
| 郵便番号 | zipcode | string | - | ゲスト認証用 |
| 注文ID | orderId | string | - | キャンセル対象注文ID |

### 出力項目

| 項目名 | 型 | 説明 |
|--------|-----|------|
| page | AccountOrderPage | 注文一覧ページオブジェクト |
| page.orders | EntitySearchResult<OrderCollection> | 注文コレクション |

## 表示項目

### 注文一覧

| 項目名 | データソース | 説明 |
|--------|-------------|------|
| 注文番号 | order.orderNumber | 注文の識別番号 |
| 注文日時 | order.orderDateTime | 注文確定日時 |
| 注文ステータス | order.stateMachineState.name | 注文状態（オープン、処理中、完了、キャンセル等） |
| 支払いステータス | order.primaryOrderTransaction.stateMachineState.name | 支払い状態（未払い、支払済み等） |
| 配送ステータス | order.primaryOrderDelivery.stateMachineState.name | 配送状態（未発送、発送済み等） |
| 合計金額 | order.amountTotal | 注文合計金額 |
| 通貨 | order.currency | 通貨情報 |
| 支払い方法 | order.primaryOrderTransaction.paymentMethod.name | 使用した支払い方法 |
| 配送方法 | order.primaryOrderDelivery.shippingMethod.name | 使用した配送方法 |

### 注文詳細（展開時）

| 項目名 | データソース | 説明 |
|--------|-------------|------|
| 商品名 | lineItem.label | 注文商品名 |
| 商品画像 | lineItem.cover | 商品サムネイル画像 |
| 数量 | lineItem.quantity | 購入数量 |
| 単価 | lineItem.unitPrice | 商品単価 |
| 小計 | lineItem.totalPrice | 商品小計 |
| 配送先住所 | order.addresses | 配送先住所情報 |
| ドキュメント | order.documents | 請求書、納品書等 |
| ダウンロード | lineItem.downloads | デジタル商品ダウンロードリンク |

## イベント仕様

### 1-注文詳細展開

注文一覧の各注文行をクリックすると、該当注文の詳細情報（商品明細、配送情報、ドキュメント）が展開表示される。JavaScriptによるアコーディオン形式で実装。

### 2-ページネーション

1ページあたり10件（DEFAULT_LIMIT）で表示。ページ番号をクリックまたはフォーム送信でページ切り替え。form-ajax-submitによる非同期更新。

### 3-注文キャンセル

キャンセルボタン押下で確認モーダル表示後、frontend.account.order.cancelへPOST。キャンセル成功後、注文一覧ページへリダイレクト。

### 4-支払い方法変更

「支払い方法を変更」ボタン押下で注文編集ページ（frontend.account.edit-order.page）へ遷移。

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 注文キャンセル | order | UPDATE | 注文ステータスをcancelledに更新 |
| 注文キャンセル | state_machine_history | INSERT | 状態遷移履歴を記録 |

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

#### order

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | state_id | cancelled状態のID | 注文キャンセル時 |
| UPDATE | updated_at | 現在日時 | 自動更新 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|----------|
| account.ordersTitle | 表示 | 注文履歴 | ページタイトル |
| account.ordersWelcome | 表示 | 注文履歴説明文 | ページ説明 |
| account.ordersInfoEmpty | 警告 | 注文がありません | 注文が0件の場合 |
| error.message-default | エラー | エラーが発生しました | 処理失敗時 |

## 例外処理

| 例外 | 原因 | 処理内容 |
|------|------|----------|
| CustomerNotLoggedInException | 未ログイン状態でアクセス | ログインページへリダイレクト |
| GuestNotAuthenticatedException | ゲスト認証失敗 | ゲストログインページへリダイレクト |
| WrongGuestCredentialsException | ゲスト認証情報不正 | エラーメッセージ表示、再認証を促す |
| CustomerAuthThrottledException | 認証試行回数超過 | 待機時間を表示、再試行を制限 |

## 備考

- 注文一覧はcreatedAtとorderDateTimeの両方で降順ソートされる
- ゲストユーザーはdeepLinkCodeを使用して特定の注文のみ閲覧可能
- 注文キャンセルはCancelOrderRouteRequestEventを通じて拡張可能
- v6.8.0でAccountOrderDetailPageLoaderは削除予定

---

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

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

### 推奨読解順序

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

まず、注文データの構造を理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | AccountOrderPage.php | `src/Storefront/Page/Account/Order/AccountOrderPage.php` | Pageオブジェクトの構造、ordersプロパティ |
| 1-2 | OrderEntity.php | `src/Core/Checkout/Order/OrderEntity.php` | 注文エンティティの全プロパティ |

**読解のコツ**: Shopwareのエンティティは多数のリレーションを持つ。associationを追うことでデータ構造の全体像が掴める。

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

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

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

**主要処理フロー**:
1. **76-102行**: orderOverview() - 注文一覧ページのメイン処理
2. **104-132行**: cancelOrder() - 注文キャンセル処理
3. **134-160行**: orderSingleOverview() - 単一注文表示（ゲスト用）

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | AccountOrderPageLoader.php | `src/Storefront/Page/Account/Order/AccountOrderPageLoader.php` | load()メソッド、getOrders()、createCriteria() |

**主要処理フロー**:
- **45-67行**: load() - ページ読み込みのメイン処理
- **91-110行**: getOrders() - 注文データ取得
- **112-157行**: createCriteria() - 検索条件の構築（アソシエーション、ソート、ページネーション）

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | index.html.twig | `src/Storefront/Resources/views/storefront/page/account/order-history/index.html.twig` | メインテンプレート、ブロック構造 |
| 4-2 | order-item.html.twig | `src/Storefront/Resources/views/storefront/page/account/order-history/order-item.html.twig` | 注文行の表示 |
| 4-3 | order-detail.html.twig | `src/Storefront/Resources/views/storefront/page/account/order-history/order-detail.html.twig` | 詳細展開部分 |

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

```
AccountOrderController::orderOverview()
    │
    ├─ AccountOrderPageLoader::load()
    │      ├─ GenericPageLoaderInterface::load()
    │      ├─ setMetaInformation()
    │      ├─ getOrders()
    │      │      ├─ createCriteria()
    │      │      ├─ OrderRouteRequestEvent dispatch
    │      │      └─ AbstractOrderRoute::load()
    │      └─ AccountOrderPageLoadedEvent dispatch
    │
    └─ renderStorefront('@Storefront/storefront/page/account/order-history/index.html.twig')

AccountOrderController::cancelOrder()
    │
    ├─ CancelOrderRouteRequestEvent dispatch
    ├─ AbstractCancelOrderRoute::cancel()
    └─ redirectToRoute()
```

### データフロー図

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

Request (p, deepLinkCode)
         │
         ▼
 AccountOrderController
         │
         ▼
 AccountOrderPageLoader::load()
         │
         ├─► GenericPageLoader ──► Page基本情報
         │
         └─► AbstractOrderRoute::load()
                    │
                    ▼
              OrderRepository
                    │
                    ▼
              OrderCollection ───────────────────► AccountOrderPage
                                                        │
                                                        ▼
                                              index.html.twig
                                                        │
                                                        ▼
                                                   Response
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| 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` | ページエンティティ | ページデータの型定義 |
| AbstractOrderRoute.php | `src/Core/Checkout/Order/SalesChannel/AbstractOrderRoute.php` | Store API | 注文データ取得API |
| AbstractCancelOrderRoute.php | `src/Core/Checkout/Order/SalesChannel/AbstractCancelOrderRoute.php` | Store API | 注文キャンセルAPI |
| index.html.twig | `src/Storefront/Resources/views/storefront/page/account/order-history/index.html.twig` | テンプレート | メイン画面テンプレート |
| order-item.html.twig | `src/Storefront/Resources/views/storefront/page/account/order-history/order-item.html.twig` | テンプレート | 注文行テンプレート |
| order-detail.html.twig | `src/Storefront/Resources/views/storefront/page/account/order-history/order-detail.html.twig` | テンプレート | 注文詳細テンプレート |
| order-detail-list.html.twig | `src/Storefront/Resources/views/storefront/page/account/order-history/order-detail-list.html.twig` | テンプレート | 商品明細テンプレート |
| order-detail-document.html.twig | `src/Storefront/Resources/views/storefront/page/account/order-history/order-detail-document.html.twig` | テンプレート | ドキュメント表示テンプレート |
