# 通知設計書 48-ホームページ商品操作通知

## 概要

本ドキュメントは、ホームページ画面において商品のカート追加、ウィッシュリスト追加/削除、比較リスト追加、ニュースレター購読の操作結果として表示される通知の設計について記述する。

### 本通知の処理概要

本通知は、ホームページ画面（HomeScreen）において商品に対して各種操作（カート追加、ウィッシュリスト追加/削除、比較リスト追加）およびニュースレター購読を行った際に、その処理結果を通知するものである。

**業務上の目的・背景**：ECアプリのホームページは、ユーザーが最初に目にする画面であり、おすすめ商品、新商品、カテゴリカルーセルなど様々な商品が表示される。ユーザーは商品カードから直接商品をカートやウィッシュリストに追加することができる。これらの操作に対して即座にフィードバックを提供することで、ユーザーは操作が成功したか失敗したかを認識でき、スムーズな購買体験を実現できる。

**通知の送信タイミング**：ホームページ画面において以下の操作が完了した際に即時表示される。
- カートへの商品追加（AddToCartState）
- ウィッシュリストへの商品追加（FetchAddWishlistHomepageState）
- ウィッシュリストからの商品削除（RemoveWishlistState）
- 比較リストへの商品追加（AddToCompareHomepageState）
- ニュースレター購読（SubscribeNewsLetterState）

**通知の受信者**：ホームページ画面を操作している現在のユーザー（アプリ操作者）。ログイン済みユーザーおよびゲストユーザーの両方が対象（ただし一部操作はログイン必須）。

**通知内容の概要**：成功時は緑色の背景でサーバーから返却されたメッセージを表示。失敗時は赤色の背景でエラーメッセージを表示する。

**期待されるアクション**：成功時はユーザーは操作が完了したことを確認し、買い物を継続する。失敗時は表示されたエラーに応じて対処（ログイン、再試行等）する。

## 通知種別

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

## 送信仕様

### 基本情報

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

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

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

## 通知テンプレート

### 成功通知

| 項目 | 内容 |
|-----|------|
| タイトル | Success（StringConstants.success のローカライズ値） |
| 背景色 | Colors.green.shade400（緑色） |
| アイコン | Icons.check_circle_outline（チェックマークアイコン） |
| 形式 | オーバーレイ通知 |

### 失敗通知

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

### 本文テンプレート

**カート追加成功時:**
```
[タイトル]: Success
[メッセージ]: {サーバーから返却されたメッセージ}（state.graphQlBaseModel.message）
```

**ウィッシュリスト追加成功時:**
```
[タイトル]: Success
[メッセージ]: {サーバーから返却されたメッセージ}（state.response.message）
```

**比較リスト追加成功時:**
```
[タイトル]: Success
[メッセージ]: {サーバーから返却されたメッセージ}（state.successMsg）
```

**ニュースレター購読成功時:**
```
[タイトル]: Success
[メッセージ]: {サーバーから返却されたメッセージ}（state.baseModel.message）
```

**失敗時:**
```
[タイトル]: Failed
[メッセージ]: {サーバーから返却されたエラーメッセージ}
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| message | 成功メッセージ | state.graphQlBaseModel.message / state.response.message / state.baseModel.message | No（成功時） |
| successMsg | 成功メッセージ（比較リスト） | state.successMsg | No |
| graphqlErrors | GraphQLエラーメッセージ | state.graphQlBaseModel.graphqlErrors | No（失敗時） |
| error | エラーメッセージ | state.error | No（失敗時） |
| success | 成功タイトル | StringConstants.success | Yes |
| failed | 失敗タイトル | StringConstants.failed | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| API応答 | AddToCartState | status == Status.success | カート追加成功時に成功通知 |
| API応答 | AddToCartState | status == Status.fail | カート追加失敗時にエラー通知 |
| API応答 | FetchAddWishlistHomepageState | status == Status.success | ウィッシュリスト追加成功時に成功通知 |
| API応答 | FetchAddWishlistHomepageState | status == Status.fail | ウィッシュリスト追加失敗時にエラー通知 |
| API応答 | RemoveWishlistState | status == Status.success | ウィッシュリスト削除成功時に成功通知 |
| API応答 | RemoveWishlistState | status == Status.fail | ウィッシュリスト削除失敗時にエラー通知 |
| API応答 | AddToCompareHomepageState | status == Status.success | 比較リスト追加成功時に成功通知 |
| API応答 | AddToCompareHomepageState | status == Status.fail | 比較リスト追加失敗時にエラー通知 |
| API応答 | SubscribeNewsLetterState | status == Status.success | ニュースレター購読成功時に成功通知 |
| API応答 | SubscribeNewsLetterState | status == Status.fail | ニュースレター購読失敗時にエラー通知 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| ネットワーク未接続 | checkInternetConnection が false の場合は API を呼び出さず、インターネットエラー通知を表示 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[商品操作ボタンタップ] --> B{インターネット接続確認}
    B -->|未接続| C[インターネットエラー通知]
    B -->|接続済| D{ログイン確認（必要な場合）}
    D -->|未ログイン| E[ログイン要求警告通知]
    D -->|ログイン済/不要| F[API呼び出し]
    F --> G[状態更新受信]
    G --> H{status == success?}
    H -->|Yes| I[ShowMessage.successNotification]
    H -->|No| J[ShowMessage.errorNotification]
    I --> K[カート数更新（カート追加時）]
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| products | 商品情報 | ホームページ商品表示 |
| theme_customization | テーマカスタマイズ | ホームページレイアウト設定 |

### 更新テーブル一覧（サーバー側）

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| cart_items | INSERT/UPDATE | カート商品追加 |
| wishlist | INSERT/DELETE | ウィッシュリスト操作 |
| compare_items | INSERT | 比較リスト追加 |
| newsletter_subscribers | INSERT | ニュースレター購読者登録 |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| ネットワークエラー | インターネット未接続 | インターネットエラー通知を表示 |
| 未ログインエラー | ログインが必要な操作で未ログイン | ログイン要求警告通知を表示 |
| 在庫エラー | 商品の在庫がない | エラー通知でメッセージを表示 |
| API呼び出し失敗 | サーバーエラー | エラー通知でメッセージを表示 |
| オプション必須エラー | 商品にオプション選択が必要 | 警告通知を表示して商品詳細画面へ遷移 |
| メール重複 | 既に登録済みのメールでニュースレター購読 | エラー通知でメッセージを表示 |

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

制限なし（24時間）

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

- 商品操作は一部ログイン必須（ウィッシュリスト、比較リスト）
- カート数量はグローバル状態（GlobalData.cartCountController）で管理される
- SharedPreferences にカート数が保存される
- ニュースレター購読はログイン不要だがメールアドレスが必要

## 備考

- カート追加成功時はカート数量がリアルタイムで更新される（132-134行目）
- ホームページはテーマカスタマイズ（ThemeCustomDataModel）に基づいて動的にレイアウトが構築される
- 商品カルーセル、カテゴリカルーセル、スライダー等の各コンポーネントから商品操作が可能

---

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

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

### 推奨読解順序

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

まず、ホームページ画面で使用される状態クラスを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | home_page_bloc.dart | `lib/screens/home_page/bloc/home_page_bloc.dart` | 各種State（AddToCartState等）の定義を確認 |

**読解のコツ**: Status enum と各State の status フィールドの関係に注目する。

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

処理の起点となる BlocConsumer の listener を特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | home_page.dart | `lib/screens/home_page/home_page.dart` | buildView メソッド内の BlocConsumer listener（121-170行目）を確認 |

**主要処理フロー**:
1. **123-135行目**: AddToCartState の処理（カート追加）
2. **136-142行目**: FetchAddWishlistHomepageState の処理（ウィッシュリスト追加）
3. **143-150行目**: RemoveWishlistState の処理（ウィッシュリスト削除）
4. **151-157行目**: AddToCompareHomepageState の処理（比較リスト追加）
5. **158-169行目**: SubscribeNewsLetterState の処理（ニュースレター購読）

#### Step 3: 商品操作の呼び出し元を理解する

各種商品操作のトリガーを確認する。HomePageView から NewProductView などの子ウィジェットに処理が委譲される。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | home_page_view.dart | `lib/screens/home_page/widget/home_page_view.dart` | ホームページの各コンポーネントへの商品データ受け渡しを確認 |

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

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

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

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

```
HomeScreen
    │
    ├─ buildView
    │      └─ BlocConsumer.listener
    │             ├─ AddToCartState
    │             │      ├─ success → successNotification + カート数更新
    │             │      └─ fail → errorNotification
    │             ├─ FetchAddWishlistHomepageState
    │             │      ├─ success → successNotification
    │             │      └─ fail → errorNotification
    │             ├─ RemoveWishlistState
    │             │      ├─ success → successNotification
    │             │      └─ fail → errorNotification
    │             ├─ AddToCompareHomepageState
    │             │      ├─ success → successNotification
    │             │      └─ fail → errorNotification
    │             └─ SubscribeNewsLetterState
    │                    ├─ success → successNotification
    │                    └─ fail → errorNotification
    │
    └─ HomePageView
           ├─ NewProductView (新商品/おすすめ商品)
           │      └─ 商品カード操作 → HomePageBloc
           ├─ CategoryCarousel (カテゴリカルーセル)
           └─ NewsletterSubscription (ニュースレター購読)
                  └─ 購読ボタン → HomePageBloc
```

### データフロー図

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

商品操作ボタン ───▶ checkInternetConnection
                              │
                       ┌──────┴──────┐
                       ▼             ▼
                    未接続        接続済
                       │             │
                       ▼             ▼
                  エラー通知    操作種別判定
                                     │
                        ┌────────────┼────────────┐
                        ▼            ▼            ▼
                    カート追加   ウィッシュ    ニュースレター
                        │        リスト         購読
                        │            │            │
                        └────────────┼────────────┘
                                     ▼
                                 API呼び出し
                                     │
                                     ▼
                                 状態更新
                                     │
                              ┌──────┴──────┐
                              ▼             ▼
                           成功          失敗
                              │             │
                              ▼             ▼
                        成功通知     エラー通知
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| home_page.dart | `lib/screens/home_page/home_page.dart` | ソース | ホームページ画面のWidget、通知トリガーの発火元 |
| home_page_view.dart | `lib/screens/home_page/widget/home_page_view.dart` | ソース | ホームページのUI構成 |
| new_product_view.dart | `lib/screens/home_page/widget/new_product_view.dart` | ソース | 新商品/おすすめ商品カルーセル |
| 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` | ソース | 文字列定数の定義 |
