# 画面設計書 42-注文エクスポート画面

## 概要

本ドキュメントは、Medusa管理画面における注文エクスポート画面の設計を記載する。本画面は、注文一覧画面で適用されたフィルタ条件を引き継ぎ、該当する注文データをCSV形式でエクスポートする機能を提供するドロワー形式の画面である。

### 本画面の処理概要

**業務上の目的・背景**：ECサイト運営において、注文データを外部システムへ連携したり、レポート作成のためにエクスポートする必要がある。本画面は、注文一覧画面で設定したフィルタ条件をそのまま活用し、条件に合致した注文データを効率的にエクスポートできる機能を提供する。これにより、会計システムへのデータ連携、売上分析レポートの作成、在庫管理システムとの連携などの業務を支援する。

**画面へのアクセス方法**：注文一覧画面（/orders）のヘッダー部分にある「Export」ボタンをクリックすることでアクセス。このとき、注文一覧画面で適用されているフィルタ条件（URLパラメータ）がそのまま引き継がれる。

**主要な操作・処理内容**：
1. 現在適用されているフィルタ条件の確認：読み取り専用で表示
2. エクスポートの実行：「Export」ボタンクリックでエクスポート処理を開始
3. キャンセル：「Cancel」ボタンで注文一覧画面に戻る

**画面遷移**：
- 遷移元：注文一覧画面（/orders）
- 遷移先：注文一覧画面（エクスポート完了またはキャンセル後）

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| F-001 | 注文エクスポート | 主機能 | 注文データのCSVエクスポート |
| F-002 | フィルタ条件表示 | 補助機能 | 適用中のフィルタ条件を表示 |

## 画面種別

ドロワー（サイドパネル）

## URL/ルーティング

```
/orders/export
```

## 入出力項目

| 項目名 | 入出力 | 型 | 必須 | 説明 |
|--------|--------|-----|------|------|
| searchParams | 入力 | object | × | 注文一覧画面から引き継いだフィルタ条件 |
| status | 入力 | string[] | × | 注文ステータスフィルタ |
| payment_status | 入力 | string[] | × | 支払状況フィルタ |
| fulfillment_status | 入力 | string[] | × | フルフィルメント状況フィルタ |
| sales_channel_id | 入力 | string[] | × | 販売チャネルフィルタ |
| created_at | 入力 | object | × | 作成日時範囲フィルタ |

## 表示項目

| 項目名 | 表示名 | 型 | 説明 |
|--------|--------|-----|------|
| filters | Filters | component | 適用中のフィルタ条件を読み取り専用で表示 |

## イベント仕様

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

「Export」ボタンをクリックすると、エクスポート処理が非同期で開始される。

- API呼び出し: `POST /admin/orders/export`
- リクエストボディ: 現在のフィルタ条件（searchParams）
- 成功時: トースト通知で成功メッセージを表示し、ドロワーを閉じる
- エラー時: トースト通知でエラーメッセージを表示

### 2-キャンセルボタンクリック

「Cancel」ボタンをクリックすると、ドロワーを閉じて注文一覧画面に戻る。

- 処理: RouteDrawer.Close によるドロワーのクローズ

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| エクスポート実行 | order | SELECT | フィルタ条件に基づく注文データ取得 |
| エクスポート実行 | export_job | INSERT | エクスポートジョブの登録 |

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

#### order

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | 全フィールド | フィルタ条件に基づく取得 | エクスポート対象データ |

#### export_job

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | type | "order" | エクスポートタイプ |
| INSERT | status | "pending" | 初期ステータス |
| INSERT | filter_params | searchParams | フィルタ条件 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|--------------|----------|
| orders.export.success.title | 成功 | Export started | エクスポート開始成功時 |
| orders.export.success.description | 情報 | エクスポート完了後にメール通知される | エクスポート開始成功時 |
| エラーメッセージ | エラー | API返却のエラーメッセージ | API呼び出しエラー時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| API呼び出しエラー | トースト通知でエラーメッセージを表示 |
| 認証エラー | ログイン画面へリダイレクト |

## 備考

- エクスポート処理は非同期で実行され、完了後にユーザーへ通知される
- フィルタ条件は読み取り専用で表示され、この画面からの変更はできない
- フィルタ条件を変更する場合は、注文一覧画面に戻って変更する必要がある

---

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

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

### 推奨読解順序

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

まず、エクスポートに使用されるフィルタ条件の構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | use-order-table-query.ts | `packages/admin/dashboard/src/hooks/table/query/use-order-table-query.ts` | URLパラメータからsearchParamsへの変換ロジック |

**読解のコツ**: `useOrderTableQuery`フックがURLパラメータを解析し、API呼び出し用のパラメータオブジェクトを生成する。

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

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

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

**主要処理フロー**:
1. **行8-23**: `OrderExport`コンポーネントでRouteDrawerをレンダリング
2. **行14-15**: ヘッダーにタイトルと説明を設定
3. **行21**: `OrderExportContent`コンポーネントをレンダリング

#### Step 3: エクスポート処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | order-export.tsx | `packages/admin/dashboard/src/routes/orders/order-export/order-export.tsx` | OrderExportContentの実装（行26-66） |

**主要処理フロー**:
- **行28**: `useOrderTableQuery`でURLパラメータを取得
- **行30**: `useExportOrders`でエクスポートAPIフックを取得
- **行31**: `useRouteModal`でモーダル制御フックを取得
- **行33-45**: `handleExportRequest`関数でエクスポート処理を実行
- **行36-38**: 成功時にトースト通知とモーダルクローズ
- **行41-43**: エラー時にエラートーストを表示

#### Step 4: フィルタ表示を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | export-filters.tsx | `packages/admin/dashboard/src/routes/orders/order-export/components/export-filters.tsx` | フィルタ表示コンポーネント |

**主要処理フロー**:
- **行6-8**: `useOrderTableFilters`でフィルタ定義を取得
- **行18**: `DataTableFilter`コンポーネントに`readonly`プロパティを渡して読み取り専用表示

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

```
OrderExport (order-export.tsx)
    │
    ├─ RouteDrawer (モーダルコンテナ)
    │
    └─ OrderExportContent
           │
           ├─ useOrderTableQuery
           │      └─ URLパラメータ解析
           │
           ├─ useExportOrders
           │      └─ POST /admin/orders/export API
           │
           ├─ ExportFilters (export-filters.tsx)
           │      │
           │      ├─ useOrderTableFilters
           │      │      └─ フィルタ定義取得
           │      │
           │      └─ DataTableFilter (readonly)
           │
           └─ handleExportRequest
                  └─ mutateAsync → API呼び出し
```

### データフロー図

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

URLパラメータ ───▶ useOrderTableQuery ───▶ searchParams
                          │
                          ▼
searchParams ────▶ ExportFilters ────────▶ フィルタ条件表示
                          │
                          ▼
Exportボタン ────▶ handleExportRequest ──▶ API呼び出し
                          │
                          ▼
                   成功/エラー ───────────▶ トースト通知
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| order-export.tsx | `packages/admin/dashboard/src/routes/orders/order-export/order-export.tsx` | ソース | ページコンポーネント |
| export-filters.tsx | `packages/admin/dashboard/src/routes/orders/order-export/components/export-filters.tsx` | ソース | フィルタ表示コンポーネント |
| use-order-table-query.ts | `packages/admin/dashboard/src/hooks/table/query/use-order-table-query.ts` | ソース | URLパラメータ解析フック |
| 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呼び出しフック（useExportOrders） |
