# 通知設計書 19-カート追加成功/失敗通知

## 概要

本ドキュメントは、商品詳細画面から商品をカートに追加した際の結果を通知するアプリ内通知の設計を定義する。

### 本通知の処理概要

商品詳細画面においてユーザーが「カートに追加」ボタンをタップした際、その追加処理の結果（成功または失敗）をリアルタイムでフィードバックするアプリ内オーバーレイ通知機能である。

**業務上の目的・背景**：ECアプリにおいてカートへの商品追加は購買プロセスの中核となる操作である。追加成功時にはユーザーに安心感を与え、次のアクション（ショッピング継続またはチェックアウト）への誘導を促す。追加失敗時（在庫切れ、バリエーション未選択など）には具体的なエラー内容を提示し、問題解決を支援する。

**通知の送信タイミング**：カート追加APIリクエストの結果が返却された直後に通知が表示される。具体的には`AddToCartProductState`がBlocから発行されたタイミングで通知処理が実行される。

**通知の受信者**：カート追加操作を実行したユーザー本人のみ。デバイス上で即座に表示されるローカル通知。

**通知内容の概要**：成功時は緑色背景の成功通知で追加完了メッセージを表示。失敗時は赤色背景のエラー通知でエラーメッセージを表示する。バリエーション未選択などの警告は黄色背景で表示される。

**期待されるアクション**：成功時はショッピングを継続するかカート画面へ遷移する。失敗時はエラー内容を確認し、必要な修正（バリエーション選択など）を行う。

## 通知種別

アプリ内通知（オーバーレイ通知）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（API応答後即時表示） |
| 優先度 | 高 |
| リトライ | 無（表示は1回のみ） |

### 送信先決定ロジック

カート追加操作を実行したユーザーのデバイス画面に直接表示される。

## 通知テンプレート

### アプリ内通知の場合

| 項目 | 内容 |
|-----|------|
| 表示位置 | 画面上部オーバーレイ |
| 表示時間 | 約3秒（自動消去） |
| 背景色（成功時） | 緑色（Colors.green.shade400） |
| 背景色（失敗時） | 赤色（Colors.red） |
| 背景色（警告時） | 黄色（Colors.amber） |

### 本文テンプレート

**成功時**
```
タイトル: Success
メッセージ: {成功メッセージ}
アイコン: check_circle_outline（白色）
```

**失敗時**
```
タイトル: Failed
メッセージ: {エラーメッセージ}
アイコン: cancel_outlined（白色）
```

**警告時（バリデーション）**
```
タイトル: Warning
メッセージ: {警告メッセージ}（例：バリエーションを選択してください）
アイコン: warning_amber（白色）
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| successMsg | カート追加成功メッセージ | state.successMsg | Yes（成功時） |
| error | エラーメッセージ | state.error | Yes（失敗時） |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 画面操作 | AddToCartProductEvent発行 | AddToCartProductState.success受信時 | カート追加成功 |
| 画面操作 | AddToCartProductEvent発行 | AddToCartProductState.fail受信時 | カート追加失敗 |
| 画面操作 | カートに追加ボタンタップ | バリデーションエラー時 | 入力チェック警告 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| インターネット未接続 | ネットワークエラー通知が別途表示 |
| 商品販売不可 | isSaleable=falseの場合はボタン無効化 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[カートに追加ボタンタップ] --> B{インターネット接続}
    B -->|未接続| C[errorNotification表示]
    B -->|接続OK| D{商品タイプ別バリデーション}
    D -->|configurable未選択| E[warningNotification表示]
    D -->|grouped 0個選択| E
    D -->|downloadable リンク未選択| E
    D -->|booking スロット未選択| E
    D -->|バリデーションOK| F[AddToCartProductEvent発行]
    F --> G[ProductScreenBLoc処理]
    G --> H[API呼び出し]
    H --> I{API結果}
    I -->|success| J[successNotification表示]
    I -->|fail| K[errorNotification表示]
    J --> L[カート数量更新]
    E --> M[ローダー非表示]
```

## データベース参照・更新仕様

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| products | 商品情報 | 在庫・販売可否確認 |
| product_variants | バリエーション情報 | configurable商品用 |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| cart_items | INSERT/UPDATE | カート商品追加・数量更新 |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| バリエーション未選択 | configurable商品で未選択 | warningNotification表示 |
| 必須オプション未入力 | カスタマイズオプション未入力 | warningNotification表示 |
| グループ商品未選択 | grouped商品で0個選択 | warningNotification表示 |
| ダウンロードリンク未選択 | downloadable商品で未選択 | warningNotification表示 |
| 予約メモ未入力 | table予約で未入力 | warningNotification表示 |
| 在庫不足 | 在庫が不足 | errorNotification表示 |
| ネットワークエラー | インターネット接続なし | errorNotification表示 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0回（自動リトライなし） |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | 制限なし |
| 1日あたり上限 | 制限なし |

### 配信時間帯

制限なし（ユーザー操作に応じて即時表示）

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

- カート操作はユーザーセッションに紐づく
- 価格は商品追加時にサーバー側で再計算される
- 在庫チェックはサーバー側で行われる

## 備考

- overlay_supportパッケージを使用してオーバーレイ通知を実装
- 商品タイプ（simple、configurable、grouped、downloadable、bundle、booking）によって異なるバリデーションが適用される
- カスタマイズオプション（customizableOptions）のバリデーションも実施
- 成功時にGlobalData.cartCountControllerでカート数量が更新される

---

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

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

### 推奨読解順序

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

まず、カート追加レスポンスのデータモデルを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | product_state.dart | `lib/screens/product_screen/bloc/product_state.dart` | AddToCartProductStateの構造を確認 |
| 1-2 | add_to_cart_model.dart | `lib/data_model/add_to_cart_model.dart` | AddToCartModelの構造を確認 |

**読解のコツ**: AddToCartProductStateのstatus、successMsg、error、responseプロパティがカート追加成否の判定と通知メッセージに使用される。

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

処理の起点となる商品詳細画面のUIコードを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | product_screen.dart | `lib/screens/product_screen/view/product_screen.dart` | BlocConsumerのlistener内でAddToCartProductStateの処理を確認 |
| 2-2 | product_screen.dart | `lib/screens/product_screen/view/product_screen.dart` | _addToCartメソッドでバリデーション処理を確認 |

**主要処理フロー**:
1. **行155-162**: AddToCartProductState処理
2. **行156-157**: 失敗時のerrorNotification呼び出し
3. **行158-161**: 成功時のsuccessNotification呼び出し
4. **行340-581**: _addToCartメソッドでの商品タイプ別バリデーションと警告通知

#### Step 3: 商品タイプ別バリデーションを理解する

_addToCartメソッド内の各商品タイプのバリデーションを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | product_screen.dart | `lib/screens/product_screen/view/product_screen.dart` | 各商品タイプのwarningNotification呼び出しを確認 |

**主要処理フロー**:
- **行378-386**: customizableOptions必須チェック
- **行404-426**: grouped商品の最低1個選択チェック
- **行451-474**: downloadable商品のリンク選択チェック
- **行474-498**: configurable商品のバリエーション選択チェック
- **行505-526**: booking商品のテーブル予約メモチェック

#### Step 4: 通知表示層を理解する

通知の実際の表示処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | show_message.dart | `lib/widgets/show_message.dart` | successNotification、errorNotification、warningNotificationメソッドの実装を確認 |

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

```
ProductScreen (product_screen.dart)
    │
    ├─ MaterialButton.onPressed (行303-319)
    │      │
    │      ├─ checkInternetConnection
    │      │      │
    │      │      ├─ 未接続 → ShowMessage.errorNotification
    │      │      │
    │      │      └─ 接続OK → _addToCart
    │      │
    │      └─ _addToCart (行340-581)
    │             │
    │             ├─ customizableOptionsチェック → warningNotification
    │             │
    │             ├─ grouped商品チェック → warningNotification
    │             │
    │             ├─ downloadable商品チェック → warningNotification
    │             │
    │             ├─ configurable商品チェック → warningNotification
    │             │
    │             ├─ booking商品チェック → warningNotification
    │             │
    │             └─ AddToCartProductEvent発行
    │
    └─ BlocConsumer<ProductScreenBLoc, ProductBaseState>
           │
           └─ listener (行154-196)
                  │
                  └─ AddToCartProductState処理 (行155-162)
                         │
                         ├─ fail → ShowMessage.errorNotification
                         │
                         └─ success → ShowMessage.successNotification
```

### データフロー図

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

カートに追加           インターネット              バリデーション
ボタンタップ     ───▶   接続チェック      ───▶      チェック
                           │                          │
                           ▼                          ▼
                     接続OK/NG              商品タイプ別処理
                           │                          │
                           ▼                          ▼
                      _addToCart              warningNotification
                           │                    (バリデーションNG時)
                           ▼                          │
                  AddToCartProductEvent               ▼
                           │               AddToCartProductState
                           ▼                    (API結果)
                  ProductScreenBLoc                   │
                           │                          ▼
                           ▼                    ShowMessage
                      API呼び出し           .successNotification
                           │               .errorNotification
                           ▼                          │
                      API Response                    ▼
                                            オーバーレイ通知表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| product_screen.dart | `lib/screens/product_screen/view/product_screen.dart` | ソース | 商品詳細画面UI、通知表示トリガー |
| product_bloc.dart | `lib/screens/product_screen/bloc/product_bloc.dart` | ソース | 商品画面ビジネスロジック |
| product_event.dart | `lib/screens/product_screen/bloc/product_event.dart` | ソース | 商品画面イベント定義 |
| product_state.dart | `lib/screens/product_screen/bloc/product_state.dart` | ソース | 商品画面状態定義 |
| show_message.dart | `lib/widgets/show_message.dart` | ソース | 通知表示ウィジェット |
| string_constants.dart | `lib/utils/string_constants.dart` | ソース | 文字列定数 |
