# 画面設計書 7-カートページ

## 概要

本ドキュメントは、Shopware 6 Storefrontにおけるカートページの画面設計書である。ショッピングカートの内容を表示・編集し、チェックアウトへ進むための画面である。

### 本画面の処理概要

カートページは、顧客が選択した商品の一覧を表示し、数量変更、商品削除、プロモーションコード適用などの操作を提供する画面である。注文確認画面への入口となる重要な画面である。

**業務上の目的・背景**：カートページは購入プロセスの中間ステップとして、顧客が購入予定の商品を確認・調整するための画面である。カート放棄率の低減が重要な課題であり、明確な価格表示、簡単な数量変更、プロモーションコードの適用しやすさなどが求められる。配送料の事前確認機能により、チェックアウト時の離脱を防ぐ。

**画面へのアクセス方法**：ヘッダーのカートアイコンをクリック、オフキャンバスカートの「カートを見る」リンク、商品追加後のリダイレクト、URL直接アクセス（`/checkout/cart`）でアクセスする。

**主要な操作・処理内容**：
1. カート内商品の一覧表示（CheckoutCartPageLoader）
2. 商品数量の変更
3. 商品の削除
4. プロモーションコードの適用
5. 配送先国・配送方法・支払方法の事前選択
6. チェックアウトへ進む

**画面遷移**：
- 遷移元：商品詳細ページ（カート追加後）、オフキャンバスカート、ヘッダーカートリンク
- 遷移先：注文確認ページ、チェックアウト登録ページ（未ログイン時）、商品詳細ページ

**権限による表示制御**：全ユーザーがアクセス可能。ログイン状態により配送先国選択の表示有無が変化する。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 35 | カート表示 | 主機能 | ショッピングカートの内容表示（CheckoutController::cartPage） |
| 43 | 数量変更 | 補助機能 | カート内商品の数量変更（CartLineItemController::changeQuantity） |
| 41 | 商品削除 | 補助機能 | カートからの商品削除（CartLineItemController::deleteLineItem） |
| 46 | プロモーションコード追加 | 補助機能 | クーポンコードの適用（CartLineItemController::addPromotion） |
| 47 | 注文確認 | 遷移先機能 | 注文確認画面への遷移 |

## 画面種別

一覧 / 編集

## URL/ルーティング

| 項目 | 値 |
|------|-----|
| URL | `/checkout/cart` |
| ルート名 | `frontend.checkout.cart.page` |
| HTTPメソッド | GET |
| HTTPキャッシュ | 無効（_noStore） |
| SEO | 無効 |

## 入出力項目

### 入力項目

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

### 出力データ

| 項目名 | データソース | 説明 |
|--------|-------------|------|
| page | CheckoutCartPageLoader | ページ全体のデータオブジェクト |
| page.cart | カートサービス | カートオブジェクト（ラインアイテム含む） |
| page.paymentMethods | 設定 | 利用可能な支払方法 |
| page.shippingMethods | 設定 | 利用可能な配送方法 |
| page.countries | 設定 | 配送可能な国一覧 |

## 表示項目

| セクション | 表示項目 | 説明 |
|-----------|---------|------|
| ヘッダー | 共通ヘッダー | ロゴ、ナビゲーション、検索、カート |
| メイン | カートヘッダー | 「ショッピングカート（{件数}個）」 |
| メイン | 商品テーブルヘッダー | 商品、数量、単価、合計等のカラム |
| メイン | 商品一覧 | 商品画像、名前、バリアント、価格、数量選択、削除ボタン |
| メイン | 商品番号で追加 | 商品番号入力フィールド |
| メイン | 配送料計算 | 国、配送方法、支払方法の選択 |
| サイドバー | プロモーションコード | コード入力フィールド |
| サイドバー | 注文サマリー | 小計、配送料、税、合計 |
| サイドバー | チェックアウトボタン | 「注文手続きへ進む」 |
| フッター | 共通フッター | フッターリンク |

## イベント仕様

### 1-カートページ表示

カートURLにアクセスすると、CheckoutController::cartPageメソッドが実行される。

**処理フロー**：
1. CheckoutCartPageLoaderがリクエストとSalesChannelContextを受け取る
2. CartServiceからカートを取得
3. 支払方法、配送方法、国一覧を取得
4. カートエラーの処理（配送方法変更等）
5. CheckoutCartPageLoadedHookを発火
6. Twigテンプレートでレンダリング

### 2-数量変更

数量セレクトボックスを変更すると、商品の数量が更新される。

**エンドポイント**: `/checkout/line-item/change-quantity/{id}`
**ルート名**: `frontend.checkout.line-item.change-quantity`
**HTTPメソッド**: POST

### 3-商品削除

削除ボタン（ゴミ箱アイコン）をクリックすると、商品がカートから削除される。

**エンドポイント**: `/checkout/line-item/delete/{id}`
**ルート名**: `frontend.checkout.line-item.delete`
**HTTPメソッド**: POST/DELETE

### 4-プロモーションコード適用

プロモーションコードを入力して適用すると、割引が適用される。

**エンドポイント**: `/checkout/promotion/add`
**ルート名**: `frontend.checkout.promotion.add`
**HTTPメソッド**: POST

### 5-配送設定変更

配送先国、支払方法、配送方法を変更すると、カートの計算が更新される。

**エンドポイント**: `/checkout/configure`
**ルート名**: `frontend.checkout.configure`

### 6-チェックアウトへ進む

「注文手続きへ進む」ボタンをクリックすると、注文確認ページまたは登録ページへ遷移する。

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| ページ表示 | cart | SELECT | カートデータ参照 |
| 数量変更 | cart | UPDATE | カートラインアイテム更新 |
| 商品削除 | cart | UPDATE | カートからラインアイテム削除 |
| プロモーション適用 | cart | UPDATE | プロモーションラインアイテム追加 |

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

#### cart（数量変更時）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | line_items | 数量変更後のラインアイテムJSON | カート全体が更新 |
| UPDATE | price | 再計算後の価格 | 自動計算 |

## メッセージ仕様

| メッセージ種別 | 条件 | メッセージ内容 |
|--------------|------|--------------|
| 情報 | カート空 | 「カートは空です」 |
| 成功 | 数量変更成功 | 「カートが更新されました」 |
| 成功 | プロモーション適用成功 | 「プロモーションコードが適用されました」 |
| エラー | プロモーション無効 | 「このプロモーションコードは無効です」 |
| エラー | 在庫不足 | 「在庫が不足しています」 |

## 例外処理

| 例外条件 | 対応 |
|---------|------|
| カート空 | 空カートメッセージと商品番号入力フォームを表示 |
| ラインアイテム未発見 | CartException::lineItemNotFound |
| 配送方法/支払方法変更エラー | エラー表示後、ページリロード |

## 備考

- カートはセッションまたはデータベースに保存される（設定による）
- 配送料は物理商品がある場合のみ計算される（IS_PHYSICAL状態チェック）
- 税表示は販売チャネル設定（税込/税抜表示）による
- カートエラー発生時は自動リロードでエラーを解消

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | CheckoutCartPage.php | `src/Storefront/Page/Checkout/Cart/CheckoutCartPage.php` | ページオブジェクトの構造 |
| 1-2 | Cart.php | `src/Core/Checkout/Cart/Cart.php` | カートオブジェクト、LineItemCollection |

**読解のコツ**: CartオブジェクトはLineItemCollectionを持ち、各ラインアイテムが商品情報、数量、価格を保持する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | CheckoutController.php | `src/Storefront/Controller/CheckoutController.php` | cartPageメソッド（74-103行目） |

**主要処理フロー**:
1. **81-83行目**: CheckoutCartPageLoaderでページデータ取得
2. **84-85行目**: カートとカートエラーの取得
3. **87行目**: CheckoutCartPageLoadedHookでフック処理
4. **89行目**: addCartErrorsでエラーメッセージ追加
5. **91-99行目**: リダイレクトループ防止とリロード処理
6. **102行目**: テンプレートレンダリング

#### Step 3: カート操作を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | CartLineItemController.php | `src/Storefront/Controller/CartLineItemController.php` | changeQuantity, deleteLineItem, addPromotion メソッド |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | index.html.twig | `src/Storefront/Resources/views/storefront/page/checkout/cart/index.html.twig` | メインテンプレート |

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

```
CheckoutController::cartPage()
    |
    +-- CheckoutCartPageLoader::load()
    |       |
    |       +-- CartService::getCart()
    |       +-- PaymentMethodRoute::load()
    |       +-- ShippingMethodRoute::load()
    |       +-- CountryRoute::load()
    |
    +-- CheckoutCartPageLoadedHook
    |
    +-- addCartErrors()
    |
    +-- routeNeedsReload() [条件付きリダイレクト]
    |
    +-- renderStorefront()
            +-- cart/index.html.twig
```

### データフロー図

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

GET /checkout/cart -->  CheckoutController::cartPage()
                             |
                             v
                   CheckoutCartPageLoader
                             |
                   +---------+---------+
                   |         |         |
                CartService  Payment  Shipping
                   |         Methods  Methods
                   v
            CheckoutCartPage      -->  HTML Response
                   |
                   v
            cart/index.html.twig
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| CheckoutController.php | `src/Storefront/Controller/CheckoutController.php` | コントローラー | ルーティングエントリーポイント |
| CartLineItemController.php | `src/Storefront/Controller/CartLineItemController.php` | コントローラー | カート操作 |
| CheckoutCartPageLoader.php | `src/Storefront/Page/Checkout/Cart/CheckoutCartPageLoader.php` | ページローダー | ページデータの構築 |
| CheckoutCartPage.php | `src/Storefront/Page/Checkout/Cart/CheckoutCartPage.php` | データ構造 | ページオブジェクト定義 |
| index.html.twig | `src/Storefront/Resources/views/storefront/page/checkout/cart/index.html.twig` | テンプレート | メインテンプレート |
| line-item.html.twig | `src/Storefront/Resources/views/storefront/component/line-item/line-item.html.twig` | テンプレート | ラインアイテム表示 |
| summary.html.twig | `src/Storefront/Resources/views/storefront/page/checkout/summary.html.twig` | テンプレート | 注文サマリー |
