# 機能設計書 45-カート削除

## 概要

本ドキュメントは、ショッピングカート全体を削除（空にする）する機能の設計を定義するものである。

### 本機能の処理概要

顧客のカートを完全に削除し、新規の空のカート状態にする機能である。

**業務上の目的・背景**：顧客がカート内のすべての商品を一度に削除して、買い物をやり直したい場合に対応する機能である。個別の商品を一つずつ削除する手間を省き、ワンクリックでカートを空にできることで、ユーザー体験を向上させる。また、テスト目的や管理目的でカートをリセットする際にも使用される。

**機能の利用シーン**：カートページで「カートを空にする」ボタンをクリックした際に実行される。購入予定を全面的に見直す場合や、誤って多くの商品をカートに追加してしまった場合に使用される。

**主要な処理内容**：
1. CartServiceを通じてカート削除処理を実行
2. カート永続化ストレージからカートデータを削除
3. CartDeletedEventを発火
4. レスポンスを返却

**関連システム・外部連携**：カート永続化システム（Redis/Database）との連携

**権限による制御**：特別な権限制御はなく、カートの所有者（セッション保持者）であれば実行可能

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 7 | カートページ | 主画面 | カートを空にする操作 |

## 機能種別

CRUD操作（Delete）/ データ削除

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| なし | - | - | カートはセッショントークンから自動特定 | - |

### 入力データソース

- SalesChannelContext: リクエストから自動解決（カートトークンを含む）
- Request: HTTPリクエストオブジェクト

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| redirect | Response | リダイレクトレスポンス（通常はカートページまたは前のページ） |

### 出力先

- HTTPレスポンス（リダイレクトまたはAJAXレスポンス）

## 処理フロー

### 処理シーケンス

```
1. リクエスト受信
   └─ POSTメソッドで /checkout/cart/delete にアクセス
2. カート削除実行
   └─ CartService::deleteCart() を呼び出し
3. 永続化ストレージから削除
   └─ CartPersister::delete() でカートデータを削除
4. イベント発火
   └─ CartDeletedEvent を発火
5. レスポンス返却
   └─ createActionResponse() でリダイレクトまたはJSONレスポンスを返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始: deleteCart] --> B[CartService::deleteCart 呼び出し]
    B --> C[CartDeleteRoute::delete]
    C --> D[CartLocker::locked - 排他制御]
    D --> E[CartPersister::delete]
    E --> F[CartDeletedEvent発火]
    F --> G[NoContentResponse返却]
    G --> H[createActionResponse]
    H --> I[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-45-01 | トークン特定 | カートはセッショントークンにより特定される | 常時 |
| BR-45-02 | 完全削除 | カートデータは永続化ストレージから完全に削除される | 常時 |
| BR-45-03 | イベント通知 | 削除後にCartDeletedEventが発火される | 削除成功時 |

### 計算ロジック

カート削除後は計算処理は発生しない。新しいカートが必要な場合は、次回カートアクセス時に自動生成される。

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| カート削除 | cart | DELETE | カートレコードの削除 |

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

#### cart

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| DELETE | - | WHERE token = {session_token} | カート全体を削除 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | システムエラー | 永続化ストレージへのアクセスエラー | システムエラーメッセージを表示 |

### リトライ仕様

リトライは実装されていない。エラー発生時はユーザーに再操作を促す。

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

CartLockerを使用して、カート操作中の排他制御を実施。同一カートに対する同時操作を防止する。

## パフォーマンス要件

- レスポンス時間: 300ms以内
- 単純な削除処理のため高速

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

- セッションベースのカート所有者確認（トークン）
- CSRFトークン検証（Symfony標準）
- XmlHttpRequest ヘッダーによるAJAXリクエスト識別

## 備考

- カート削除後、同一セッションで再度商品を追加すると、新しいカートが自動生成される
- フラッシュメッセージは設定されない（シンプルな削除操作）

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | CartLineItemController.php | `src/Storefront/Controller/CartLineItemController.php` | deleteCartメソッドがエントリーポイント |

**主要処理フロー**:
1. **74-80行目**: deleteCartメソッド全体
2. **77行目**: CartService::deleteCart呼び出し
3. **79行目**: createActionResponseでレスポンス生成

**読解のコツ**: deleteCartは非常にシンプルなメソッドで、CartServiceに処理を委譲するのみである。

#### Step 2: サービス層を理解する

CartServiceがどのように削除を実行するかを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | CartService.php | `src/Core/Checkout/Cart/SalesChannel/CartService.php` | deleteCart()メソッドの実装 |

**主要処理フロー**:
- **177-180行目**: deleteCart()メソッド
- **179行目**: deleteRouteへの委譲

#### Step 3: ルート実装を理解する

実際の削除処理とイベント発火を行うルートクラスを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | CartDeleteRoute.php | `src/Core/Checkout/Cart/SalesChannel/CartDeleteRoute.php` | 削除処理の実装 |

**主要処理フロー**:
- **36-47行目**: delete()メソッド全体
- **39行目**: CartLockerによる排他制御開始
- **40行目**: CartPersister::delete()でカートを削除
- **42-43行目**: CartDeletedEvent発火
- **45行目**: NoContentResponse返却

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

```
CartLineItemController::deleteCart()
    │
    └─ CartService::deleteCart()
           │
           └─ CartDeleteRoute::delete()
                  │
                  ├─ CartLocker::locked() - 排他制御
                  │
                  ├─ CartPersister::delete() - カート削除
                  │
                  ├─ EventDispatcher::dispatch(CartDeletedEvent)
                  │
                  └─ NoContentResponse
```

### データフロー図

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

SalesChannelContext ────▶ CartLineItemController        ───▶ リダイレクトレスポンス
  │                              │                                    │
  └─ token                       ▼                                    │
                         CartService::deleteCart()                    │
                                 │                                    │
                                 ▼                                    │
                         CartDeleteRoute::delete()                    │
                                 │                                    │
                                 ▼                                    │
                         CartPersister::delete()                      │
                                 │                                    │
                                 ▼                                    │
                         cart テーブルから削除                         │
                                 │                                    │
                                 ▼                                    │
                         CartDeletedEvent                             ▼
                                                            NoContentResponse
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| CartLineItemController.php | `src/Storefront/Controller/CartLineItemController.php` | コントローラー | HTTPリクエスト処理 |
| CartService.php | `src/Core/Checkout/Cart/SalesChannel/CartService.php` | サービス | カート操作のファサード |
| CartDeleteRoute.php | `src/Core/Checkout/Cart/SalesChannel/CartDeleteRoute.php` | ルート | Store API実装、イベント発火 |
| AbstractCartPersister.php | `src/Core/Checkout/Cart/AbstractCartPersister.php` | サービス | カート永続化・削除 |
| CartLocker.php | `src/Core/Checkout/Cart/CartLocker.php` | サービス | カート操作の排他制御 |
| CartDeletedEvent.php | `src/Core/Checkout/Cart/Event/CartDeletedEvent.php` | イベント | カート削除イベント |
| NoContentResponse.php | `src/Core/System/SalesChannel/NoContentResponse.php` | レスポンス | 204 No Contentレスポンス |
