# 通知設計書 4-エラー通知（Error Notification）

## 概要

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

### 本通知の処理概要

本通知は、ユーザー操作が失敗した際に、画面上部にオーバーレイ形式で赤色の背景を持つエラーメッセージを表示する機能を提供する。キャンセルアイコン付きで、視覚的に操作の失敗を伝達する。

**業務上の目的・背景**：ECアプリにおいて、ユーザーが実行した操作（商品のカート追加、ログイン、決済など）が失敗した場合、その旨を即座にユーザーに伝達することは不可欠である。エラー通知により、ユーザーは問題が発生したことを認識し、適切な対処（再試行、情報の修正など）を行うことができる。明確なエラーフィードバックがない場合、ユーザーは操作の成否が不明なまま次のアクションに進んでしまい、深刻な問題につながる可能性がある。

**通知の送信タイミング**：各種ユーザー操作（カート操作、認証、決済処理など）が失敗した直後。APIレスポンスでエラーが確認された時点、またはクライアント側のバリデーションで問題が検出された時点で即座に表示される。

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

**通知内容の概要**：「Failed」（失敗）というタイトルと、エラーの原因を示す具体的なメッセージ（例：「ログインに失敗しました」「ネットワークエラーが発生しました」など）。赤色の背景とキャンセルアイコンで視覚的なエラーを表現。

**期待されるアクション**：ユーザーはエラーメッセージを確認し、問題の原因を理解した上で、入力内容の修正や再試行などの対処を行う。上方向へスワイプして通知を閉じることも可能。

## 通知種別

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

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（エラー発生時に即座表示） |
| 優先度 | 高 |
| リトライ | なし（UI表示のため不要） |

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

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

## 通知テンプレート

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

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

### 本文テンプレート

```
タイトル: "Failed" (StringConstants.failed.localized())
サブタイトル: {msg} - エラーメッセージ
```

### 添付ファイル

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

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| msg | エラーメッセージ | API エラーレスポンス / バリデーションメッセージ | Yes |
| context | ビルドコンテキスト | Flutter Widget | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 画面操作 | カートから商品削除失敗 | RemoveCartItemState.fail | cart_screen.dart 行65-66 |
| 画面操作 | 全カート商品削除失敗 | RemoveAllCartItemState.fail | cart_screen.dart 行75-76 |
| 画面操作 | クーポン適用失敗 | AddCouponState.fail | cart_screen.dart 行84-85 |
| 画面操作 | クーポン削除失敗 | RemoveCouponCartState.fail | cart_screen.dart 行92-93 |
| 画面操作 | カート更新失敗 | UpdateCartState.fail | cart_screen.dart 行108-109 |
| 画面操作 | ウィッシュリスト移動失敗 | MoveToCartState.fail | cart_screen.dart 行100-101 |
| 認証操作 | ログイン失敗 | FetchSignInState.fail | sign_in_screen.dart |
| 認証操作 | 会員登録失敗 | SignUpState.fail | sign_up.dart |
| API通信 | ネットワークエラー | Exception発生 | 各種API呼び出し時 |

### 送信抑止条件

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

## 処理フロー

### 送信フロー

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

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

### 参照テーブル一覧

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

### 更新テーブル一覧

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

制限なし（エラー発生に連動）

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

- エラーメッセージには内部実装の詳細を含めない（セキュリティ情報の漏洩防止）
- スタックトレースや技術的な詳細はログに出力し、ユーザーには簡潔なメッセージのみを表示
- SQLエラーやシステムエラーの生メッセージは表示しない

## 備考

- overlay_support パッケージを使用してオーバーレイ表示を実現
- 赤色（Colors.red）は直感的にエラーを示す色として選定
- 国際化対応済み（`.localized()` メソッドによる多言語サポート）
- 空文字列のエラーメッセージも許容（`""` が渡された場合）

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | show_message.dart | `lib/widgets/show_message.dart` | ShowMessageクラスのerrorNotificationメソッド |

**読解のコツ**: successNotification との差異（背景色、アイコン、タイトル）に注目する。

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

エラー状態検出の仕組みを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | cart_screen_state.dart | `lib/screens/cart_screen/bloc/cart_screen_state.dart` | CartStatus.failの定義 |

**主要処理フロー**:
1. **行17**: `enum CartStatus { success, fail }` - 状態列挙型の定義
2. 各Stateクラスの `.fail()` コンストラクタでerror文字列を保持

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

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

**主要処理フロー**:
- **行38-56**: `errorNotification()` メソッド
- **行39**: `showSimpleNotification` 関数呼び出し
- **行40-44**: タイトルテキスト（Failed、白色、太字、16px）
- **行45**: context引数
- **行46**: 背景色（Colors.red）
- **行47-50**: リーディングアイコン（cancel_outlined、白色）
- **行51**: スワイプ消去方向（上方向）
- **行52-55**: サブタイトル（エラーメッセージ、白色）

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | cart_screen.dart | `lib/screens/cart_screen/cart_screen.dart` | BlocConsumer listenerでのエラー検出 |

**主要処理フロー**:
- **行64-66**: RemoveCartItemState.failでのエラー通知
- **行74-76**: RemoveAllCartItemState.failでのエラー通知
- **行83-85**: AddCouponState.failでのエラー通知
- **行91-93**: RemoveCouponCartState.failでのエラー通知
- **行100-101**: MoveToCartState.failでのエラー通知
- **行107-109**: UpdateCartState.failでのエラー通知

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

```
BlocConsumer（各画面）
    |
    +-- listener（状態変化検出）
            |
            +-- State.fail 判定
                    |
                    +-- state.error 取得
                            |
                            +-- ShowMessage.errorNotification(error, context)
                                    |
                                    +-- showSimpleNotification()
                                            |
                                            +-- OverlaySupport（オーバーレイ描画）
                                                    |
                                                    +-- 画面上部に赤色通知表示
```

### データフロー図

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

ユーザー操作 ──────▶ API呼び出し ──────▶ エラーレスポンス
                                                |
                                                ▼
                                        エラーメッセージ抽出
                                                |
                                                ▼
                                        BLoC State.fail(error)
                                                |
                                                ▼
                                        listener検出
                                                |
                                                ▼
                                        errorNotification(error, context)
                                                |
                                                ▼
                                        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` | ソース | カート操作でのエラー通知呼び出し例 |
| cart_screen_state.dart | `lib/screens/cart_screen/bloc/cart_screen_state.dart` | ソース | エラー状態の定義 |
| string_constants.dart | `lib/utils/string_constants.dart` | 設定 | 「failed」文字列定数 |
| application_localization.dart | `lib/utils/application_localization.dart` | ソース | 多言語対応処理 |
