# 通知設計書 5-警告通知（Warning Notification）

## 概要

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

### 本通知の処理概要

本通知は、ユーザーへの注意喚起や警告が必要な場合に、画面上部にオーバーレイ形式で黄色（amber）の背景を持つ警告メッセージを表示する機能を提供する。警告アイコン付きで、視覚的に注意が必要なことを伝達する。

**業務上の目的・背景**：ECアプリにおいて、エラーではないが注意が必要な状況（必須項目の未入力、推奨されない操作、確認が必要な状態など）をユーザーに伝達する必要がある。警告通知により、ユーザーは問題を未然に防ぎ、スムーズに操作を完了できる。成功通知（緑）やエラー通知（赤）とは異なる黄色の背景により、視覚的に「注意」という中間的な状態を表現する。

**通知の送信タイミング**：バリデーション警告、確認が必要な操作、推奨アクションの提案など、ユーザーの注意を引く必要がある時点で表示される。アプリ終了確認、必須オプション未選択、在庫警告なども含まれる。

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

**通知内容の概要**：「Warning」（警告）というタイトル（またはカスタムタイトル）と、注意が必要な内容を示す具体的なメッセージ。黄色（amber）の背景と警告アイコンで視覚的に注意を喚起。

**期待されるアクション**：ユーザーは警告メッセージを確認し、必要に応じて入力内容の修正や操作の確認を行う。警告の内容に応じて適切なアクションを取ることが期待される。

## 通知種別

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

## 送信仕様

### 基本情報

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

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

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

## 通知テンプレート

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

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

### 本文テンプレート

```
タイトル: {title} ?? "Warning" (StringConstants.warning.localized())
サブタイトル: {msg} - 警告メッセージ
```

### 添付ファイル

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

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| msg | 警告メッセージ | 呼び出し元から渡される | Yes |
| context | ビルドコンテキスト | Flutter Widget | Yes |
| title | カスタムタイトル | 呼び出し元から渡される（オプション） | No |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| バリデーション | バリエーション未選択 | 設定可能商品でオプション未選択 | product_screen.dart |
| バリデーション | 必須オプション未入力 | カスタマイズオプションが未入力 | product_screen.dart |
| バリデーション | グループ商品未選択 | 最低1つの商品が選択されていない | product_screen.dart |
| バリデーション | ダウンロードリンク未選択 | ダウンロード商品でリンク未選択 | product_screen.dart |
| バリデーション | 予約メモ未入力 | テーブル予約で特別リクエストメモ未入力 | product_screen.dart |
| 確認操作 | アプリ終了確認 | バックボタン2回押下時 | error_handler.dart |

### 送信抑止条件

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

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[ユーザー操作検出] --> B{バリデーション/確認条件}
    B -->|条件該当| C[警告メッセージ決定]
    B -->|条件なし| D[通常処理継続]
    C --> E[ShowMessage.warningNotification呼び出し]
    E --> F{カスタムタイトル指定?}
    F -->|Yes| G[指定タイトル使用]
    F -->|No| H[デフォルト Warning 使用]
    G --> I[showSimpleNotification実行]
    H --> I
    I --> J[オーバーレイ表示]
    J --> K{ユーザーアクション}
    K -->|スワイプ| L[即座に消去]
    K -->|放置| M[自動消去]
    L --> N[ユーザーが対処検討]
    M --> N
```

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

### 参照テーブル一覧

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

### 更新テーブル一覧

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

制限なし（警告発生に連動）

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

- 警告メッセージには機密情報を含めない
- ユーザーへの注意喚起のみを目的とする
- 不正なメッセージインジェクションを防止

## 備考

- overlay_support パッケージを使用してオーバーレイ表示を実現
- 黄色（Colors.amber）は直感的に「警告・注意」を示す色として選定
- カスタムタイトルを指定可能（title引数、オプション）
- 国際化対応済み（`.localized()` メソッドによる多言語サポート）
- 成功（緑）とエラー（赤）の中間的な重要度を表現

---

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

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

### 推奨読解順序

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

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

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

**読解のコツ**: success/errorNotification との差異（背景色、アイコン、オプショナルなtitle引数）に注目する。

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

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

**主要処理フロー**:
- **行58-77**: `warningNotification()` メソッド
- **行58-59**: 引数にオプショナルな `{String? title}` を持つ
- **行60**: `showSimpleNotification` 関数呼び出し
- **行61**: タイトル: `title ?? StringConstants.warning.localized()` - nullの場合はデフォルト「Warning」を使用
- **行65**: context引数
- **行66**: 背景色（Colors.amber）
- **行67-70**: リーディングアイコン（warning_amber、白色）
- **行71**: スワイプ消去方向（上方向）
- **行72-75**: サブタイトル（警告メッセージ、白色）

#### Step 3: 呼び出し元を理解する（商品画面の例）

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | product_screen.dart | `lib/screens/product_screen/view/product_screen.dart` | _addToCartメソッドでの警告表示 |

**主要処理フロー**:
- バリエーション未選択時: `ShowMessage.warningNotification(StringConstants.pleaseSelectVariants.localized(), context)`
- 必須オプション未入力時: `ShowMessage.warningNotification(...)`
- グループ商品未選択時: `ShowMessage.warningNotification(StringConstants.atLeastOneWarning.localized(), context)`
- ダウンロードリンク未選択時: `ShowMessage.warningNotification(StringConstants.linkRequired.localized(), context)`
- 予約メモ未入力時: `ShowMessage.warningNotification(StringConstants.specialRequestNotesRequired.localized(), context)`

#### Step 4: アプリ終了確認の例

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | error_handler.dart | `lib/screens/home_page/utils/error_handler.dart` | アプリ終了確認時の警告表示 |

**主要処理フロー**:
- バックボタン2回押下時に `ShowMessage.warningNotification` を呼び出し
- カスタムタイトルを使用する場合あり

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

```
各画面（product_screen, home_page等）
    |
    +-- バリデーション/確認処理
            |
            +-- 条件該当判定
                    |
                    +-- ShowMessage.warningNotification(msg, context, {title})
                            |
                            +-- title ?? StringConstants.warning.localized()
                            |
                            +-- showSimpleNotification()
                                    |
                                    +-- OverlaySupport（オーバーレイ描画）
                                            |
                                            +-- 画面上部に黄色通知表示
```

### データフロー図

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

ユーザー操作 ──────▶ バリデーション判定 ──────▶ 警告条件該当
                                                    |
                                                    ▼
                                            メッセージ決定
                                                    |
                                                    ▼
                                            warningNotification(msg, context, {title})
                                                    |
                               ┌────────────────────┴────────────────────┐
                               ▼                                         ▼
                        title指定あり                              title指定なし
                               |                                         |
                               ▼                                         ▼
                        カスタムタイトル使用                      "Warning"使用
                               |                                         |
                               └──────────────┬──────────────────────────┘
                                              ▼
                                    showSimpleNotification()
                                              |
                                              ▼
                                    オーバーレイ表示 ──────▶ ユーザーに注意喚起
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| show_message.dart | `lib/widgets/show_message.dart` | ソース | 警告通知の表示処理 |
| main.dart | `lib/main.dart` | ソース | OverlaySupport.globalの初期化 |
| product_screen.dart | `lib/screens/product_screen/view/product_screen.dart` | ソース | 商品画面でのバリデーション警告例 |
| error_handler.dart | `lib/screens/home_page/utils/error_handler.dart` | ソース | アプリ終了確認の警告例 |
| string_constants.dart | `lib/utils/string_constants.dart` | 設定 | 「warning」等の文字列定数 |
| application_localization.dart | `lib/utils/application_localization.dart` | ソース | 多言語対応処理 |
