# 通知設計書 43-注文エラー通知

## 概要

本ドキュメントは、チェックアウト処理の最終段階で注文処理がエラーとなった場合に表示されるエラー通知の設計について記述する。

### 本通知の処理概要

本通知は、注文確定処理（SaveOrder）において、サーバー側で注文処理が失敗した場合に表示されるエラー通知である。

**業務上の目的・背景**：ECアプリにおいて、注文処理は決済、在庫確保、配送手配など複数のサブシステムが連携する複雑な処理である。何らかの理由で注文処理が失敗した場合、ユーザーに即座にエラーを通知し、適切な対処（商品の追加、カートの見直し等）を促す必要がある。本通知により、注文失敗をユーザーに明示し、次のアクションを促すことを目的とする。

**通知の送信タイミング**：注文確定画面（SaveOrder画面）において、SaveOrderFetchDataEvent の処理結果として SaveOrderFetchDataState の status が fail となった場合に即時表示される。

**通知の受信者**：チェックアウト操作を行っている現在のユーザー（アプリ操作者）。ログイン済みユーザーおよびゲストユーザーの両方が対象となる。

**通知内容の概要**：エラーメッセージとして、サーバーから返却されたエラーメッセージと「商品を追加してください」という趣旨の追加メッセージが表示される。画面中央にエラーメッセージが表示される形式となっている。

**期待されるアクション**：ユーザーは通知を確認後、カートに商品を追加するか、カートの内容を見直すか、決済情報を確認するか、カスタマーサポートに連絡して問題を解決する。

## 通知種別

アプリ内通知（画面内エラーメッセージ表示）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（即時表示） |
| 優先度 | 高 |
| リトライ | 無し（即時1回表示） |

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

操作中のユーザーに対して即時表示。特定の送信先決定ロジックは不要。

## 通知テンプレート

### アプリ内通知

| 項目 | 内容 |
|-----|------|
| 表示形式 | ErrorMessage.errorMsg（画面内エラーメッセージ） |
| 表示位置 | 画面中央 |
| 背景色 | 画面背景色（通常のUI） |
| アイコン | なし |

### 本文テンプレート

```
[メッセージ]: {サーバーエラーメッセージ} 商品を追加してください
（{state.error} + StringConstants.addMoreProductsMsg のローカライズ値）
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| error | サーバーから返却されたエラーメッセージ | state.error | Yes |
| addMoreProductsMsg | 商品追加を促すメッセージ | StringConstants.addMoreProductsMsg | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| API応答 | SaveOrderFetchDataState 受信 | status == SaveOrderStatus.fail | 注文保存処理が失敗した場合 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| status == SaveOrderStatus.success | 注文が正常に完了した場合は通知を表示しない |
| redirectUrl が存在する | 外部決済ページへリダイレクトする場合は通知を表示しない |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[注文確定リクエスト送信] --> B[SaveOrderFetchDataState 受信]
    B --> C{status == success?}
    C -->|Yes| D{redirectUrl存在?}
    D -->|Yes| E[外部決済ページへリダイレクト]
    D -->|No| F[注文完了画面表示]
    C -->|No| G[ErrorMessage.errorMsg 表示]
    G --> H[ユーザーがカートを見直し]
```

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

### 参照テーブル一覧

本通知はクライアント側で処理が完結するが、注文処理自体はサーバー側で以下のテーブルを参照・更新する。

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| orders | 注文情報 | サーバー側で注文作成時に INSERT |
| cart | カート情報 | 注文完了後にクリア |
| inventory | 在庫情報 | 在庫確保処理で UPDATE |

### 更新テーブル一覧

該当なし（クライアント側での更新はなし）

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 在庫不足 | 注文商品の在庫が不足 | 本通知を表示し、商品追加または削除を促す |
| 決済エラー | 決済処理が失敗 | 本通知を表示し、決済情報の確認を促す |
| カートエラー | カート内に購入不可の商品が存在 | 本通知を表示し、カートの見直しを促す |
| サーバーエラー | サーバー側の内部エラー | 本通知を表示し、再試行を促す |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（自動リトライなし） |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし（ユーザーによる手動リトライ） |

## 配信設定

### レート制限

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

### 配信時間帯

制限なし（24時間）

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

- エラーメッセージにはセンシティブな情報（決済情報、個人情報）を含めない
- サーバー側のスタックトレースや詳細なエラー情報はクライアントに返却しない

## 備考

- 本通知は ErrorMessage.errorMsg ウィジェットを使用して画面内に表示される
- PayPal決済の場合、エラー時には ShowMessage.errorNotification も使用される（333-335行目）
- 注文処理が成功した場合は注文完了画面（_orderPlacedView）が表示される

---

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

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

### 推奨読解順序

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

まず、注文保存のレスポンスデータモデルを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | save_order_model.dart | `lib/screens/checkout/data_model/save_order_model.dart` | SaveOrderModel クラスの構造を確認 |

**読解のコツ**: GraphQL API レスポンスのデータモデルと、order, redirectUrl などのフィールドに注目する。

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

処理の起点となる BlocBuilder の buildUI メソッドを特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | save_order.dart | `lib/screens/checkout/checkout_save_order/view/save_order.dart` | buildUI メソッド（176-199行目）を確認 |

**主要処理フロー**:
1. **176-199行目**: buildUI メソッドで状態に応じたUIを構築
2. **177行目**: SaveOrderFetchDataState の判定
3. **188-192行目**: status == SaveOrderStatus.fail の場合の ErrorMessage.errorMsg 表示

#### Step 3: エラーメッセージ表示処理を理解する

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | error_message.dart | `lib/widgets/error_message.dart` | errorMsg メソッドの実装詳細を確認 |

**主要処理フロー**:
- エラーメッセージを中央に表示するウィジェットを返却

#### Step 4: 文字列定数を理解する

通知に使用される文字列定数を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | string_constants.dart | `lib/utils/string_constants.dart` | addMoreProductsMsg（219行目）の定義を確認 |

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

```
CheckOutSaveOrder
    │
    ├─ initState
    │      └─ SaveOrderBloc.add(SaveOrderFetchDataEvent)
    │
    ├─ _saveOrderBloc
    │      └─ BlocConsumer
    │             ├─ builder → buildUI
    │             │      ├─ SaveOrderFetchDataState (success)
    │             │      │      └─ _orderPlacedView または リダイレクト
    │             │      └─ SaveOrderFetchDataState (fail)
    │             │             └─ ErrorMessage.errorMsg
    │             └─ listener（PayPal決済時のエラーハンドリング）
    │
    └─ paypalView（PayPal決済時の処理）
           └─ onError → ShowMessage.errorNotification
```

### データフロー図

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

注文確定リクエスト ───▶ SaveOrderFetchDataEvent ───▶ API呼び出し
                                                          │
                                                          ▼
                                               SaveOrderFetchDataState
                                                          │
                                                   ┌──────┴──────┐
                                                   ▼             ▼
                                               success         fail
                                                   │             │
                                                   ▼             ▼
                                            注文完了画面    エラーメッセージ表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| save_order.dart | `lib/screens/checkout/checkout_save_order/view/save_order.dart` | ソース | 注文保存画面のWidget、通知トリガーの発火元 |
| error_message.dart | `lib/widgets/error_message.dart` | ソース | エラーメッセージ表示ウィジェット |
| show_message.dart | `lib/widgets/show_message.dart` | ソース | 通知表示ユーティリティクラス（PayPal決済エラー時） |
| string_constants.dart | `lib/utils/string_constants.dart` | ソース | 文字列定数の定義 |
| save_order_model.dart | `lib/screens/checkout/data_model/save_order_model.dart` | ソース | 注文保存APIレスポンスのデータモデル |
| save_order_bloc.dart | `lib/screens/checkout/checkout_save_order/bloc/save_order_bloc.dart` | ソース | 注文保存のBLoC |
