# 画面設計書 21-返金詳細画面

## 概要

本ドキュメントは、Bagisto eコマースモバイルアプリにおける返金詳細画面の設計仕様を記述したものです。注文に対して発生した返金情報を詳細に表示し、ユーザーが返金状況を確認できる機能を提供します。

### 本画面の処理概要

本画面は、注文に対して発生した返金情報を詳細に表示するための画面です。返金された商品の明細、返金金額、調整手数料などの情報を一覧形式で確認することができます。

**業務上の目的・背景**：eコマースにおいて、注文のキャンセルや返品に伴う返金処理は重要な業務プロセスです。ユーザーは自身の注文に対する返金状況を正確に把握する必要があり、返金額や調整手数料などの詳細情報を確認できる機能が求められます。本画面は、透明性のある返金情報の提供により、ユーザーの信頼を維持し、問い合わせ対応の削減に貢献します。

**画面へのアクセス方法**：注文詳細画面から「返金」タブをタップすることで本画面にアクセスします。OrderDetailからOrderRefundScreenへ遷移する際、orderDetailsModelが引数として渡されます。

**主要な操作・処理内容**：
1. 画面初期化時に注文IDに基づく返金データをAPIから取得する
2. 返金ID、返金対象商品リストを表示する
3. 各商品のSKU、商品名、価格、数量、小計、税額、総額を表示する
4. 価格詳細として小計、配送料、調整返金額、調整手数料、総額を表示する
5. 配送先・支払い情報を表示する

**画面遷移**：本画面へは注文詳細画面から遷移します。本画面から他画面への直接遷移はなく、戻るボタンで注文詳細画面に戻ります。

**権限による表示制御**：ログイン済みユーザーのみアクセス可能です。表示される返金情報は、ログイン中のユーザーの注文に関連するもののみに限定されます。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 47 | 返金詳細表示 | 主機能 | 注文の返金情報表示（返金額、調整手数料） |

## 画面種別

詳細

## URL/ルーティング

本画面はNavigator.pushによる画面遷移で表示されます。Flutter内部のルーティングとして`OrderRefundScreen`ウィジェットが直接プッシュされます。

## 入出力項目

| 項目名 | 入出力 | 型 | 必須 | 説明 |
|--------|--------|------|------|------|
| orderDetailsModel | 入力 | OrderDetail | 任意 | 注文詳細情報（注文IDを含む） |

## 表示項目

### 返金情報セクション

| 項目名 | データ型 | 説明 |
|--------|---------|------|
| 返金ID | int | 返金処理の識別ID（#形式で表示） |
| SKU | String | 商品のSKUコード |
| 商品名 | String | 返金対象商品の名称 |
| 価格 | String | 商品の単価（フォーマット済み） |
| 数量 | int | 返金対象の数量 |
| 小計 | String | 商品小計（フォーマット済み） |
| 税額 | String | 税金額（フォーマット済み） |
| 総額 | String | 商品ごとの総額（フォーマット済み） |

### 価格詳細セクション

| 項目名 | データ型 | 説明 |
|--------|---------|------|
| 小計 | String | 返金小計額 |
| 配送料 | String | 配送料の返金額 |
| 調整返金額 | String | 調整による返金額 |
| 調整手数料 | String | 調整手数料 |
| 総額 | String | 返金総額 |

### 配送・支払い情報セクション

ShippingAndPaymentInfoウィジェットにより、配送先住所と支払い方法の情報が表示されます。

## イベント仕様

### 1-画面初期化イベント

画面初期化時（initState）にOrderRefundBlocを通じてOrderRefundFetchDataEventが発行され、注文IDに基づく返金データの取得が開始されます。

処理フロー：
1. context.read<OrderRefundBloc>()でBlocインスタンスを取得
2. OrderRefundFetchDataEvent(widget.orderDetailsModel?.id ?? 0)を発行
3. OrderRefundRepositoryImp.getRefundListが呼び出される
4. API応答に基づきOrderRefundListDataStateが発行される
5. 成功時はrefundDetailsウィジェットが表示される
6. データなしの場合はEmptyDataViewが表示される

## データベース更新仕様

### 操作別データベース影響一覧

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面表示 | refunds | SELECT | 注文に紐づく返金情報を取得 |
| 画面表示 | refund_items | SELECT | 返金対象商品の明細を取得 |

### テーブル別更新項目詳細

#### refunds

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | id | order_id = {渡された注文ID} | 返金ID |
| SELECT | formatted_price | order_id = {渡された注文ID} | フォーマット済み価格情報 |

#### refund_items

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | id, name, sku, qty | refund_id = {返金ID} | 返金商品明細 |
| SELECT | formatted_price | refund_id = {返金ID} | 商品価格情報 |

## メッセージ仕様

| メッセージ種別 | メッセージキー | 表示内容 | 表示条件 |
|--------------|--------------|---------|---------|
| タイトル | StringConstants.refunds | 返金 | AppBarタイトル |
| ラベル | StringConstants.priceDetails | 価格詳細 | 価格セクションヘッダー |
| ラベル | StringConstants.subTotal | 小計 | 価格行ラベル |
| ラベル | StringConstants.shippingHandling | 配送料 | 価格行ラベル |
| ラベル | StringConstants.adjustmentRefund | 調整返金額 | 価格行ラベル |
| ラベル | StringConstants.adjustmentFee | 調整手数料 | 価格行ラベル |
| ラベル | StringConstants.grandTotal | 総額 | 価格行ラベル |

## 例外処理

| 例外状況 | 処理内容 | ユーザーへの表示 |
|---------|---------|----------------|
| 返金データなし | EmptyDataViewを表示 | データがない旨のビューを表示 |
| API通信エラー | OrderRefundListDataState.failが発行される | エラー状態に応じた表示 |
| 返金リストが空 | refundListがnullの場合EmptyDataViewを表示 | 空のデータビューを表示 |

## 備考

- 本画面は読み取り専用であり、返金情報の編集や操作は行えません
- 返金処理自体は管理画面側で実行され、本画面はその結果を表示する役割です
- ShippingAndPaymentInfoウィジェットは、注文詳細画面と共通のコンポーネントを使用しています
- 返金が複数回行われている場合、すべての返金情報がリスト形式で表示されます

---

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

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

### 推奨読解順序

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

まず、返金情報のデータ構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | order_refund_model.dart | `lib/data_model/order_model/order_refund_model.dart` | OrderRefundModel、ViewRefunds、RefundItemsの構造を理解 |
| 1-2 | order_detail_model.dart | `lib/data_model/order_model/order_detail_model.dart` | OrderDetailとFormattedPriceの構造を確認 |

**読解のコツ**: JsonSerializableアノテーションに注目し、JSONからのマッピング規則を確認してください。ViewRefundsが複数のRefundItemsを持つ親子関係になっています。

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

処理の起点となるファイル・関数を特定します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | order_refund_details.dart | `lib/screens/order_refund/order_refund_details.dart` | OrderRefundScreenクラスが本画面のエントリーポイント |

**主要処理フロー**:
1. **17-22行目**: initStateでOrderRefundBlocを取得し、OrderRefundFetchDataEventを発行
2. **25-36行目**: buildメソッドでScaffoldとAppBarを構築
3. **38-54行目**: BlocConsumerでステートに応じたUIを切り替え
4. **56-122行目**: refundDetailsメソッドで返金情報をレンダリング

#### Step 3: Bloc層を理解する

状態管理と非同期処理の流れを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | order_refund_bloc.dart | `lib/screens/order_refund/bloc/order_refund_bloc.dart` | イベント処理とステート発行の流れ |
| 3-2 | order_refund_event.dart | `lib/screens/order_refund/bloc/order_refund_event.dart` | OrderRefundFetchDataEventの定義 |
| 3-3 | order_refund_state.dart | `lib/screens/order_refund/bloc/order_refund_state.dart` | OrderRefundListDataStateの成功・失敗状態 |

**主要処理フロー**:
- **24-34行目** (order_refund_bloc.dart): OrderRefundFetchDataEventを受けてリポジトリを呼び出し、結果に応じたステートを発行

#### Step 4: Repository層を理解する

API通信の実装を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | order_refund_repository.dart | `lib/screens/order_refund/bloc/order_refund_repository.dart` | getRefundListメソッドの実装 |

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

```
OrderRefundScreen (order_refund_details.dart)
    │
    ├─ initState()
    │      └─ OrderRefundBloc.add(OrderRefundFetchDataEvent)
    │
    ├─ BlocConsumer<OrderRefundBloc, OrderRefundBaseState>
    │      └─ buildContainer() → refundDetails()
    │
    └─ OrderRefundBloc (order_refund_bloc.dart)
           │
           └─ mapEventToState()
                  └─ OrderRefundRepositoryImp.getRefundList()
                         └─ API呼び出し → OrderRefundModel
```

### データフロー図

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

OrderDetail        ───▶ OrderRefundScreen.initState()    ───▶ 画面表示
 (orderId)                    │
                              ▼
                    OrderRefundFetchDataEvent
                              │
                              ▼
                    OrderRefundBloc.mapEventToState()
                              │
                              ▼
                    OrderRefundRepositoryImp.getRefundList()
                              │
                              ▼
                    GraphQL API呼び出し
                              │
                              ▼
                    OrderRefundModel                      ───▶ refundDetails()
                     └─ ViewRefunds[]                           │
                         └─ RefundItems[]                       ▼
                                                          返金情報の表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| order_refund_details.dart | `lib/screens/order_refund/order_refund_details.dart` | ソース | 画面本体のStatefulWidget |
| order_refund_bloc.dart | `lib/screens/order_refund/bloc/order_refund_bloc.dart` | ソース | 状態管理Bloc |
| order_refund_event.dart | `lib/screens/order_refund/bloc/order_refund_event.dart` | ソース | Blocイベント定義 |
| order_refund_state.dart | `lib/screens/order_refund/bloc/order_refund_state.dart` | ソース | Blocステート定義 |
| order_refund_repository.dart | `lib/screens/order_refund/bloc/order_refund_repository.dart` | ソース | API通信リポジトリ |
| order_refund_model.dart | `lib/data_model/order_model/order_refund_model.dart` | ソース | 返金データモデル |
| index.dart | `lib/screens/order_refund/utils/index.dart` | ソース | 共通インポートファイル |
