# 画面設計書 41-注文一覧画面

## 概要

本ドキュメントは、Medusa管理画面における注文一覧画面の設計を記載する。本画面は、ECサイトで受け付けた全注文を一覧表示し、注文の検索・フィルタリング・エクスポートなどの操作を提供する中核的な管理画面である。

### 本画面の処理概要

**業務上の目的・背景**：ECサイト運営において、日々発生する注文を効率的に管理・確認することは最も重要な業務の一つである。本画面は、注文の全体像を把握し、特定の注文を素早く検索・抽出できる機能を提供することで、オペレーターの業務効率を向上させる。また、注文状況（支払状況・フルフィルメント状況）を一目で確認できることで、対応が必要な注文を迅速に特定できる。

**画面へのアクセス方法**：左側のナビゲーションメニューから「Orders」を選択することでアクセス可能。管理画面のダッシュボードからも注文セクションへのリンクを通じてアクセスできる。

**主要な操作・処理内容**：
1. 注文一覧の表示：ページネーション付きで全注文を表示（デフォルト20件/ページ）
2. 注文の検索：表示ID、顧客情報などで注文を検索
3. フィルタリング：支払状況、フルフィルメント状況、販売チャネル、日付範囲などでフィルタリング
4. ソート：表示ID、作成日時、更新日時でソート
5. 注文詳細への遷移：行クリックで個別注文の詳細画面へ遷移
6. 注文エクスポート：現在のフィルタ条件で注文データをエクスポート

**画面遷移**：
- 遷移元：ダッシュボード、ナビゲーションメニュー
- 遷移先：注文詳細画面（`/orders/{id}`）、注文エクスポート画面（`/orders/export`）

**権限による表示制御**：管理者権限を持つユーザーのみがアクセス可能。注文データの閲覧権限は認証済みユーザーに限定される。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| F-001 | 注文一覧取得 | 主機能 | 注文データの取得・表示 |
| F-002 | 注文検索 | 主機能 | キーワードによる注文検索 |
| F-003 | 注文フィルタリング | 主機能 | 各種条件による絞り込み |
| F-004 | 注文エクスポート | 遷移先機能 | CSVエクスポート画面への遷移 |
| F-005 | 注文詳細表示 | 遷移先機能 | 個別注文詳細画面への遷移 |

## 画面種別

一覧

## URL/ルーティング

```
/orders
```

## 入出力項目

| 項目名 | 入出力 | 型 | 必須 | 説明 |
|--------|--------|-----|------|------|
| q | 入力 | string | × | 検索クエリ |
| offset | 入力 | number | × | ページネーションオフセット |
| limit | 入力 | number | × | 取得件数（デフォルト20） |
| order | 入力 | string | × | ソート条件 |
| status | 入力 | string[] | × | 注文ステータスフィルタ |
| payment_status | 入力 | string[] | × | 支払状況フィルタ |
| fulfillment_status | 入力 | string[] | × | フルフィルメント状況フィルタ |
| sales_channel_id | 入力 | string[] | × | 販売チャネルフィルタ |
| created_at | 入力 | object | × | 作成日時範囲フィルタ |

## 表示項目

| 項目名 | 表示名 | 型 | 説明 |
|--------|--------|-----|------|
| display_id | # | number | 注文表示ID |
| created_at | Date | datetime | 作成日時 |
| customer | Customer | object | 顧客情報（名前、メール） |
| sales_channel | Sales Channel | object | 販売チャネル |
| payment_status | Payment | string | 支払状況（pending/captured/refunded等） |
| fulfillment_status | Fulfillment | string | フルフィルメント状況（not_fulfilled/fulfilled等） |
| total | Total | number | 注文合計金額（通貨コード付き） |
| shipping_address.country_code | Country | string | 配送先国（国旗アイコン付き） |

## イベント仕様

### 1-テーブル行クリック

ユーザーがテーブルの行をクリックすると、該当注文の詳細画面へ遷移する。

- 遷移先: `/orders/{order.id}`
- 処理: `navigateTo`関数によるクライアントサイドルーティング

### 2-エクスポートボタンクリック

「Export」ボタンをクリックすると、現在のフィルタ条件を保持したまま注文エクスポート画面へ遷移する。

- 遷移先: `/orders/export${location.search}`
- 処理: 現在のURLパラメータを引き継いでエクスポート画面へ遷移

### 3-フィルタ適用

フィルタ条件を変更すると、URLパラメータが更新され、該当条件での注文一覧が再取得される。

- 処理: `useOrderTableQuery`フックによるURLパラメータ同期
- API呼び出し: `GET /admin/orders`（フィルタパラメータ付き）

### 4-ソート変更

ソートカラムを変更すると、該当カラムでの昇順/降順ソートが適用される。

- 対象カラム: display_id, created_at, updated_at
- 処理: URLパラメータの`order`フィールド更新

### 5-ページネーション操作

ページを変更すると、該当ページの注文一覧が取得される。

- 処理: `offset`パラメータの更新
- 1ページあたり20件表示

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 注文一覧表示 | order | SELECT | 注文データの取得 |
| 注文一覧表示 | customer | SELECT | 顧客情報の取得 |
| 注文一覧表示 | sales_channel | SELECT | 販売チャネル情報の取得 |
| 注文一覧表示 | payment_collection | SELECT | 支払コレクション情報の取得 |

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

#### order

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | id, status, created_at, email, display_id, custom_display_id, payment_status, fulfillment_status, total, currency_code | フィルタ条件に基づく取得 | ページネーション適用 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|--------------|----------|
| MSG-001 | 情報 | 注文データがありません | 検索結果が0件の場合 |
| MSG-002 | エラー | データの取得に失敗しました | API呼び出しエラー時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| API呼び出しエラー | エラーをthrowしてエラーバウンダリで処理 |
| 認証エラー | ログイン画面へリダイレクト |
| データ取得中 | ローディングスケルトンを表示 |

## 備考

- 注文一覧はReact Queryの`keepPreviousData`オプションを使用し、ページ切り替え時のちらつきを防止している
- Feature Flag `view_configurations` が有効な場合、`ConfigurableOrderListTable`コンポーネントが使用される
- ウィジェット拡張ポイント（`order.list.before`, `order.list.after`）が用意されている

---

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

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

### 推奨読解順序

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

まず、注文データの型定義と取得するフィールドを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | const.ts | `packages/admin/dashboard/src/routes/orders/order-list/const.ts` | DEFAULT_FIELDSで取得するフィールド一覧を確認 |
| 1-2 | use-order-table-columns.tsx | `packages/admin/dashboard/src/hooks/table/columns/use-order-table-columns.tsx` | テーブルに表示するカラム定義を確認 |

**読解のコツ**: `DEFAULT_PROPERTIES`と`DEFAULT_RELATIONS`の組み合わせで、APIリクエスト時のfieldsパラメータが構成される。

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

処理の起点となるコンポーネントを特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | order-list.tsx | `packages/admin/dashboard/src/routes/orders/order-list/order-list.tsx` | ページコンポーネントの構成を確認 |

**主要処理フロー**:
1. **行7**: `useExtension`でウィジェット取得関数を取得
2. **行10-18**: `SingleColumnPage`レイアウトでテーブルコンポーネントをラップ

#### Step 3: テーブルコンポーネントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | order-list-table.tsx | `packages/admin/dashboard/src/routes/orders/order-list/components/order-list-table/order-list-table.tsx` | テーブルの実装詳細を確認 |

**主要処理フロー**:
- **行22-27**: Feature Flagチェックで使用するテーブルコンポーネントを分岐
- **行29-31**: `useOrderTableQuery`でURLパラメータを取得
- **行33-41**: `useOrders`フックで注文データを取得
- **行43-44**: フィルタとカラム定義を取得
- **行46-52**: `useDataTable`でテーブル状態を管理
- **行66-85**: `_DataTable`コンポーネントでテーブルをレンダリング

#### Step 4: APIフックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | orders.tsx | `packages/admin/dashboard/src/hooks/api/orders.tsx` | 注文API呼び出しフックの実装 |

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

```
OrderList (order-list.tsx)
    │
    ├─ SingleColumnPage (レイアウト)
    │
    └─ OrderListTable (order-list-table.tsx)
           │
           ├─ useOrderTableQuery
           │      └─ URLパラメータ解析
           │
           ├─ useOrders (orders.tsx)
           │      └─ GET /admin/orders API呼び出し
           │
           ├─ useOrderTableFilters
           │      └─ フィルタ定義取得
           │
           ├─ useOrderTableColumns
           │      └─ カラム定義取得
           │
           └─ _DataTable
                  └─ テーブルレンダリング
```

### データフロー図

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

URLパラメータ ───▶ useOrderTableQuery ───▶ searchParams
                          │
                          ▼
searchParams ────▶ useOrders ───────────▶ orders配列
                          │
                          ▼
orders配列 ──────▶ useDataTable ────────▶ tableインスタンス
                          │
                          ▼
tableインスタンス ▶ _DataTable ──────────▶ 画面表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| order-list.tsx | `packages/admin/dashboard/src/routes/orders/order-list/order-list.tsx` | ソース | ページコンポーネント |
| order-list-table.tsx | `packages/admin/dashboard/src/routes/orders/order-list/components/order-list-table/order-list-table.tsx` | ソース | テーブルコンポーネント |
| const.ts | `packages/admin/dashboard/src/routes/orders/order-list/const.ts` | ソース | 定数定義 |
| use-order-table-columns.tsx | `packages/admin/dashboard/src/hooks/table/columns/use-order-table-columns.tsx` | ソース | カラム定義フック |
| use-order-table-filters.tsx | `packages/admin/dashboard/src/hooks/table/filters/use-order-table-filters.tsx` | ソース | フィルタ定義フック |
| orders.tsx | `packages/admin/dashboard/src/hooks/api/orders.tsx` | ソース | API呼び出しフック |
| data-table.tsx | `packages/admin/dashboard/src/components/table/data-table/data-table.tsx` | ソース | 汎用テーブルコンポーネント |
