# 画面設計書 17-注文履歴一覧画面

## 概要

本ドキュメントは、Bagisto eコマースモバイルアプリにおける注文履歴一覧画面の設計仕様を定義するものです。注文履歴一覧画面は、ユーザーの過去の注文を一覧表示し、注文管理を行うための画面です。

### 本画面の処理概要

注文履歴一覧画面は、ログインユーザーの過去の注文を一覧表示し、注文ステータス、日付、合計金額を確認できる画面です。フィルタリング機能も提供します。

**業務上の目的・背景**：eコマースにおいて、ユーザーが過去の注文履歴を確認できることは重要です。配送状況の確認、再注文、返品・交換の申請など、購入後のアクションを取るための起点となります。また、注文ID、日付、ステータス、金額でのフィルタリング機能により、大量の注文履歴から目的の注文を素早く見つけることができます。

**画面へのアクセス方法**：
- アカウント画面から「注文履歴」メニューをタップ
- ダッシュボード画面から「注文履歴」セクションをタップ
- ナビゲーションドロワーの「注文履歴」メニューをタップ

**主要な操作・処理内容**：
1. 注文履歴の一覧表示（注文ID、日付、ステータス、合計金額）
2. 注文をタップして注文詳細画面へ遷移
3. フィルタ機能（注文ID、合計金額、日付範囲、ステータス）
4. ページネーション（無限スクロール）
5. Pull-to-Refreshで最新データ取得
6. フィルタ条件のクリア

**画面遷移**：
- 遷移元：アカウント画面、ダッシュボード画面、ナビゲーションドロワー
- 遷移先：注文詳細画面

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 41 | 注文一覧表示 | 主機能 | ユーザーの過去注文一覧表示（ステータス、日付、合計金額） |
| 42 | 注文詳細表示 | 遷移先機能 | 注文タップ時に詳細画面へ遷移 |

## 画面種別

一覧

## URL/ルーティング

```dart
const String orderListScreen = 'orderListScreen';
```

ルート定義：`Navigator.pushNamed(context, orderListScreen)`

## 入出力項目

| 項目名 | 入力/出力 | 型 | 必須 | 説明 |
|--------|----------|-----|------|------|
| isFromDashboard | 入力 | bool? | × | ダッシュボードからの遷移フラグ（表示件数制限用） |

## 表示項目

| No | 項目名 | 型 | 表示条件 | 説明 |
|----|--------|-----|----------|------|
| 1 | AppBar | AppBar | 通常表示 | タイトル「注文履歴」、フィルタアイコン |
| 2 | フィルタアイコン | IconButton | 通常表示 | フィルタ用BottomSheet表示 |
| 3 | 注文リスト | ListView | 注文あり | 注文一覧（OrdersListTile） |
| 4 | 注文ID | Text | 注文あり | 注文番号の表示 |
| 5 | 注文日 | Text | 注文あり | 注文日時の表示 |
| 6 | ステータス | Chip | 注文あり | 注文ステータス（色分け表示） |
| 7 | 合計金額 | Text | 注文あり | フォーマット済み金額 |
| 8 | フィルタBottomSheet | Card | フィルタ表示時 | フィルタ条件入力UI |
| 9 | 空状態表示 | EmptyDataView | 注文0件 | 注文がない場合の表示 |
| 10 | ローディング | OrderLoader | 読み込み中 | スケルトンローダー表示 |

## イベント仕様

### 1-注文一覧取得

**トリガー**：画面初期表示時、Pull-to-Refresh時、フィルタ適用時

**処理フロー**：
1. `OrderListBloc`に`FetchOrderListEvent`を発行
2. パラメータ：id, status, startDate, endDate, total, page
3. `OrderListRepository.getOrderList()`でAPIを呼び出し
4. 取得したデータを`OrdersListModel`モデルに変換
5. `FetchOrderListState.success`を発行しUIを更新

### 2-ページネーション

**トリガー**：スクロール最下部到達時

**処理フロー**：
1. `_scrollController`で位置を監視
2. `maxScrollExtent`に到達し、次ページがある場合
3. `page++`してFetchOrderListEventを発行
4. 既存データに追加データをマージ

### 3-フィルタ適用

**トリガー**：フィルタBottomSheetで「送信」ボタン押下

**処理フロー**：
1. 入力された条件を取得（orderId, total, startDate, endDate, status）
2. pageを1にリセット
3. `FetchOrderListEvent`を発行（isFilterApply: true）
4. 条件に合致する注文のみ表示

### 4-フィルタクリア

**トリガー**：フィルタBottomSheetで「クリア」ボタン押下

**処理フロー**：
1. すべてのフィルタ条件をクリア
2. pageを1にリセット
3. `FetchOrderListEvent`を発行（条件なし）
4. BottomSheetを閉じる

### 5-注文詳細遷移

**トリガー**：注文リストアイテムをタップ

**処理フロー**：
1. 選択した注文のIDを取得
2. `Navigator.pushNamed(context, orderDetailPage, arguments: orderId)`を実行
3. 注文詳細画面へ遷移

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 注文一覧取得 | orders | SELECT | ユーザーの注文履歴を取得 |

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

#### orders

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | id, increment_id, status, grand_total, created_at | customer_idで絞り込み、フィルタ条件適用 | ページネーション対応 |

## メッセージ仕様

| No | メッセージID | メッセージ内容 | 表示タイミング | 種別 |
|----|------------|---------------|--------------|------|
| 1 | orders | 注文履歴 | AppBarタイトル | 情報 |
| 2 | filterBy | フィルター | フィルタBottomSheetタイトル | 情報 |
| 3 | clear | クリア | クリアボタン | 情報 |
| 4 | searchOrder | 注文検索 | フィルタセクション | 情報 |
| 5 | enterOrderId | 注文IDを入力 | フィルタ入力欄 | 情報 |
| 6 | enterTotal | 合計金額を入力 | フィルタ入力欄 | 情報 |
| 7 | orderDate | 注文日 | フィルタセクション | 情報 |
| 8 | fromDate | 開始日 | フィルタ入力欄 | 情報 |
| 9 | toDate | 終了日 | フィルタ入力欄 | 情報 |
| 10 | orderStatus | 注文ステータス | フィルタセクション | 情報 |
| 11 | all/pending/closed/canceled/processing/completed/pendingPayment/fraud | 各ステータス | ステータスドロップダウン | 情報 |
| 12 | cancel | キャンセル | キャンセルボタン | 情報 |
| 13 | submit | 送信 | 送信ボタン | 情報 |

## 例外処理

| No | 例外状況 | 対応処理 |
|----|---------|---------|
| 1 | 注文履歴が空 | `EmptyDataView`を表示 |
| 2 | API通信エラー | `EmptyDataView`を表示 |
| 3 | フィルタ結果が0件 | 空の一覧表示 |

## 備考

- ダッシュボードから遷移した場合（isFromDashboard: true）は最大5件表示
- ステータスは8種類：All, Pending, Closed, Canceled, Processing, Completed, Pending Payment, Fraud
- 日付フィルタは「YYYY-MM-DD 00:00:01」「YYYY-MM-DD 23:59:59」形式でAPI送信
- `OrderStatusBGColorHelper`mixinでステータスに応じた背景色を設定
- Pull-to-Refreshでページをリセットして再取得
- ページネーションは`paginatorInfo`のcurrentPage、lastPageで制御

---

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

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

### 推奨読解順序

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

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

**読解のコツ**: `OrdersListModel`には`data`（注文リスト）と`paginatorInfo`（ページネーション情報）が含まれます。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | order_list.dart | `lib/screens/orders/screen/order_list.dart` | OrdersListクラス |

**主要処理フロー**:
1. **行37-53**: initStateでBloc取得、イベント発行、ステータスリスト初期化
2. **行57-77**: buildメソッドでScaffold構築（AppBar、フィルタアイコン）
3. **行81-110**: BlocConsumerで状態に応じたUI構築
4. **行112-126**: `paginationFunction`でスクロール監視
5. **行128-171**: `_getOrdersList`で注文リスト表示
6. **行176-445**: `_getOrderFilter`でフィルタBottomSheet

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | order_list_bloc.dart | `lib/screens/orders/bloc/order_list_bloc.dart` | 注文一覧取得処理 |
| 3-2 | order_list_event.dart | `lib/screens/orders/bloc/order_list_event.dart` | イベント定義 |
| 3-3 | order_list_state.dart | `lib/screens/orders/bloc/order_list_state.dart` | 状態定義 |

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

```
OrdersList (order_list.dart)
    │
    ├─ OrderListBloc (order_list_bloc.dart)
    │      │
    │      └─ FetchOrderListEvent
    │             └─ OrderListRepository.getOrderList()
    │
    ├─ ListView.separated
    │      └─ OrdersListTile (order_list_tile.dart)
    │             └─ タップ → Navigator.pushNamed(orderDetailPage)
    │
    └─ _getOrderFilter (BottomSheet)
           ├─ 注文ID入力
           ├─ 合計金額入力
           ├─ 日付範囲選択
           └─ ステータス選択
```

### データフロー図

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

初期表示/Pull-to-Refresh ─────▶ OrderListBloc ─────▶ UI更新
フィルタ条件入力 ─────────────▶       │
スクロール（ページネーション） ───▶    │
                                     │
                                     └─ OrderListRepository
                                              │
                                              └─ GraphQL API
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| order_list.dart | `lib/screens/orders/screen/order_list.dart` | ソース | メイン画面ウィジェット |
| order_list_bloc.dart | `lib/screens/orders/bloc/order_list_bloc.dart` | ソース | 状態管理BLoC |
| order_list_event.dart | `lib/screens/orders/bloc/order_list_event.dart` | ソース | イベント定義 |
| order_list_state.dart | `lib/screens/orders/bloc/order_list_state.dart` | ソース | 状態定義 |
| order_list_repo.dart | `lib/screens/orders/bloc/order_list_repo.dart` | ソース | API通信 |
| order_list_tile.dart | `lib/screens/orders/widget/order_list_tile.dart` | ソース | 注文リストアイテム |
| order_loader_view.dart | `lib/screens/orders/widget/order_loader_view.dart` | ソース | ローダービュー |
| index.dart | `lib/screens/orders/utils/index.dart` | ソース | エクスポート集約 |
| route_constants.dart | `lib/utils/route_constants.dart` | 設定 | ルート定数定義 |
