# 機能設計書 47-返金詳細表示

## 概要

本ドキュメントは、ECモバイルアプリケーションにおける返金詳細表示機能の設計仕様を定義する。注文の返金情報（返金額、調整手数料、商品明細）を表示する機能である。

### 本機能の処理概要

この機能は、注文詳細画面から遷移し、該当注文の返金情報を詳細に表示する。返金ID、返金された商品の一覧、返金額、調整金額、配送先・支払い情報などを確認できる。

**業務上の目的・背景**：ECサイトにおいて、返金処理の詳細確認は顧客と事業者双方にとって重要である。返金額の内訳（商品代、配送料、調整金額）を明確に表示することで、取引の透明性を確保し、顧客の疑問や不安を解消する。

**機能の利用シーン**：ユーザーが注文詳細画面で「返金詳細」ボタンをタップした際に利用される。返金額の確認、返金された商品の確認、調整手数料の確認などに使用される。

**主要な処理内容**：
1. 注文IDに基づく返金データの取得
2. 返金IDと商品明細の表示
3. 価格詳細（小計、配送料、調整返金額、調整手数料、合計）の表示
4. 配送先・支払い情報の表示

**関連システム・外部連携**：バックエンドのBagisto GraphQL APIと連携し、返金データを取得する。

**権限による制御**：ログイン済みユーザーのみがアクセス可能。ユーザーは自身の注文の返金情報のみを閲覧できる。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 21 | 返金詳細画面 | 主画面 | 注文の返金情報表示（返金額、調整手数料） |
| 18 | 注文詳細画面 | 参照元画面 | 返金詳細ボタンから遷移 |

## 機能種別

データ取得 / 詳細表示

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| orderId | int | Yes | 注文の内部ID | 正の整数 |

### 入力データソース

- 画面遷移引数：OrderDetailモデル（orderIdを含む）
- ユーザーセッション：認証トークン（SharedPreferencesから取得）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| viewRefunds[].id | int | 返金ID |
| viewRefunds[].items[].sku | String | 商品SKU |
| viewRefunds[].items[].name | String | 商品名 |
| viewRefunds[].items[].qty | int | 返金数量 |
| viewRefunds[].items[].formattedPrice.price | String | 単価 |
| viewRefunds[].items[].formattedPrice.baseTotal | String | 小計 |
| viewRefunds[].items[].formattedPrice.taxAmount | String | 税額 |
| viewRefunds[].items[].formattedPrice.total | String | 合計 |
| viewRefunds[].formattedPrice.subTotal | String | 返金小計 |
| viewRefunds[].formattedPrice.shippingAmount | String | 配送料返金 |
| viewRefunds[].formattedPrice.adjustmentRefund | String | 調整返金額 |
| viewRefunds[].formattedPrice.adjustmentFee | String | 調整手数料 |
| viewRefunds[].formattedPrice.grandTotal | String | 返金総合計 |

### 出力先

- 画面表示：OrderRefundScreenウィジェットによる返金詳細表示

## 処理フロー

### 処理シーケンス

```
1. 画面初期化（initState）
   └─ OrderRefundBlocを取得し、OrderRefundFetchDataEventを発行
2. API呼び出し
   └─ OrderRefundRepositoryImpがApiClient経由でGraphQL APIを呼び出し
3. レスポンス処理
   └─ OrderRefundModelにデシリアライズ
4. 状態更新
   └─ OrderRefundListDataStateをemitしてUI更新
5. 返金詳細表示
   └─ 返金ID、商品明細、価格詳細、配送・支払い情報を表示
```

### フローチャート

```mermaid
flowchart TD
    A[注文詳細画面] --> B{qtyRefunded > 0?}
    B -->|Yes| C[返金詳細ボタン表示]
    B -->|No| D[返金詳細ボタン非表示]
    C --> E[返金詳細ボタン押下]
    E --> F[OrderRefundScreen遷移]
    F --> G[OrderRefundFetchDataEvent発行]
    G --> H[getRefundList API呼び出し]
    H --> I{レスポンス成功?}
    I -->|Yes| J[OrderRefundModel生成]
    I -->|No| K[エラー表示]
    J --> L{データあり?}
    L -->|Yes| M[返金詳細表示]
    L -->|No| N[EmptyDataView表示]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-47-01 | 表示条件 | 返金数量(qtyRefunded)が0より大きい場合のみ表示 | 常時 |
| BR-47-02 | 自己注文のみ | ユーザーは自身の注文の返金情報のみ閲覧可能 | 常時 |
| BR-47-03 | 複数返金対応 | 1注文に複数の返金がある場合はすべて表示 | 常時 |

### 計算ロジック

返金詳細表示判定（注文詳細画面）：
```dart
if (orderDetailModel?.items?[0].qtyRefunded != 0) {
  // 返金詳細ボタンを表示
}
```

## データベース操作仕様

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 返金取得 | refunds | SELECT | 注文IDに紐づく返金情報を取得 |
| 返金取得 | refund_items | SELECT | 返金に含まれる商品明細を取得 |

### テーブル別操作詳細

#### refunds（GraphQL API経由）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | id, items, formattedPrice等 | order_id = 指定されたorderId | 複数レコード可能 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | API通信エラー | ネットワーク接続不可 | エラー表示 |
| - | データなし | 返金情報がない | EmptyDataView表示 |

### リトライ仕様

- 自動リトライなし
- 画面再表示で再取得可能

## トランザクション仕様

本機能はデータ取得のみのため、トランザクション管理は不要。

## パフォーマンス要件

- データロード：2秒以内

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

- 認証トークンを使用したAPI呼び出し
- 注文IDによるアクセス制御（サーバーサイドで所有者確認）

## 備考

- ShippingAndPaymentInfoウィジェットを再利用して配送・支払い情報を表示
- OrderDetailモデルを引数として渡し、関連情報を共有
- 調整返金額（Adjustment Refund）と調整手数料（Adjustment Fee）は管理者が設定する金額

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | order_refund_model.dart | `lib/data_model/order_model/order_refund_model.dart` | OrderRefundModel、ViewRefundsの構造 |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | order_refund_details.dart | `lib/screens/order_refund/order_refund_details.dart` | StatefulWidgetの構造、initStateでのBloc初期化 |

**主要処理フロー**:
- **17-21行目**: initStateでOrderRefundBlocを取得し、OrderRefundFetchDataEventを発行
- **38-53行目**: BlocConsumerでstateの変化を監視しUI更新
- **56-121行目**: refundDetails()で返金情報を表示
- **140-196行目**: getRefunds()で返金商品一覧を表示

#### Step 3: BLoCパターンを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | order_refund_bloc.dart | `lib/screens/order_refund/bloc/order_refund_bloc.dart` | OrderRefundFetchDataEventのハンドリング |

**主要処理フロー**:
- **23-34行目**: OrderRefundFetchDataEvent処理、getRefundList呼び出し

#### Step 4: リポジトリ層を理解する

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

**主要処理フロー**:
- **21-30行目**: getRefundListでApiClient.getRefundList呼び出し

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

```
OrderRefundScreen (Widget)
    │
    ├─ OrderRefundBloc
    │      │
    │      └─ OrderRefundRepositoryImp
    │             │
    │             └─ ApiClient.getRefundList()
    │
    ├─ OrderRefundListDataState
    │      │
    │      └─ OrderRefundModel
    │
    └─ ShippingAndPaymentInfo (Widget)
```

### データフロー図

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

orderId ───▶ OrderRefundFetchDataEvent ───▶ OrderRefundBloc
   │                                              │
   │                                              ▼
   │                                    OrderRefundRepository
   │                                              │
   │                                              ▼
   │                                      ApiClient (GraphQL)
   │                                              │
   │                                              ▼
   │                                    OrderRefundModel
   │                                              │
   │                                              ▼
   └─────────────────────────────── OrderRefundListDataState ───▶ UI更新
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| order_refund_details.dart | `lib/screens/order_refund/order_refund_details.dart` | ソース | メイン画面ウィジェット |
| 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` | ソース | イベント定義 |
| order_refund_state.dart | `lib/screens/order_refund/bloc/order_refund_state.dart` | ソース | 状態定義 |
| order_refund_repository.dart | `lib/screens/order_refund/bloc/order_refund_repository.dart` | ソース | リポジトリ層 |
| order_refund_model.dart | `lib/data_model/order_model/order_refund_model.dart` | ソース | データモデル |
| shipping_payment_info.dart | `lib/screens/order_detail/widgets/shipping_payment_info.dart` | ソース | 配送・支払い情報UI |
