# 画面設計書 18-注文詳細画面

## 概要

本ドキュメントは、Bagisto eコマースモバイルアプリにおける注文詳細画面の設計仕様を定義するものです。注文詳細画面は、個別の注文情報を詳細に表示し、注文に対するアクション（キャンセル、再注文等）を提供する画面です。

### 本画面の処理概要

注文詳細画面は、特定の注文の詳細情報（商品明細、配送先、支払い情報、ステータス）を表示し、注文のキャンセルや再注文などの操作を行う画面です。

**業務上の目的・背景**：注文詳細画面は、ユーザーが自分の注文内容を詳細に確認するための画面です。注文した商品の確認、配送状況の把握、支払い情報の確認ができます。また、条件を満たす注文に対してはキャンセルや再注文のアクションを提供し、ユーザーの利便性を高めます。請求書、配送情報、返金情報への遷移も可能です。

**画面へのアクセス方法**：
- 注文履歴一覧画面から注文をタップ
- 注文完了画面から注文IDをタップ

**主要な操作・処理内容**：
1. 注文詳細情報の表示（注文ID、ステータス、日時、商品一覧）
2. 配送先住所・請求先住所の表示
3. 支払い方法・配送方法の表示
4. 価格詳細の表示（小計、配送料、税金、合計）
5. 注文キャンセル（条件を満たす場合）
6. 再注文（カートに追加）
7. 請求書詳細画面への遷移
8. 配送詳細画面への遷移
9. 返金詳細画面への遷移

**画面遷移**：
- 遷移元：注文履歴一覧画面、注文完了画面
- 遷移先：請求書詳細画面、配送詳細画面、返金詳細画面、カート画面

**権限による表示制御**：本画面はログインユーザー専用です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 42 | 注文詳細表示 | 主機能 | 個別注文の詳細情報表示（商品明細、配送先、支払い情報、ステータス） |
| 43 | 注文キャンセル | 補助機能 | 注文のキャンセル申請処理 |
| 44 | 再注文 | 補助機能 | 過去の注文を再度カートに追加する処理 |
| 45 | 請求書表示 | 遷移先機能 | 請求書詳細画面への遷移 |
| 46 | 配送詳細表示 | 遷移先機能 | 配送詳細画面への遷移 |
| 47 | 返金詳細表示 | 遷移先機能 | 返金詳細画面への遷移 |

## 画面種別

詳細

## URL/ルーティング

```dart
const String orderDetailPage = 'orderDetailPage';
```

ルート定義：`Navigator.pushNamed(context, orderDetailPage, arguments: orderId)`

## 入出力項目

| 項目名 | 入力/出力 | 型 | 必須 | 説明 |
|--------|----------|-----|------|------|
| orderId | 入力 | int? | ○ | 注文ID |

## 表示項目

| No | 項目名 | 型 | 表示条件 | 説明 |
|----|--------|-----|----------|------|
| 1 | AppBar | AppBar | 常時 | タイトル「注文詳細」 |
| 2 | 注文ID | Text | 常時 | 注文番号の表示 |
| 3 | 注文ステータス | Chip | 常時 | ステータス（色分け表示） |
| 4 | 注文日時 | Text | 常時 | 注文確定日時 |
| 5 | 商品一覧 | ListView | 常時 | 注文商品の一覧 |
| 6 | 商品画像/名前/数量/価格 | Widget | 常時 | 各商品の詳細 |
| 7 | 配送先住所 | Card | 常時 | 配送先の住所情報 |
| 8 | 請求先住所 | Card | 常時 | 請求先の住所情報 |
| 9 | 支払い方法 | Text | 常時 | 選択された支払い方法 |
| 10 | 配送方法 | Text | 常時 | 選択された配送方法 |
| 11 | 価格詳細 | Card | 常時 | 小計、配送料、税金、割引、合計 |
| 12 | キャンセルボタン | MaterialButton | キャンセル可能時 | 注文キャンセルボタン |
| 13 | 再注文ボタン | MaterialButton | 常時 | 再注文ボタン |
| 14 | 請求書ボタン | IconButton | 請求書あり | 請求書詳細への遷移 |
| 15 | 配送ボタン | IconButton | 配送情報あり | 配送詳細への遷移 |
| 16 | 返金ボタン | IconButton | 返金情報あり | 返金詳細への遷移 |
| 17 | ローディング | OrderDetailLoader | 読み込み中 | スケルトンローダー表示 |

## イベント仕様

### 1-注文詳細取得

**トリガー**：画面初期表示時

**処理フロー**：
1. `OrderDetailBloc`に`OrderDetailFetchDataEvent(orderId)`を発行
2. `OrderDetailRepository.getOrderDetails(orderId)`でAPIを呼び出し
3. 取得したデータを`OrderDetail`モデルに変換
4. `OrderDetailFetchDataState.success`を発行しUIを更新

### 2-注文キャンセル

**トリガー**：キャンセルボタン押下

**処理フロー**：
1. `OnClickOrderLoadingEvent`でローダー表示
2. `CancelOrderEvent(orderId)`を発行
3. `OrderDetailRepository.cancelOrder(orderId)`でAPIを呼び出し
4. 成功時：成功通知を表示、2秒後に前画面に戻る
5. 失敗時：エラー通知を表示

### 3-再注文

**トリガー**：再注文ボタン押下

**処理フロー**：
1. `ReOrderEvent(orderId)`を発行
2. `OrderDetailRepository.reOrderCustomerOrder(orderId)`でAPIを呼び出し
3. 成功時：成功通知を表示、2秒後にカート画面へ遷移
4. 失敗時：エラー通知を表示

### 4-請求書詳細遷移

**トリガー**：請求書ボタンタップ

**処理フロー**：
1. `Navigator.pushNamed(context, invoiceDetails, arguments: orderDetail)`を実行
2. 請求書詳細画面へ遷移

### 5-配送詳細遷移

**トリガー**：配送ボタンタップ

**処理フロー**：
1. `Navigator.pushNamed(context, shipmentDetails, arguments: orderDetail)`を実行
2. 配送詳細画面へ遷移

### 6-返金詳細遷移

**トリガー**：返金ボタンタップ

**処理フロー**：
1. `Navigator.pushNamed(context, refundDetails, arguments: orderDetail)`を実行
2. 返金詳細画面へ遷移

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 注文詳細取得 | orders, order_items, order_addresses | SELECT | 注文詳細情報を取得 |
| 注文キャンセル | orders | UPDATE | ステータスをキャンセルに更新 |
| 再注文 | cart_items | INSERT | 注文商品をカートに追加 |

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

#### orders

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | 全項目 | order_idで絞り込み | 詳細情報取得 |
| UPDATE | status | "canceled" | キャンセル時 |

## メッセージ仕様

| No | メッセージID | メッセージ内容 | 表示タイミング | 種別 |
|----|------------|---------------|--------------|------|
| 1 | orderDetails | 注文詳細 | AppBarタイトル | 情報 |
| 2 | - | （APIからの成功メッセージ） | キャンセル/再注文成功時 | 成功 |
| 3 | - | （APIからのエラーメッセージ） | キャンセル/再注文失敗時 | エラー |
| 4 | somethingWrong | 問題が発生しました | 予期せぬエラー時 | エラー |

## 例外処理

| No | 例外状況 | 対応処理 |
|----|---------|---------|
| 1 | 注文データ取得失敗 | `ErrorMessage.errorMsg`でエラー表示 |
| 2 | キャンセル失敗 | エラー通知表示 |
| 3 | 再注文失敗 | エラー通知表示 |
| 4 | 在庫切れで再注文不可 | APIからのエラーメッセージ表示 |

## 備考

- `OrderStatusBGColorHelper`mixinでステータスに応じた背景色を設定
- キャンセル成功後は2秒待機して自動的に前画面へ戻る
- 再注文成功後は2秒待機してカート画面へ遷移
- 請求書/配送/返金ボタンの表示はそれぞれのデータ有無で制御
- `OrderDetailTile`ウィジェットで詳細表示UI構築

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | order_detail_model.dart | `lib/screens/order_detail/data_model/order_detail_model.dart`（推定） | OrderDetailクラスの構造 |

**読解のコツ**: `OrderDetail`には注文情報、商品一覧、住所、支払い/配送情報が含まれます。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | order_detail.dart | `lib/screens/order_detail/view/order_detail.dart` | OrderDetailScreenクラス |

**主要処理フロー**:
1. **行37-41**: initStateでBloc取得、`OrderDetailFetchDataEvent`発行
2. **行44-55**: buildメソッドでScaffold構築
3. **行58-88**: BlocConsumerでイベント処理
4. **行91-124**: `buildContainer`で状態に応じたUI構築

#### Step 3: 状態管理（BLoC）を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | order_detail_bloc.dart | `lib/screens/order_detail/bloc/order_detail_bloc.dart` | 注文詳細取得、キャンセル、再注文処理 |
| 3-2 | order_detail_event.dart | `lib/screens/order_detail/bloc/order_detail_event.dart` | イベント定義 |
| 3-3 | order_detail_state.dart | `lib/screens/order_detail/bloc/order_detail_state.dart` | 状態定義 |

**主要処理フロー**:
- **行26-40**: OrderDetailFetchDataEvent処理
- **行41-54**: CancelOrderEvent処理
- **行58-70**: ReOrderEvent処理

#### Step 4: UIコンポーネントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | order_detail_tile.dart | `lib/screens/order_detail/widgets/order_detail_tile.dart` | 注文詳細表示Widget |
| 4-2 | shipping_payment_info.dart | `lib/screens/order_detail/widgets/shipping_payment_info.dart` | 配送/支払い情報Widget |

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

```
OrderDetailScreen (order_detail.dart)
    │
    ├─ OrderDetailBloc (order_detail_bloc.dart)
    │      │
    │      ├─ OrderDetailFetchDataEvent
    │      │      └─ OrderDetailRepository.getOrderDetails()
    │      │
    │      ├─ CancelOrderEvent
    │      │      └─ OrderDetailRepository.cancelOrder()
    │      │
    │      └─ ReOrderEvent
    │             └─ OrderDetailRepository.reOrderCustomerOrder()
    │
    └─ OrderDetailTile (order_detail_tile.dart)
           ├─ 商品一覧表示
           ├─ 住所表示
           ├─ 価格詳細表示
           └─ アクションボタン
                  ├─ キャンセル → CancelOrderEvent
                  ├─ 再注文 → ReOrderEvent
                  ├─ 請求書 → Navigator.pushNamed(invoiceDetails)
                  ├─ 配送 → Navigator.pushNamed(shipmentDetails)
                  └─ 返金 → Navigator.pushNamed(refundDetails)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| order_detail.dart | `lib/screens/order_detail/view/order_detail.dart` | ソース | メイン画面ウィジェット |
| order_detail_bloc.dart | `lib/screens/order_detail/bloc/order_detail_bloc.dart` | ソース | 状態管理BLoC |
| order_detail_event.dart | `lib/screens/order_detail/bloc/order_detail_event.dart` | ソース | イベント定義 |
| order_detail_state.dart | `lib/screens/order_detail/bloc/order_detail_state.dart` | ソース | 状態定義 |
| order_detail_repository.dart | `lib/screens/order_detail/bloc/order_detail_repository.dart` | ソース | API通信 |
| order_detail_tile.dart | `lib/screens/order_detail/widgets/order_detail_tile.dart` | ソース | 詳細表示Widget |
| shipping_payment_info.dart | `lib/screens/order_detail/widgets/shipping_payment_info.dart` | ソース | 配送/支払いWidget |
| order_detail_loader.dart | `lib/screens/order_detail/widgets/order_detail_loader.dart` | ソース | ローダーWidget |
| index.dart | `lib/screens/order_detail/utils/index.dart` | ソース | エクスポート集約 |
| route_constants.dart | `lib/utils/route_constants.dart` | 設定 | ルート定数定義 |
