# 通知設計書 52-アプリ終了確認通知

## 概要

本ドキュメントは、Bagisto モバイルアプリにおけるアプリ終了確認通知の設計を記載する。ユーザーが意図しないアプリ終了を防止するため、バックボタン押下時に警告通知を表示し、確認を促す機能の仕様を定義する。

### 本通知の処理概要

アプリ終了確認通知は、ユーザーがホーム画面等でバックボタンを押下した際に、アプリを終了する前に警告メッセージを表示し、誤操作によるアプリ終了を防止する機能である。

**業務上の目的・背景**：ECアプリでは、カート内の商品選択や閲覧中の商品情報など、ユーザーセッション中の状態が重要である。誤ってバックボタンを押下してアプリを終了してしまうと、それらの情報が失われたり、ユーザー体験が損なわれる可能性がある。本通知により、ユーザーに終了の意思確認を行い、誤操作を防止することで、ユーザビリティの向上を図る。特にAndroid端末ではハードウェア/ソフトウェアのバックボタンが存在するため、この対策が重要である。

**通知の送信タイミング**：ホームページ画面等でバックボタンが押下された際に、インターネット接続エラー後のダイアログ確認操作（OKボタン押下）時に警告通知が表示される。具体的には `homePageError` 関数内で AlertDialog の OK ボタン押下後に表示される。

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

**通知内容の概要**：黄色（amber）背景のオーバーレイ通知で、タイトル「Warning」（警告）とメッセージ「アプリを閉じます」（closeApp）が表示される。警告アイコン付き。

**期待されるアクション**：ユーザーは通知を確認後、2秒以内に再度バックボタンを押下するとアプリが終了する。逆に、何もしなければ通知が消えてアプリは継続使用できる。これにより、ユーザーは意図的な終了か誤操作かを判断する時間が与えられる。

## 通知種別

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

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（即座に画面上部に表示） |
| 優先度 | 高（ユーザー操作に対する確認通知） |
| リトライ | 無（単発の警告通知） |

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

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

## 通知テンプレート

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

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

### 本文テンプレート

```
タイトル: Warning（StringConstants.warning）
メッセージ: アプリを閉じます（StringConstants.closeApp）
```

### 添付ファイル

なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| StringConstants.warning | 通知タイトル（デフォルト） | lib/utils/string_constants.dart | Yes |
| StringConstants.closeApp | 終了確認メッセージ | lib/utils/string_constants.dart | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 画面操作 | AlertDialog OKボタン押下 | homePageError ダイアログ表示後 | ネットワークエラーダイアログのOK押下時に終了警告を表示 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| AlertDialog が表示されていない | homePageError が呼び出されていない場合は通知しない |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[ネットワークエラー発生] --> B[homePageError呼び出し]
    B --> C[AlertDialog表示]
    C --> D{OKボタン押下}
    D -->|押下| E[Navigator.pop]
    E --> F[warningNotification表示]
    F --> G[2秒待機]
    G --> H[アプリ終了処理コメントアウト]
    D -->|ダイアログ外タップ| I[ダイアログ閉じる]
```

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

### 参照テーブル一覧

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

### 更新テーブル一覧

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

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| Context無効 | Navigator.pop後にContextが無効になった場合 | エラーハンドリングなし（通常は発生しない） |

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

24時間いつでも表示可能

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

- 個人情報は含まれない
- ローカル処理のみのため、外部への情報漏洩リスクなし
- アプリ終了処理（exit(0)）は現在コメントアウトされている

## 備考

- 通知は overlay_support パッケージを使用してオーバーレイ表示される
- ユーザーは通知を上方向にスワイプして手動で消去可能
- 多言語対応済み（localized() メソッドで翻訳テキストを取得）
- 現状のコードでは `exit(0)` がコメントアウトされており、実際のアプリ終了は行われない
- Future.delayed で2秒の遅延が設定されているが、終了処理はコメントアウト

---

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

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

### 推奨読解順序

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

文字列定数とShowMessageクラスの構造を理解する。

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

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

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

homePageError 関数の実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | error_handler.dart | `lib/screens/home_page/utils/error_handler.dart` | homePageError 関数の実装（16-37行目） |

**主要処理フロー**:
1. **16行目**: homePageError 関数定義（error, context を引数）
2. **17-36行目**: showDialog でAlertDialogを表示
3. **22行目**: AlertDialog タイトル「インターネット接続問題」
4. **24-32行目**: OKボタン押下時の処理
5. **26行目**: Navigator.pop でダイアログを閉じる
6. **27行目**: warningNotification で終了警告を表示
7. **28-30行目**: 2秒遅延後の終了処理（コメントアウト）

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

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

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

**主要処理フロー**:
- **58行目**: warningNotification メソッド定義（msg, context, title を引数）
- **60行目**: showSimpleNotification でオーバーレイ通知を表示
- **61行目**: title が null の場合は StringConstants.warning を使用
- **66行目**: 背景色 Colors.amber（黄色）
- **67-69行目**: 警告アイコン（Icons.warning_amber）
- **71行目**: slideDismissDirection で上方向スワイプ消去

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

```
ネットワークエラー発生
    │
    └─ homePageError(error, context)
           │
           ├─ showDialog()
           │      └─ AlertDialog
           │             └─ MaterialButton (OK)
           │                    ├─ Navigator.pop()
           │                    └─ ShowMessage.warningNotification()
           │                           └─ showSimpleNotification()
           │
           └─ Future.delayed(2秒)
                  └─ exit(0) // コメントアウト
```

### データフロー図

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

ネットワークエラー ───▶ homePageError() ───▶ AlertDialog表示
                              │
                              ▼
                    OKボタン押下イベント
                              │
                              ▼
                    Navigator.pop(context)
                              │
                              ▼
                    warningNotification()
                              │
                              ▼
                    オーバーレイ通知表示
                              │
                              ▼
                    Future.delayed(2秒)
                              │
                              ▼
                    [アプリ終了 - 現在無効]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| error_handler.dart | `lib/screens/home_page/utils/error_handler.dart` | ソース | エラーハンドリング関数 |
| show_message.dart | `lib/widgets/show_message.dart` | ソース | 通知表示ユーティリティクラス |
| string_constants.dart | `lib/utils/string_constants.dart` | ソース | 文字列定数定義 |
| index.dart | `lib/screens/home_page/utils/index.dart` | ソース | home_page utils のエクスポート |
