# 画面設計書 8-オフキャンバスカート

## 概要

本ドキュメントは、Shopware 6 Storefrontにおけるオフキャンバスカートの画面設計書である。サイドバー形式で表示されるカートウィジェットであり、ページ遷移なしでカート内容を確認・操作できる。

### 本画面の処理概要

オフキャンバスカートは、商品をカートに追加した際や、ヘッダーのカートアイコンをクリックした際に画面右側からスライドインするサイドバー形式のカート表示である。カート内容の確認、数量変更、プロモーションコード適用、チェックアウトへの遷移が可能。

**業務上の目的・背景**：オフキャンバスカートは、顧客が商品をカートに追加した後の体験を向上させる。フルページ遷移を必要とせずにカート内容を確認できるため、買い物の流れを中断させない。「続けて買い物」と「チェックアウトへ進む」の両方の選択肢を提示することで、顧客の購買意欲を維持しながら追加購入も促進できる。

**画面へのアクセス方法**：商品をカートに追加した後の自動表示、ヘッダーのカートアイコンをクリック、AJAX経由で`/checkout/offcanvas`エンドポイントが呼び出される。

**主要な操作・処理内容**：
1. カート内商品の一覧表示（OffcanvasCartPageLoader）
2. 商品数量の変更
3. 商品の削除
4. プロモーションコードの適用
5. カートページへの遷移
6. チェックアウトへの遷移
7. オフキャンバスを閉じて買い物を続ける

**画面遷移**：
- 遷移元：商品詳細ページ（カート追加後）、ヘッダーカートアイコン
- 遷移先：カートページ、注文確認ページ、元の画面（閉じる操作）

**権限による表示制御**：全ユーザーがアクセス可能。特別な権限制御なし。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 37 | オフキャンバスカート | 主機能 | サイドバー形式のカート表示（CheckoutController::offcanvas） |
| 38 | カート情報ウィジェット | 補助機能 | ヘッダーのカートアイコン更新（CheckoutController::info） |
| 43 | 数量変更 | API連携 | カート内数量の変更 |

## 画面種別

オフキャンバス / ウィジェット

## URL/ルーティング

| 項目 | 値 |
|------|-----|
| URL | `/checkout/offcanvas` |
| ルート名 | `frontend.cart.offcanvas` |
| HTTPメソッド | GET |
| XmlHttpRequest | 必須 |
| SEO | 無効 |

## 入出力項目

### 入力項目

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

### 出力データ

| 項目名 | データソース | 説明 |
|--------|-------------|------|
| page | OffcanvasCartPageLoader | ページ全体のデータオブジェクト |
| page.cart | カートサービス | カートオブジェクト |

## 表示項目

| セクション | 表示項目 | 説明 |
|-----------|---------|------|
| ヘッダー | 閉じるボタン | 「買い物を続ける」リンク（左矢印付き） |
| ヘッダー | カートタイトル | 「ショッピングカート」 |
| ヘッダー | 商品数 | 「（{件数}個）」 |
| フラッシュ | メッセージ | 成功/エラーメッセージ |
| リスト | 商品一覧 | 商品画像、名前、価格、数量、削除ボタン |
| 空状態 | メッセージ | 「カートは空です」 |
| サマリー | 合計金額 | 小計、配送料、合計 |
| アクション | プロモーションフォーム | コード入力と適用ボタン |
| アクション | チェックアウトボタン | 「注文手続きへ進む」 |
| アクション | カートリンク | 「カートを見る」 |

## イベント仕様

### 1-オフキャンバス表示

カートアイコンクリックまたは商品追加後にオフキャンバスが表示される。

**処理フロー**：
1. JavaScriptがクリック/追加イベントをキャッチ
2. AJAX経由で`/checkout/offcanvas`を呼び出し
3. CheckoutController::offcanvasが実行される
4. OffcanvasCartPageLoaderでカートデータを取得
5. CheckoutOffcanvasWidgetLoadedHookを発火
6. offcanvas-cart.html.twigでHTMLをレンダリング
7. 右側からスライドインで表示

### 2-カート情報ウィジェット更新

カート操作後、ヘッダーのカートアイコンのバッジが更新される。

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

### 3-数量変更

数量を変更すると、オフキャンバス全体が再読み込みされる。

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

コードを入力して適用すると、オフキャンバス内で反映される。

### 5-オフキャンバスを閉じる

「買い物を続ける」クリック、オーバーレイクリック、Escキーで閉じる。

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

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

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

## メッセージ仕様

| メッセージ種別 | 条件 | メッセージ内容 |
|--------------|------|--------------|
| 情報 | カート空 | 「カートは空です」 |
| 成功 | 数量変更成功 | 「カートが更新されました」 |
| 成功 | プロモーション適用成功 | 「プロモーションコードが適用されました」 |

## 例外処理

| 例外条件 | 対応 |
|---------|------|
| カート空 | 空メッセージ表示、チェックアウトボタン無効化 |
| AJAX通信エラー | エラーメッセージ表示 |

## 備考

- オフキャンバスはutilities/offcanvas.html.twigを継承
- フラッシュメッセージはapp.flashesで取得
- カート空の場合、チェックアウトボタンにdisabledクラスが付与される
- hidden-line-items-informationで非表示ラインアイテム情報を出力

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | OffcanvasCartPage.php | `src/Storefront/Page/Checkout/Offcanvas/OffcanvasCartPage.php` | ページオブジェクトの構造 |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | CheckoutController.php | `src/Storefront/Controller/CheckoutController.php` | offcanvasメソッド（278-308行目） |
| 2-2 | CheckoutController.php | `src/Storefront/Controller/CheckoutController.php` | infoメソッド（255-276行目） |

**主要処理フロー**:
1. **285-287行目**: OffcanvasCartPageLoaderでカートデータ取得
2. **289行目**: CheckoutOffcanvasWidgetLoadedHookでフック処理
3. **291-293行目**: カートとエラーの取得
4. **295-303行目**: リダイレクトループ防止処理
5. **307行目**: テンプレートレンダリング

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | offcanvas-cart.html.twig | `src/Storefront/Resources/views/storefront/component/checkout/offcanvas-cart.html.twig` | オフキャンバステンプレート |

**主要処理フロー**:
- **1行目**: offcanvas.html.twigを継承
- **17-76行目**: カート内容の表示（空/有の分岐）
- **84-133行目**: プロモーションコードフォーム
- **135-153行目**: チェックアウト/カートリンク

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

```
[カートアイコン/商品追加]
    |
    v
JavaScript (AJAX Request)
    |
    v
CheckoutController::offcanvas()
    |
    +-- OffcanvasCartPageLoader::load()
    |       |
    |       +-- CartService::getCart()
    |
    +-- CheckoutOffcanvasWidgetLoadedHook
    |
    +-- addCartErrors()
    |
    +-- renderStorefront()
            +-- offcanvas-cart.html.twig
                    |
                    v
            [Offcanvas Sidebar]
```

### データフロー図

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

カートアイコン    -->  CheckoutController::offcanvas()
クリック (AJAX)              |
                            v
                   OffcanvasCartPageLoader
                            |
                            v
                      CartService
                            |
                            v
                   OffcanvasCartPage     -->  HTML Fragment
                            |
                            v
                   offcanvas-cart.html.twig
                            |
                            v
                   [Sidebar Display]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| CheckoutController.php | `src/Storefront/Controller/CheckoutController.php` | コントローラー | ルーティングエントリーポイント |
| OffcanvasCartPageLoader.php | `src/Storefront/Page/Checkout/Offcanvas/OffcanvasCartPageLoader.php` | ページローダー | ページデータの構築 |
| OffcanvasCartPage.php | `src/Storefront/Page/Checkout/Offcanvas/OffcanvasCartPage.php` | データ構造 | ページオブジェクト定義 |
| offcanvas-cart.html.twig | `src/Storefront/Resources/views/storefront/component/checkout/offcanvas-cart.html.twig` | テンプレート | オフキャンバスHTML |
| offcanvas.html.twig | `src/Storefront/Resources/views/storefront/utilities/offcanvas.html.twig` | テンプレート | オフキャンバス基盤 |
| offcanvas-cart-summary.html.twig | `src/Storefront/Resources/views/storefront/component/checkout/offcanvas-cart-summary.html.twig` | テンプレート | サマリー表示 |
| cart-widget.html.twig | `src/Storefront/Resources/views/storefront/layout/header/actions/cart-widget.html.twig` | テンプレート | ヘッダーカートアイコン |
