# 通知設計書 3-成功通知（Success Notification）

## 概要

本ドキュメントは、Bagisto ECモバイルアプリにおけるアプリ内成功通知（Success Notification）機能の設計書である。

### 本通知の処理概要

本通知は、ユーザー操作が正常に完了した際に、画面上部にオーバーレイ形式で緑色の背景を持つ成功メッセージを表示する機能を提供する。チェックマークアイコン付きで、視覚的に操作の成功を伝達する。

**業務上の目的・背景**：ECアプリにおいて、ユーザーが実行した操作（商品のカート追加、注文確定、住所登録など）が正常に完了したことを即座にフィードバックすることは、ユーザー体験の向上に不可欠である。成功通知により、ユーザーは操作結果を視覚的に確認でき、次のアクションへスムーズに移行できる。また、操作の成否が不明な状態を解消し、ユーザーの不安を軽減する。

**通知の送信タイミング**：各種ユーザー操作（カート操作、認証、住所登録、レビュー投稿など）が正常に完了した直後。APIレスポンスで成功が確認された時点で即座に表示される。

**通知の受信者**：操作を実行したユーザー本人。画面上のオーバーレイとして表示されるため、操作中のユーザーのみが対象。

**通知内容の概要**：「Success」（成功）というタイトルと、操作に応じた具体的なメッセージ（例：「商品をカートに追加しました」「ログインに成功しました」など）。緑色の背景とチェックマークアイコンで視覚的な成功を表現。

**期待されるアクション**：ユーザーは通知を確認し、必要に応じて上方向へスワイプして通知を閉じるか、自動的に消えるのを待つ。その後、次の操作へ進む。

## 通知種別

アプリ内通知（オーバーレイ通知 / トースト形式）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（画面操作完了時に即座表示） |
| 優先度 | 中 |
| リトライ | なし（UI表示のため不要） |

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

1. 操作を実行したユーザーの画面に対してのみ表示
2. BuildContextを通じて現在の画面に表示
3. アプリ全体でグローバルにサポート（OverlaySupport.global）

## 通知テンプレート

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

| 項目 | 内容 |
|-----|------|
| 表示位置 | 画面上部 |
| 背景色 | Colors.green.shade400 |
| アイコン | Icons.check_circle_outline（白色） |
| 消去方向 | 上方向スワイプ（DismissDirection.up） |

### 本文テンプレート

```
タイトル: "Success" (StringConstants.success.localized())
サブタイトル: {msg} - 操作に応じたメッセージ
```

### 添付ファイル

| ファイル名 | 形式 | 条件 | 説明 |
|----------|------|------|------|
| なし | - | - | テキストのみ |

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| msg | 成功メッセージ | 呼び出し元から渡される | Yes |
| context | ビルドコンテキスト | Flutter Widget | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 画面操作 | カートから商品削除 | RemoveCartItemState.success | cart_screen.dart 行67-69 |
| 画面操作 | 全カート商品削除 | RemoveAllCartItemState.success | cart_screen.dart 行77-79 |
| 画面操作 | クーポン適用 | AddCouponState.success | cart_screen.dart 行86-88 |
| 画面操作 | クーポン削除 | RemoveCouponCartState.success | cart_screen.dart 行94-96 |
| 画面操作 | カート更新 | UpdateCartState.success | cart_screen.dart 行112-113 |
| 画面操作 | ウィッシュリスト移動 | MoveToCartState.success | cart_screen.dart 行102-104 |
| 認証操作 | ログイン成功 | FetchSignInState.success | sign_in_screen.dart |
| 認証操作 | 会員登録成功 | SignUpState.success | sign_up.dart |
| 住所操作 | 住所追加/更新成功 | AddEditAddressState.success | add_edit_address_screen.dart |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| contextが無効 | ウィジェットがアンマウント済みの場合 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[ユーザー操作実行] --> B[API呼び出し]
    B --> C{API結果}
    C -->|成功| D[BLoC State更新]
    C -->|失敗| E[エラー通知へ]
    D --> F[BlocConsumer listener検出]
    F --> G[ShowMessage.successNotification呼び出し]
    G --> H[showSimpleNotification実行]
    H --> I[オーバーレイ表示]
    I --> J{ユーザーアクション}
    J -->|スワイプ| K[即座に消去]
    J -->|放置| L[自動消去]
    K --> M[終了]
    L --> M
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| なし | - | UI表示のためDB参照なし |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| なし | - | UI表示のためDB更新なし |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| Context無効 | 画面遷移中に呼び出し | overlay_supportパッケージがハンドリング |

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

制限なし（ユーザー操作に連動）

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

- 通知メッセージには機密情報を含めない
- ユーザー操作の結果のみを表示
- XSS等の脆弱性はFlutterフレームワークレベルで防御

## 備考

- overlay_support パッケージを使用してオーバーレイ表示を実現
- main.dart で `OverlaySupport.global` がアプリ全体をラップ
- 国際化対応済み（`.localized()` メソッドによる多言語サポート）
- テキストスタイルは白色、フォントサイズ16px、太字

---

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

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

### 推奨読解順序

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

成功通知の表示パラメータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | show_message.dart | `lib/widgets/show_message.dart` | ShowMessageクラスの全体構造 |

**読解のコツ**: `overlay_support` パッケージの `showSimpleNotification` 関数の引数を理解する。

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

オーバーレイサポートの初期化を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | main.dart | `lib/main.dart` | OverlaySupport.globalでのアプリラップ |

**主要処理フロー**:
1. **行192**: `OverlaySupport.global` でMaterialAppをラップ
2. これにより、アプリ全体でオーバーレイ通知が利用可能になる

#### Step 3: 通知表示処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | show_message.dart | `lib/widgets/show_message.dart` | successNotification() メソッドの実装 |

**主要処理フロー**:
- **行18-36**: `successNotification()` メソッド
- **行19**: `showSimpleNotification` 関数呼び出し
- **行20-24**: タイトルテキスト（Success、白色、太字、16px）
- **行25**: context引数
- **行26**: 背景色（Colors.green.shade400）
- **行27-30**: リーディングアイコン（check_circle_outline、白色）
- **行31**: スワイプ消去方向（上方向）
- **行32-35**: サブタイトル（メッセージ、白色）

#### Step 4: 呼び出し元を理解する（カート画面の例）

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | cart_screen.dart | `lib/screens/cart_screen/cart_screen.dart` | BlocConsumer listenerでの通知呼び出し |

**主要処理フロー**:
- **行62-116**: BlocConsumer listener内での状態監視
- **行67-69**: RemoveCartItemState.successでの成功通知
- **行77-79**: RemoveAllCartItemState.successでの成功通知
- **行86-88**: AddCouponState.successでの成功通知
- **行94-96**: RemoveCouponCartState.successでの成功通知
- **行102-104**: MoveToCartState.successでの成功通知
- **行112-113**: UpdateCartState.successでの成功通知

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

```
BlocConsumer（各画面）
    |
    +-- listener（状態変化検出）
            |
            +-- State.success 判定
                    |
                    +-- ShowMessage.successNotification(msg, context)
                            |
                            +-- showSimpleNotification()
                                    |
                                    +-- OverlaySupport（オーバーレイ描画）
                                            |
                                            +-- 画面上部に緑色通知表示
```

### データフロー図

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

ユーザー操作 ──────▶ API呼び出し ──────▶ 成功レスポンス
                                                |
                                                ▼
                                        BLoC State更新
                                                |
                                                ▼
                                        listener検出
                                                |
                                                ▼
                                        successNotification()
                                                |
                                                ▼
                                        showSimpleNotification()
                                                |
                                                ▼
                                        オーバーレイ表示 ──────▶ ユーザーに視覚的フィードバック
                                                |
                               ┌────────────────┴────────────────┐
                               ▼                                 ▼
                        スワイプで消去                      自動消去
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| show_message.dart | `lib/widgets/show_message.dart` | ソース | 成功通知の表示処理 |
| main.dart | `lib/main.dart` | ソース | OverlaySupport.globalの初期化 |
| cart_screen.dart | `lib/screens/cart_screen/cart_screen.dart` | ソース | カート操作での通知呼び出し例 |
| string_constants.dart | `lib/utils/string_constants.dart` | 設定 | 「success」文字列定数 |
| application_localization.dart | `lib/utils/application_localization.dart` | ソース | 多言語対応処理 |
