# 画面設計書 20-商品エクスポート画面

## 概要

本ドキュメントは、Medusa Admin Dashboard における商品エクスポート画面の設計仕様を定義するものである。

### 本画面の処理概要

商品エクスポート画面は、商品データをCSVファイルとしてエクスポートするための画面である。フィルタ条件を指定してエクスポート対象を絞り込むことができる。

**業務上の目的・背景**：商品データのバックアップ、外部システムへの連携、データ分析のために商品情報をエクスポートする必要がある。本画面は、必要な条件でフィルタリングした商品データをCSV形式でダウンロードする機能を提供する。

**画面へのアクセス方法**：商品一覧画面のアクションメニューから「Export」ボタンをクリックすることでドロワー形式で表示される。URLパスは `/products/export` となる。

**主要な操作・処理内容**：
1. フィルタ条件の確認・設定
2. エクスポートの実行
3. バックグラウンドでのファイル生成

**画面遷移**：
- 遷移元：商品一覧画面（No.5）
- 遷移先：商品一覧画面（エクスポート実行/キャンセル後）

**権限による表示制御**：本画面へのアクセスには商品管理権限が必要。権限がない場合は画面にアクセスできない。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | 商品CRUD | 主機能 | 商品データのエクスポート |

## 画面種別

参照（ドロワー形式）

## URL/ルーティング

```
/products/export
```

## 入出力項目

### 入力項目

| 項目名 | 項目ID | 型 | 必須 | バリデーション | 備考 |
|--------|--------|-----|------|---------------|------|
| 商品タイプ | type_id | string[] | - | - | 複数選択可 |
| 商品タグ | tag_id | string[] | - | - | 複数選択可 |
| 販売チャネル | sales_channel_id | string[] | - | - | 複数選択可 |
| ステータス | status | string[] | - | - | draft/proposed/published/rejected |
| 作成日 | created_at | DateRange | - | - | 日付範囲 |
| 更新日 | updated_at | DateRange | - | - | 日付範囲 |

### 出力項目

| 項目名 | 項目ID | 型 | 備考 |
|--------|--------|-----|------|
| トランザクションID | transaction_id | string | エクスポート処理の追跡用 |

## 表示項目

### フィルタセクション

| 項目名 | 表示形式 | 備考 |
|--------|---------|------|
| タイトル | Heading h2 | "Filters" |
| 説明テキスト | Text | フィルタの説明 |
| フィルタコンポーネント | DataTableFilter | readonly表示 |

### 利用可能なフィルタ

| フィルタ名 | キー | タイプ | 備考 |
|-----------|------|--------|------|
| 商品タイプ | type_id | select (multiple) | 検索可能 |
| 商品タグ | tag_id | select (multiple) | 検索可能 |
| 販売チャネル | sales_channel_id | select (multiple) | 検索可能 |
| ステータス | status | select (multiple) | draft/proposed/published/rejected |
| 作成日 | created_at | date | 日付範囲 |
| 更新日 | updated_at | date | 日付範囲 |

### フッター

| 項目名 | 表示形式 | 備考 |
|--------|---------|------|
| キャンセルボタン | Button secondary | ドロワーを閉じる |
| エクスポートボタン | Button primary | エクスポート実行 |

## イベント仕様

### 1-エクスポート実行

**トリガー**：「Export」ボタン押下

**処理フロー**：
1. 現在のフィルタパラメータ（searchParams）を取得
2. `useExportProducts`ミューテーションでエクスポート処理をリクエスト
3. 成功時にinfoトースト表示（バックグラウンドで処理中）
4. ドロワーを閉じる
5. 失敗時にエラートースト表示

### 2-キャンセル

**トリガー**：「Cancel」ボタン押下またはドロワー外クリック

**処理フロー**：
1. ドロワーを閉じる
2. エクスポート処理は実行されない

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| エクスポート実行 | (なし - 読み取り専用) | SELECT | 商品データの読み取り |

本画面は参照系画面であり、データベースの更新は発生しない。エクスポート処理はバックグラウンドジョブとして実行され、完了後に通知される。

## メッセージ仕様

| 種別 | メッセージキー | 表示条件 |
|------|--------------|---------|
| 情報 | products.export.success.title | エクスポートリクエスト成功時 |
| 情報 | products.export.success.description | エクスポートリクエスト成功時（説明） |
| エラー | (API error message) | エクスポートリクエスト失敗時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| API呼び出し失敗 | エラートースト表示 |
| 認証エラー | ログインページへリダイレクト |

## 備考

- RouteDrawerコンポーネントを使用したドロワー形式
- エクスポートはバックグラウンドで非同期実行される
- 商品一覧画面で適用されているフィルタがそのまま引き継がれる
- DataTableFilterコンポーネントはreadonly属性で表示（編集不可）
- useProductTableQueryでURLパラメータからフィルタ条件を取得
- useProductTableFiltersで利用可能なフィルタ定義を動的に生成

---

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

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

### 推奨読解順序

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

まず、エクスポート処理のデータ構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | use-product-table-query.tsx | `packages/admin/dashboard/src/hooks/table/query/use-product-table-query.tsx` | searchParamsの構造（17-66行目） |
| 1-2 | products.tsx | `packages/admin/dashboard/src/hooks/api/products.tsx` | useExportProductsの定義（411-426行目） |

**読解のコツ**: searchParamsには商品一覧のフィルタ条件が含まれており、そのままエクスポートAPIに渡される。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | product-export.tsx | `packages/admin/dashboard/src/routes/products/product-export/product-export.tsx` | ルートコンポーネントとProductExportContentコンポーネント |

**主要処理フロー**:
- **8-24行目**: ProductExport - ドロワーのラッパー
- **26-67行目**: ProductExportContent - メインのエクスポートロジック

#### Step 3: フィルタ処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | export-filters.tsx | `packages/admin/dashboard/src/routes/products/product-export/components/export-filters.tsx` | フィルタ表示コンポーネント |
| 3-2 | use-product-table-filters.tsx | `packages/admin/dashboard/src/hooks/table/filters/use-product-table-filters.tsx` | フィルタ定義の詳細 |

**主要処理フロー**:
- **6-22行目**: ExportFilters - DataTableFilterをreadonly表示
- **use-product-table-filters.tsx 79-212行目**: Filter配列の動的生成

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

```
ProductExport (product-export.tsx)
    │
    └─ ProductExportContent
           │
           ├─ useProductTableQuery
           │      └─ useQueryParams
           │             └─ URLからフィルタパラメータを取得
           │
           ├─ useExportProducts
           │      └─ sdk.admin.product.export
           │
           ├─ useRouteModal
           │      └─ handleSuccess
           │
           └─ ExportFilters (export-filters.tsx)
                  │
                  ├─ useProductTableFilters
                  │      ├─ useProductTypes
                  │      ├─ useProductTags
                  │      └─ useSalesChannels
                  │
                  └─ DataTableFilter (readonly)
```

### データフロー図

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

商品一覧のフィルタ ──────────▶ useProductTableQuery ──────────▶ searchParams
    │
    └─ URLパラメータ
           ├─ type_id
           ├─ tag_id
           ├─ sales_channel_id
           ├─ status
           ├─ created_at
           └─ updated_at

ExportFilters ────────────────▶ DataTableFilter ──────────────▶ フィルタ条件表示
    │                              (readonly)
    └─ useProductTableFilters
           └─ Filter[]配列

Exportボタン ─────────────────▶ handleExportRequest ──────────▶ エクスポート実行
        │
        └─ useExportProducts
               └─ sdk.admin.product.export(searchParams)
                      │
                      ├─ 成功 ──────▶ infoトースト → ドロワー閉じる
                      └─ 失敗 ──────▶ errorトースト
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| product-export.tsx | `packages/admin/dashboard/src/routes/products/product-export/product-export.tsx` | ソース | メインコンポーネント |
| export-filters.tsx | `packages/admin/dashboard/src/routes/products/product-export/components/export-filters.tsx` | ソース | フィルタ表示 |
| index.ts | `packages/admin/dashboard/src/routes/products/product-export/index.ts` | ソース | エクスポート定義 |
| products.tsx | `packages/admin/dashboard/src/hooks/api/products.tsx` | ソース | エクスポート関連APIフック |
| use-product-table-query.tsx | `packages/admin/dashboard/src/hooks/table/query/use-product-table-query.tsx` | ソース | クエリパラメータ処理 |
| use-product-table-filters.tsx | `packages/admin/dashboard/src/hooks/table/filters/use-product-table-filters.tsx` | ソース | フィルタ定義 |
| data-table-filter.tsx | `packages/admin/dashboard/src/components/table/data-table/data-table-filter/data-table-filter.tsx` | ソース | フィルタUIコンポーネント |
