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

## 概要

本ドキュメントは、ECモバイルアプリにおけるカート内の全商品を一括削除する機能について設計仕様を定義する。

### 本機能の処理概要

本機能は、ショッピングカートに追加された全ての商品を一括で削除し、カートを空の状態にする機能である。

**業務上の目的・背景**：ECサイトにおいて、ユーザーがカート内容を全てリセットしたい場合がある。商品の再検討、別の購入プランへの変更、または単純なリセット操作として、全商品を一度に削除できる機能は利便性を高める。個別削除を繰り返す手間を省き、効率的なカート管理を実現する。

**機能の利用シーン**：ユーザーが購入予定を大幅に変更したい場合、カートに多数の商品が入っている状態で一からやり直したい場合に利用される。例えば、セール終了後に価格が変わった商品群を全て削除し、再度商品選択をやり直す場合などに活用される。

**主要な処理内容**：
1. カート画面にて「Empty Cart」ボタンを押下
2. 全削除確認ダイアログを表示（誤操作防止）
3. ユーザーが「Yes」を選択すると、RemoveAllCartItemEventを発行
4. GraphQL API経由でサーバーに全削除リクエストを送信
5. 成功時はカートを空にし、空カート画面を表示
6. 成功メッセージを表示し、カート総数を0に更新

**関連システム・外部連携**：Bagisto GraphQL APIとの連携により、`removeAllCartItem` mutationを使用してカート全体を削除する。

**権限による制御**：ゲストユーザー・ログインユーザーいずれも本機能を利用可能。自身のカートのみ操作可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 12 | カート画面 | 主画面 | カート内の全商品一括削除処理 |

## 機能種別

CRUD操作（Delete）/ 確認ダイアログ / 一括処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| なし | - | - | パラメータ不要（セッション/認証で特定） | - |

### 入力データソース

画面操作（「Empty Cart」ボタン押下 → 確認ダイアログで「Yes」選択）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| success | bool | 処理成功可否 |
| message | String | 処理結果メッセージ |

### 出力先

- 画面表示（空カート画面への遷移）
- グローバルカート数表示の更新（0に設定）
- SharedPreferences（カート数を0に更新）

## 処理フロー

### 処理シーケンス

```
1. ユーザーが「Empty Cart」ボタンを押下
   └─ ButtonView._onPressAllRemove呼び出し
2. 全削除確認ダイアログを表示
   └─ AlertDialog表示（Yes/No選択肢）
3. ユーザーが「Yes」を選択
   └─ ダイアログを閉じ、RemoveAllCartItemEventを発行
4. CartScreenBlocがイベントを受信
   └─ repository.removeAllCartItemを呼び出し
5. CartScreenRepositoryがApiClientを経由でAPI呼び出し
   └─ GraphQL mutation removeAllCartItemを実行
6. 成功時: RemoveAllCartItemState.successを発行
   └─ カートデータを再取得（空になる）
7. 空カート画面を表示、成功メッセージを表示
8. カート総数を0に設定
```

### フローチャート

```mermaid
flowchart TD
    A[Empty Cartボタン押下] --> B[確認ダイアログ表示]
    B --> C{ユーザー選択}
    C -->|Yes| D[RemoveAllCartItemEvent発行]
    C -->|No| E[ダイアログを閉じる]
    D --> F[CartScreenBloc処理]
    F --> G[API呼び出し]
    G --> H{成功?}
    H -->|Yes| I[RemoveAllCartItemState.success]
    I --> J[カート数を0に設定]
    J --> K[カートデータ再取得]
    K --> L[空カート画面表示]
    L --> M[成功メッセージ表示]
    H -->|No| N[RemoveAllCartItemState.fail]
    N --> O[エラーメッセージ表示]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-023-01 | 削除確認 | 全削除前に確認ダイアログを表示し、誤操作を防止 | Empty Cartボタン押下時 |
| BR-023-02 | 全商品削除 | カート内の全商品を一括で削除 | API成功時 |
| BR-023-03 | カート数リセット | カート総数を0にリセット | 削除成功時 |
| BR-023-04 | 空カート表示 | 削除後は空カート画面を表示 | 削除成功時 |

### 計算ロジック

削除後のカート合計金額 = 0（全商品削除のため）

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| カートアイテム全削除 | cart_items | DELETE | 当該カートの全アイテムを削除 |
| カート更新 | carts | UPDATE | カート情報をリセット |

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

#### cart_items

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| DELETE | - | cart_id = 当該カートID | 全レコードを削除 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ネットワークエラー | API通信失敗 | エラーメッセージを表示 |
| - | セッション切れ | カートセッションが無効 | エラー表示 |

### リトライ仕様

自動リトライは行わない。ユーザーに再操作を促す。

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

サーバー側でトランザクション管理。cart_itemsテーブルの全削除とcartsテーブルの更新は同一トランザクション内で実行される。

## パフォーマンス要件

- API応答時間: 3秒以内を目標（大量アイテムの場合を考慮）
- UI応答: 確認ダイアログは即座に表示

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

- 認証: ゲストユーザーはセッションベース、ログインユーザーはトークン認証
- アクセス権限: 自身のカートのみ操作可能

## 備考

全削除操作は取り消し不可。削除した商品群を再度購入するには、各商品詳細画面から再追加が必要。

---

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

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

### 推奨読解順序

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

API応答のデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | graphql_base_model.dart | `lib/data_model/graphql_base_model.dart` | BaseModelクラス（success, messageフィールド） |

**読解のコツ**: 全削除APIはBaseModelを返し、CartModelは含まない点に注意。

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

Empty Cartボタン押下から確認ダイアログまでの流れを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | button_view.dart | `lib/screens/cart_screen/widget/button_view.dart` | Empty Cartボタンと_onPressAllRemoveメソッド |

**主要処理フロー**:
1. **84-86行目**: Empty CartボタンのonPressed処理
2. **157-188行目**: _onPressAllRemoveメソッドで確認ダイアログを表示
3. **177-181行目**: 「Yes」選択時にRemoveAllCartItemEventを発行

#### Step 3: BLoC層を理解する

状態管理とビジネスロジックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | cart_screen_event.dart | `lib/screens/cart_screen/bloc/cart_screen_event.dart` | RemoveAllCartItemEventの定義（43-45行目） |
| 3-2 | cart_screen_state.dart | `lib/screens/cart_screen/bloc/cart_screen_state.dart` | RemoveAllCartItemStateの定義（58-67行目） |
| 3-3 | cart_screen_bloc.dart | `lib/screens/cart_screen/bloc/cart_screen_bloc.dart` | RemoveAllCartItemEventの処理（48-56行目） |

**主要処理フロー**:
- **48-56行目**: RemoveAllCartItemEventを受信し、repository経由でAPI呼び出し

#### Step 4: リポジトリ層とAPI層を理解する

実際のAPI呼び出し処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | cart_screen_repository.dart | `lib/screens/cart_screen/bloc/cart_screen_repository.dart` | removeAllCartItemメソッド（108-119行目） |
| 4-2 | api_client.dart | `lib/services/api_client.dart` | removeAllCartItem API呼び出し（570-581行目） |
| 4-3 | mutation_query.dart | `lib/services/mutation_query.dart` | GraphQL mutation定義（431-438行目） |

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

```
ButtonView (button_view.dart)
    │
    └─ _onPressAllRemove() - 確認ダイアログ表示
           │
           └─ AlertDialog → 「Yes」押下
                  │
                  └─ RemoveAllCartItemEvent発行
                         │
                         └─ CartScreenBloc.mapEventToState
                                │
                                └─ CartScreenRepository.removeAllCartItem
                                       │
                                       └─ ApiClient.removeAllCartItem
                                              │
                                              └─ MutationQuery.removeAllCartItem
```

### データフロー図

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

Empty Cartボタン ───▶ 確認ダイアログ ───▶ RemoveAllCartItemEvent
     (UI)              (確認UI)            (イベント発行)
                                                 │
                       ┌─────────────────────────┘
                       ▼
             CartScreenBloc
                       │
                       ▼
             CartScreenRepository
                       │
                       ▼
                 ApiClient
                       │
                       ▼
          GraphQL API (removeAllCartItem)
                       │
                       ▼
               BaseModel ───▶ RemoveAllCartItemState ───▶ UI更新
             (応答データ)         (状態通知)          (空カート表示)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| cart_screen.dart | `lib/screens/cart_screen/cart_screen.dart` | ソース | カート画面メインWidget |
| button_view.dart | `lib/screens/cart_screen/widget/button_view.dart` | ソース | カート操作ボタン群、全削除UI |
| cart_screen_bloc.dart | `lib/screens/cart_screen/bloc/cart_screen_bloc.dart` | ソース | カート画面BLoC |
| cart_screen_event.dart | `lib/screens/cart_screen/bloc/cart_screen_event.dart` | ソース | BLoCイベント定義 |
| cart_screen_state.dart | `lib/screens/cart_screen/bloc/cart_screen_state.dart` | ソース | BLoC状態定義 |
| cart_screen_repository.dart | `lib/screens/cart_screen/bloc/cart_screen_repository.dart` | ソース | カート画面リポジトリ |
| graphql_base_model.dart | `lib/data_model/graphql_base_model.dart` | ソース | API基本応答モデル |
| api_client.dart | `lib/services/api_client.dart` | ソース | API通信クライアント |
| mutation_query.dart | `lib/services/mutation_query.dart` | ソース | GraphQLクエリ定義 |
