# 通知設計書 49-新商品カート追加通知

## 概要

本ドキュメントは、ホームページの新商品カルーセルにおいて商品をカートに追加する際に表示される各種通知の設計について記述する。

### 本通知の処理概要

本通知は、ホームページの新商品ビュー（NewProductView）において商品をカートに追加する際、条件に応じて表示される各種通知（警告通知、エラー通知）である。

**業務上の目的・背景**：新商品カルーセルは、ホームページで目立つ位置に配置される商品一覧である。ユーザーは商品カードから直接「カートに追加」ボタンをタップできるが、商品タイプやオプションの有無、ログイン状態によって適切なフィードバックを提供する必要がある。

**通知の送信タイミング**：新商品ビューにおいて以下の操作を行った際に即時表示される。
- カート追加ボタンタップ時（商品にオプション選択が必要な場合）
- ウィッシュリストアイコンタップ時（未ログインの場合）
- 比較アイコンタップ時（未ログインの場合）
- インターネット未接続時

**通知の受信者**：新商品ビューを操作している現在のユーザー（アプリ操作者）。

**通知内容の概要**：警告メッセージとして「オプションを選択してください」「ログインしてください」「インターネット接続を確認してください」等のローカライズされたテキストが表示される。

**期待されるアクション**：
- オプション選択が必要な場合は商品詳細画面でオプションを選択してからカートに追加
- 未ログインの場合はログインしてから再度操作
- インターネット未接続の場合は接続を確認してから再度操作

## 通知種別

アプリ内通知（オーバーレイ警告/エラー通知）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（即時表示） |
| 優先度 | 高 |
| リトライ | 無し（即時1回表示） |

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

操作中のユーザーに対して即時表示。特定の送信先決定ロジックは不要。

## 通知テンプレート

### 警告通知（オプション選択必須時）

| 項目 | 内容 |
|-----|------|
| タイトル | Warning（StringConstants.warning のローカライズ値） |
| 背景色 | Colors.amber（黄色） |
| アイコン | Icons.warning_amber（警告アイコン） |
| 形式 | オーバーレイ通知 |

### 警告通知（未ログイン時）

| 項目 | 内容 |
|-----|------|
| タイトル | Warning（StringConstants.warning のローカライズ値） |
| 背景色 | Colors.amber（黄色） |
| アイコン | Icons.warning_amber（警告アイコン） |
| 形式 | オーバーレイ通知 |

### エラー通知（インターネット未接続時）

| 項目 | 内容 |
|-----|------|
| タイトル | Failed（StringConstants.failed のローカライズ値） |
| 背景色 | Colors.red（赤色） |
| アイコン | Icons.cancel_outlined（キャンセルアイコン） |
| 形式 | オーバーレイ通知 |

### 本文テンプレート

**オプション選択必須時:**
```
[タイトル]: Warning
[メッセージ]: オプションを選択してください（StringConstants.addOptions のローカライズ値）
```

**未ログイン時:**
```
[タイトル]: Warning
[メッセージ]: ログインしてください（StringConstants.pleaseLogin のローカライズ値）
```

**インターネット未接続時:**
```
[タイトル]: Failed
[メッセージ]: インターネット接続に問題があります（StringConstants.internetIssue のローカライズ値）
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| addOptions | オプション選択を促すメッセージ | StringConstants.addOptions | Yes（オプション必須時） |
| pleaseLogin | ログインを促すメッセージ | StringConstants.pleaseLogin | Yes（未ログイン時） |
| internetIssue | インターネット接続エラーメッセージ | StringConstants.internetIssue | Yes（接続エラー時） |
| warning | 警告タイトル | StringConstants.warning | Yes |
| failed | 失敗タイトル | StringConstants.failed | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 画面操作 | カート追加ボタンタップ | 商品タイプが simple/virtual 以外、またはカスタマイズオプションあり | オプション選択必須の警告通知 |
| 画面操作 | ウィッシュリストアイコンタップ | isLogin == false | ログイン必須の警告通知 |
| 画面操作 | 比較アイコンタップ | isLogin == false | ログイン必須の警告通知 |
| 画面操作 | 各種操作 | checkInternetConnection == false | インターネット接続エラー通知 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| simple/virtual商品かつオプションなし | カート追加が直接実行され、警告通知は表示されない |
| ログイン済み | ウィッシュリスト/比較操作でログイン警告は表示されない |
| インターネット接続あり | インターネットエラー通知は表示されない |
| isRecentProduct == true | 最近閲覧商品の場合、ウィッシュリスト/比較アイコンは非表示 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[操作ボタンタップ] --> B{インターネット接続確認}
    B -->|未接続| C[ShowMessage.errorNotification（internetIssue）]
    B -->|接続済| D{操作種別判定}
    D -->|カート追加| E{商品タイプ判定}
    E -->|simple/virtual かつ オプションなし| F[HomePageBloc.add（カート追加Event）]
    E -->|その他| G[ShowMessage.warningNotification（addOptions）]
    G --> H[商品詳細画面へ遷移]
    D -->|ウィッシュリスト| I{ログイン確認}
    I -->|未ログイン| J[ShowMessage.warningNotification（pleaseLogin）]
    I -->|ログイン済| K[HomePageBloc.add（ウィッシュリストEvent）]
    D -->|比較| L{ログイン確認}
    L -->|未ログイン| M[ShowMessage.warningNotification（pleaseLogin）]
    L -->|ログイン済| N[HomePageBloc.add（比較Event）]
```

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

### 参照テーブル一覧

本通知はクライアント側のみで完結するため、データベース参照は発生しない。

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| ネットワークエラー | インターネット未接続 | インターネットエラー通知を表示 |
| 未ログインエラー | ログインが必要な操作で未ログイン | ログイン要求警告通知を表示 |
| オプション必須エラー | 商品にオプション選択が必要 | 警告通知を表示して商品詳細画面へ遷移 |

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

制限なし（24時間）

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

- 商品操作は一部ログイン必須（ウィッシュリスト、比較リスト）
- 未ログイン時は明示的にログインを要求し、不正操作を防止

## 備考

- 最近閲覧商品（isRecentProduct == true）の場合、ウィッシュリスト/比較アイコンは非表示となる（208-259行目の条件分岐）
- オプション選択必須の警告通知後、OnClickLoaderEvent で isReqToShowLoader: false が設定される
- homepageEvent ヘルパー関数でカート追加処理を実行する

---

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

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

### 推奨読解順序

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

まず、商品データモデルとカルーセル表示に使用されるパラメータを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | new_product_data.dart | `lib/screens/home_page/data_model/new_product_data.dart` | NewProducts クラスの type, customizableOptions, priceHtml フィールドを確認 |

**読解のコツ**: 商品タイプ（simple, configurable, bundle等）とカスタマイズオプションの有無が処理分岐に影響することに注目する。

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

処理の起点となる各種操作のタップイベントを特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | new_product_view.dart | `lib/screens/home_page/widget/new_product_view.dart` | 各種操作のタップ処理を確認 |

**主要処理フロー**:
1. **213-256行目**: ウィッシュリストアイコンのタップ処理
2. **258-295行目**: 比較アイコンのタップ処理
3. **331-394行目**: カート追加ボタンのタップ処理

#### Step 3: 条件判定ロジックを理解する

商品タイプとオプションによる処理分岐を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | new_product_view.dart | `lib/screens/home_page/widget/new_product_view.dart` | 340-352行目の条件分岐を確認 |

**条件分岐**:
```dart
if (((val?.priceHtml?.type) == StringConstants.simple ||
    val?.type == StringConstants.simple ||
    val?.type == StringConstants.virtual) &&
    ((val?.customizableOptions ?? []).length == 0))
```

#### Step 4: 文字列定数を理解する

通知に使用される文字列定数を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | string_constants.dart | `lib/utils/string_constants.dart` | addOptions（136行目）, pleaseLogin（195行目）, internetIssue（126行目）の定義を確認 |

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

```
NewProductView
    │
    ├─ ListView.builder (商品カードリスト)
    │      │
    │      ├─ ウィッシュリストアイコン (isRecentProduct == false の場合のみ)
    │      │      └─ InkWell.onTap
    │      │             └─ checkInternetConnection
    │      │                    ├─ 未接続 → errorNotification (internetIssue)
    │      │                    └─ 接続済
    │      │                           ├─ isLogin → ウィッシュリストEvent
    │      │                           └─ !isLogin → warningNotification (pleaseLogin)
    │      │
    │      ├─ 比較アイコン (isRecentProduct == false の場合のみ)
    │      │      └─ InkWell.onTap
    │      │             └─ checkInternetConnection
    │      │                    ├─ 未接続 → errorNotification (internetIssue)
    │      │                    └─ 接続済
    │      │                           ├─ isLogin → 比較Event
    │      │                           └─ !isLogin → warningNotification (pleaseLogin)
    │      │
    │      └─ カート追加ボタン
    │             └─ CommonWidgets().appButton.onPressed
    │                    └─ checkInternetConnection
    │                           ├─ 未接続 → errorNotification (internetIssue)
    │                           └─ 接続済
    │                                  ├─ simple/virtual + オプションなし
    │                                  │      └─ homepageEvent (カート追加)
    │                                  └─ その他
    │                                         ├─ warningNotification (addOptions)
    │                                         └─ Navigator.pushNamed (商品詳細)
    │
    └─ viewAllButton (全て見るボタン)
           └─ カテゴリ画面へ遷移
```

### データフロー図

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

操作ボタンタップ ───▶ checkInternetConnection
                              │
                       ┌──────┴──────┐
                       ▼             ▼
                    未接続        接続済
                       │             │
                       ▼             ▼
                  エラー通知    操作種別判定
                                     │
                        ┌────────────┼────────────┐
                        ▼            ▼            ▼
                    カート追加   ウィッシュ      比較
                        │        リスト           │
                        │            │            │
                        ▼            ▼            ▼
                  商品タイプ判定  ログイン確認  ログイン確認
                        │            │            │
                 ┌──────┴──────┐     │            │
                 ▼            ▼     ▼            ▼
            simple/virtual  その他  未ログイン  ログイン済
               オプションなし  │     │            │
                 │            ▼     ▼            ▼
                 ▼        警告通知  警告通知    API呼び出し
            API呼び出し      +画面遷移
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| new_product_view.dart | `lib/screens/home_page/widget/new_product_view.dart` | ソース | 新商品カルーセルのWidget、通知トリガーの発火元 |
| home_page_event.dart | `lib/screens/home_page/utils/home_page_event.dart` | ソース | homepageEvent ヘルパー関数 |
| home_page_bloc.dart | `lib/screens/home_page/bloc/home_page_bloc.dart` | ソース | ホームページのBLoC |
| show_message.dart | `lib/widgets/show_message.dart` | ソース | 通知表示ユーティリティクラス |
| string_constants.dart | `lib/utils/string_constants.dart` | ソース | 文字列定数の定義 |
| new_product_data.dart | `lib/screens/home_page/data_model/new_product_data.dart` | ソース | 商品データモデル |
