# 通知設計書 51-インターネット接続エラー通知

## 概要

本ドキュメントは、Bagisto モバイルアプリにおけるインターネット接続エラー通知の設計を記載する。ネットワーク接続がない状態でユーザーが操作を試みた際に、エラー状態を明確に伝えるためのアプリ内通知機能の仕様を定義する。

### 本通知の処理概要

インターネット接続エラー通知は、ユーザーがネットワーク接続を必要とする操作（画面遷移、データ取得、商品操作など）を実行しようとした際に、接続がない場合にエラーを通知する機能である。

**業務上の目的・背景**：ECアプリでは商品閲覧、カート操作、注文処理など、ほぼすべての機能がサーバーとの通信を必要とする。ネットワーク接続がない状態でユーザーが操作を試みた場合、なぜ操作が失敗したかを明確に伝えることで、ユーザーの混乱を防ぎ、適切な対処（Wi-Fi接続、モバイルデータの確認など）を促すことができる。また、無駄なAPI呼び出しを事前に防ぐことで、アプリのパフォーマンスと安定性を向上させる。

**通知の送信タイミング**：`checkInternetConnection()` 関数が呼び出され、戻り値が `false`（接続なし）の場合に即座に通知が表示される。具体的には、ドロワーメニューからのダッシュボード遷移、ダウンロード商品画面遷移、カテゴリ画面遷移などの操作時にチェックが行われる。

**通知の受信者**：現在アプリを操作しているユーザー本人。端末上でリアルタイムに通知が表示される。

**通知内容の概要**：赤色背景のオーバーレイ通知で、タイトル「Failed」（失敗）とメッセージ「インターネット接続を確認してください」が表示される。キャンセルアイコン付き。

**期待されるアクション**：ユーザーは通知を確認後、Wi-Fi設定の確認、モバイルデータ通信の有効化、電波状況の良い場所への移動など、ネットワーク接続を回復するための対処を行い、再度操作を試みることが期待される。

## 通知種別

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

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（即座に画面上部に表示） |
| 優先度 | 高（ユーザー操作のブロッキング通知） |
| リトライ | 無（ユーザーによる再操作が必要） |

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

操作を試みたユーザー本人に対してのみ表示される。端末上のローカル通知であり、送信先の決定ロジックは不要。

## 通知テンプレート

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

| 項目 | 内容 |
|-----|------|
| 表示位置 | 画面上部オーバーレイ |
| 背景色 | 赤色（Colors.red） |
| アイコン | キャンセルアイコン（Icons.cancel_outlined） |
| 表示時間 | 自動消去（overlay_support パッケージのデフォルト） |

### 本文テンプレート

```
タイトル: Failed（StringConstants.failed）
メッセージ: インターネット接続を確認してください（StringConstants.internetIssue）
```

### 添付ファイル

なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| StringConstants.failed | 通知タイトル | lib/utils/string_constants.dart | Yes |
| StringConstants.internetIssue | エラーメッセージ | lib/utils/string_constants.dart | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 画面操作 | ドロワーメニューからダッシュボード遷移タップ | checkInternetConnection() == false | ダッシュボード画面への遷移前にネットワークチェック |
| 画面操作 | ドロワーメニューからダウンロード商品遷移タップ | checkInternetConnection() == false | ダウンロード商品画面への遷移前にネットワークチェック |
| 画面操作 | カテゴリアイテムダブルタップ | checkInternetConnection() == false | カテゴリ画面への遷移前にネットワークチェック |
| 画面操作 | 新商品ビューでの操作 | checkInternetConnection() == false | 商品操作前にネットワークチェック |
| 画面操作 | カルーセルスライダーでの操作 | checkInternetConnection() == false | スライダー操作前にネットワークチェック |
| 画面操作 | 商品画面での画像表示 | checkInternetConnection() == false | 画像取得前にネットワークチェック |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| ネットワーク接続あり | checkInternetConnection() が true を返す場合は通知しない |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[ユーザー操作] --> B[checkInternetConnection呼び出し]
    B --> C{接続状態確認}
    C -->|接続あり true| D[通常処理続行]
    C -->|接続なし false| E[ShowMessage.showNotification呼び出し]
    E --> F[オーバーレイ通知表示]
    F --> G[自動消去]
    D --> H[画面遷移・データ取得]
```

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

### 参照テーブル一覧

なし（ローカル処理のみ）

### 更新テーブル一覧

なし（ローカル処理のみ、ログは端末内に保持されない）

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| InternetConnectionChecker 例外 | ライブラリ初期化失敗 | デフォルトで接続なしとして扱い通知表示 |

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

24時間いつでも表示可能

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

- 個人情報は含まれない
- ローカル処理のみのため、外部への情報漏洩リスクなし
- ネットワーク状態のチェックには internet_connection_checker パッケージを使用

## 備考

- 通知は overlay_support パッケージを使用してオーバーレイ表示される
- ユーザーは通知を上方向にスワイプして手動で消去可能（slideDismissDirection: DismissDirection.up）
- 多言語対応済み（localized() メソッドで翻訳テキストを取得）

---

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

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

### 推奨読解順序

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

インターネット接続チェックの結果とShowMessageクラスの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | string_constants.dart | `lib/utils/string_constants.dart` | StringConstants.internetIssue、StringConstants.failed の定義（126行目、133行目） |

**読解のコツ**: Dart の静的定数として定義されており、localized() メソッドで多言語対応テキストに変換される。

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

ネットワークチェックの実装とその呼び出し元を特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | check_internet_connection.dart | `lib/utils/check_internet_connection.dart` | checkInternetConnection() 関数の実装（13-16行目） |

**主要処理フロー**:
1. **13行目**: checkInternetConnection() 関数定義
2. **14行目**: InternetConnectionChecker.createInstance().hasConnection で接続状態を取得
3. **15行目**: bool 値を返却

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

ShowMessage クラスの showNotification メソッドの実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | show_message.dart | `lib/widgets/show_message.dart` | showNotification メソッドの実装（79-94行目） |

**主要処理フロー**:
- **79行目**: showNotification メソッド定義（title, message, color, icon を引数に取る）
- **81行目**: showSimpleNotification でオーバーレイ通知を表示
- **88行目**: slideDismissDirection でスワイプ消去方向を設定

#### Step 4: 呼び出し元を理解する

ドロワーメニューやカテゴリアイテムからの呼び出しを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | drawer_list_view.dart | `lib/screens/drawer/drawer_list_view.dart` | ダッシュボード遷移時のチェック（188-199行目）、ダウンロード商品遷移時のチェック（209-219行目） |
| 4-2 | drawer_category_item.dart | `lib/screens/drawer/widget/drawer_category_item.dart` | カテゴリダブルタップ時のチェック（31-45行目） |

**主要処理フロー**:
- **drawer_list_view.dart 188行目**: checkInternetConnection().then で接続チェック後の処理
- **drawer_list_view.dart 193-197行目**: 接続なしの場合、ShowMessage.showNotification を呼び出し
- **drawer_category_item.dart 31行目**: onDoubleTap で接続チェック
- **drawer_category_item.dart 42-43行目**: 接続なしの場合の通知表示

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

```
ユーザー操作（タップ/ダブルタップ）
    │
    ├─ DrawerListView.build()
    │      └─ checkInternetConnection()
    │             └─ InternetConnectionChecker.hasConnection
    │      └─ ShowMessage.showNotification()
    │             └─ showSimpleNotification()
    │
    └─ DrawerCategoryItem.build()
           └─ checkInternetConnection()
                  └─ InternetConnectionChecker.hasConnection
           └─ ShowMessage.showNotification()
                  └─ showSimpleNotification()
```

### データフロー図

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

ユーザータップ ───▶ checkInternetConnection() ───▶ bool（接続状態）
                         │
                         ▼
               ┌─────────┴─────────┐
               │                   │
           接続あり              接続なし
               │                   │
               ▼                   ▼
         通常処理続行      ShowMessage.showNotification()
                                   │
                                   ▼
                          オーバーレイ通知表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| check_internet_connection.dart | `lib/utils/check_internet_connection.dart` | ソース | ネットワーク接続チェック関数 |
| show_message.dart | `lib/widgets/show_message.dart` | ソース | 通知表示ユーティリティクラス |
| string_constants.dart | `lib/utils/string_constants.dart` | ソース | 文字列定数定義 |
| drawer_list_view.dart | `lib/screens/drawer/drawer_list_view.dart` | ソース | ドロワーメニュー画面 |
| drawer_category_item.dart | `lib/screens/drawer/widget/drawer_category_item.dart` | ソース | カテゴリアイテムウィジェット |
| new_product_view.dart | `lib/screens/home_page/widget/new_product_view.dart` | ソース | 新商品ビュー |
| carousal_slider.dart | `lib/screens/home_page/widget/carousal_slider.dart` | ソース | カルーセルスライダー |
| product_image_view.dart | `lib/screens/product_screen/view/product_image_view.dart` | ソース | 商品画像ビュー |
| product_screen.dart | `lib/screens/product_screen/view/product_screen.dart` | ソース | 商品詳細画面 |
