# 通知設計書 30-住所追加/更新成功通知

## 概要

本ドキュメントは、配送先住所の追加または更新が成功した際に表示される通知の設計について記載する。

### 本通知の処理概要

本通知は、ユーザーが住所追加/編集画面で配送先住所の新規追加または既存住所の更新を行った際に、その操作結果をフィードバックするためのアプリ内通知機能である。

**業務上の目的・背景**：ECアプリにおいて、配送先住所の管理は注文処理に不可欠な機能である。ユーザーが住所情報を追加・更新した際に、操作が成功したか失敗したかを明確にフィードバックすることで、正確な住所情報が登録されていることをユーザーに確認させ、配送トラブルを防止する。住所情報には必須項目が多いため、バリデーションエラー時の適切な通知も重要である。

**通知の送信タイミング**：ユーザーが「住所を保存」ボタンをタップし、BLoCがAPIレスポンスを受信した直後に通知が表示される。成功時は通知表示後に画面を閉じて前の画面に戻る。

**通知の受信者**：操作を実行したユーザー本人のみがアプリ内通知を受信する。

**通知内容の概要**：成功時は緑色の背景でチェックマークアイコン付きの成功通知、失敗時は赤色の背景でキャンセルアイコン付きのエラー通知が表示される。

**期待されるアクション**：成功通知を受け取った場合、ユーザーは住所が正常に保存されたことを確認し、次の操作（チェックアウト等）に進む。失敗通知を受け取った場合、ユーザーは入力内容を確認し、エラーを修正して再度保存を試みる。

## 通知種別

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

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（API応答後即時表示） |
| 優先度 | 高 |
| リトライ | なし |

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

操作を実行したユーザーのデバイス上のみに表示される。

## 通知テンプレート

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

| 項目 | 成功時 | 失敗時 |
|-----|-------|-------|
| タイトル | "Success"（ローカライズ対応） | "Failed"（ローカライズ対応） |
| 背景色 | Colors.green.shade400 | Colors.red |
| アイコン | Icons.check_circle_outline | Icons.cancel_outlined |

### 本文テンプレート

```
新規追加成功時: {BaseModel.message}
更新成功時: {UpdateAddressModel.message}
失敗時: {State.errorまたはgraphqlErrors}
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| message | 成功時のメッセージ | BaseModel.message / UpdateAddressModel.message | Yes |
| error | 失敗時のメッセージ | State.error | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 画面操作 | FetchAddAddressEvent | API処理完了後 | 新規住所追加 |
| 画面操作 | FetchEditAddressEvent | API処理完了後 | 既存住所更新 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| 該当なし | API処理完了時は常に通知表示 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[ユーザーが住所保存ボタンをタップ] --> B{新規追加 or 更新?}
    B -->|新規追加| C[FetchAddAddressEvent発行]
    B -->|更新| D[FetchEditAddressEvent発行]
    C --> E[AddEditAddressBloc処理]
    D --> E
    E --> F[API呼び出し]
    F --> G{APIレスポンス}
    G -->|成功| H[ShowMessage.successNotification表示]
    G -->|失敗| I[ShowMessage.errorNotification表示]
    H --> J[Navigator.pop 画面を閉じる]
    I --> K[Navigator.pop 画面を閉じる]
    J --> L[終了]
    K --> L
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| countries | 国一覧 | ドロップダウン表示用 |
| states | 州/県一覧 | ドロップダウン表示用 |
| customer_addresses | 既存住所情報 | 編集時の初期値 |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| customer_addresses | INSERT | 新規住所追加 |
| customer_addresses | UPDATE | 既存住所更新 |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| バリデーションエラー | 必須項目未入力 | フォームバリデーションで事前チェック |
| API失敗 | サーバーエラー等 | エラー通知を表示 |
| ネットワークエラー | インターネット接続なし | エラー通知を表示 |

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

24時間対応

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

- ユーザー認証状態の確認必須
- 住所情報は個人情報のためHTTPS通信必須
- 他ユーザーの住所を操作できないようサーバー側で認証チェック

## 備考

- 成功時は画面を2回popすることで住所一覧画面に戻る（Future.delayedで遅延実行）
- isEditフラグで新規追加と更新を区別
- チェックアウト画面から呼び出された場合はisCheckoutフラグがtrue
- 位置情報からの住所入力にも対応（LocationScreen連携）

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | add_edit_address_state.dart | `lib/screens/add_edit_address/bloc/add_edit_address_state.dart` | FetchAddAddressState, FetchEditAddressStateの構造 |
| 1-2 | update_address_model.dart | `lib/screens/address_list/data_model/update_address_model.dart` | UpdateAddressModelの構造 |

**読解のコツ**: 新規追加はBaseModelを、更新はUpdateAddressModelをレスポンスとして使用。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | add_edit_address_screen.dart | `lib/screens/add_edit_address/view/add_edit_address_screen.dart` | BlocConsumerのlistener部分（行175-271）で通知表示処理を確認 |

**主要処理フロー**:
1. **行176-221**: FetchEditAddressState処理（更新）
2. **行222-269**: FetchAddAddressState処理（新規追加）

#### Step 3: BLoC処理層を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | add_edit_address_bloc.dart | `lib/screens/add_edit_address/bloc/add_edit_address_bloc.dart` | FetchEditAddressEvent, FetchAddAddressEvent処理のロジック |

**主要処理フロー**:
- **行29-64**: FetchEditAddressEvent処理
- **行65-87**: FetchAddAddressEvent処理

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | show_message.dart | `lib/widgets/show_message.dart` | successNotification（行18-36）、errorNotification（行38-56）の実装 |

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

```
AddNewAddress (add_edit_address_screen.dart)
    │
    ├─ BlocConsumer<AddEditAddressBloc, AddEditAddressBaseState>
    │      │
    │      └─ listener (行175-271)
    │             │
    │             ├─ FetchEditAddressState (行176)
    │             │      ├─ AddEditStatus.fail → ShowMessage.errorNotification
    │             │      │                       → Navigator.pop
    │             │      └─ AddEditStatus.success → ShowMessage.successNotification
    │             │                                → Navigator.pop (2回)
    │             │
    │             └─ FetchAddAddressState (行222)
    │                    ├─ AddEditStatus.fail → ShowMessage.errorNotification
    │                    │                       → Navigator.pop
    │                    └─ AddEditStatus.success → ShowMessage.successNotification
    │                                              → Navigator.pop (2回)
    │
    └─ AddEditAddressBloc (add_edit_address_bloc.dart)
           │
           ├─ FetchEditAddressEvent処理 (行29-64)
           │      └─ repository.callEditAddressApi
           │
           └─ FetchAddAddressEvent処理 (行65-87)
                  └─ repository.callCreateAddress
```

### データフロー図

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

住所保存 ───▶ AddEditAddressEvent ───▶ AddEditAddressBloc
ボタンタップ            │                       │
                       │                       ▼
                       │            repository API呼び出し
                       │                       │
                       │                       ▼
                       │            BaseModel / UpdateAddressModel
                       │                       │
                       │                       ▼
                       │            AddEditAddressState
                       │                       │
                       ▼                       ▼
              ShowMessage.successNotification / errorNotification
                       │
                       ▼
              Navigator.pop (画面遷移)
                       │
                       ▼
              AddressData返却 (住所一覧更新用)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| add_edit_address_screen.dart | `lib/screens/add_edit_address/view/add_edit_address_screen.dart` | ソース | 画面、通知トリガー |
| add_edit_address_bloc.dart | `lib/screens/add_edit_address/bloc/add_edit_address_bloc.dart` | ソース | BLoC処理 |
| add_edit_address_state.dart | `lib/screens/add_edit_address/bloc/add_edit_address_state.dart` | ソース | 状態定義 |
| add_edit_address_event.dart | `lib/screens/add_edit_address/bloc/add_edit_address_event.dart` | ソース | イベント定義 |
| show_message.dart | `lib/widgets/show_message.dart` | ソース | 通知表示 |
| save_address_button.dart | `lib/screens/add_edit_address/view/widget/save_address_button.dart` | ソース | 保存ボタンUI |
| get_address_form.dart | `lib/screens/add_edit_address/view/widget/get_address_form.dart` | ソース | 住所入力フォーム |
