# 画面設計書 19-商品インポート画面

## 概要

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

### 本画面の処理概要

商品インポート画面は、CSVファイルから商品データを一括でインポートするための画面である。大量の商品データを効率的に登録・更新することができる。

**業務上の目的・背景**：新規ストアの立ち上げや、外部システムからの移行、大量の商品追加・更新時に、個別に商品を登録するのは非効率である。本画面は、CSVファイルを通じて商品データを一括でインポートし、運用効率を大幅に向上させるために必要である。

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

**主要な操作・処理内容**：
1. CSVファイルのアップロード
2. インポートプレビュー（サマリー表示）
3. インポートの確定・実行
4. テンプレートファイルのダウンロード

**画面遷移**：
- 遷移元：商品一覧画面（No.5）
- 遷移先：商品一覧画面（インポート完了/キャンセル後）

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | 商品CRUD | 主機能 | CSVからの商品一括インポート |
| 74 | ファイルアップロード | 補助機能 | CSVファイルのアップロード |

## 画面種別

登録（ドロワー形式）

## URL/ルーティング

```
/products/import
```

## 入出力項目

### 入力項目

| 項目名 | 項目ID | 型 | 必須 | バリデーション | 備考 |
|--------|--------|-----|------|---------------|------|
| CSVファイル | file | File | 必須 | CSV形式 | ドラッグ&ドロップ対応 |

### 出力項目

| 項目名 | 項目ID | 型 | 備考 |
|--------|--------|-----|------|
| トランザクションID | transaction_id | string | インポート確認用 |
| インポートサマリー | summary | object | 処理件数等 |

## 表示項目

### アップロードセクション

| 項目名 | 表示形式 | 備考 |
|--------|---------|------|
| タイトル | Heading h2 | "Upload" |
| 説明テキスト | Text | アップロード手順の説明 |
| アップロードエリア | UploadImport | ドラッグ&ドロップ対応 |
| ファイルプレビュー | FilePreview | アップロード後に表示 |

### サマリーセクション（アップロード後）

| 項目名 | 表示形式 | 備考 |
|--------|---------|------|
| インポートサマリー | ImportSummary | 処理対象件数等 |

### テンプレートセクション

| 項目名 | 表示形式 | 備考 |
|--------|---------|------|
| タイトル | Heading h2 | "Template" |
| 説明テキスト | Text | テンプレートの説明 |
| テンプレートファイル | FilePreview | ダウンロードリンク付き |

## イベント仕様

### 1-ファイルアップロード

**トリガー**：ファイル選択またはドラッグ&ドロップ

**処理フロー**：
1. UploadImportコンポーネントでファイル受付
2. `useImportProducts`ミューテーションで前処理（プリプロセス）
3. サーバーでCSV解析、サマリー生成
4. 成功時にトランザクションIDとサマリーを取得
5. 失敗時にエラートースト表示、ファイル状態をクリア

### 2-ファイル削除

**トリガー**：ファイルプレビューの削除ボタン押下

**処理フロー**：
1. filenameをundefinedに設定
2. アップロードエリアを再表示

### 3-インポート確定

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

**処理フロー**：
1. transaction_idの存在を確認
2. `useConfirmImportProducts`ミューテーションでインポート確定
3. 成功時にinfoトースト表示（バックグラウンドで処理中）
4. ドロワーを閉じる
5. 失敗時にエラートースト表示

### 4-テンプレートダウンロード

**トリガー**：テンプレートファイルのダウンロードリンククリック

**処理フロー**：
1. getProductImportCsvTemplateでテンプレート内容を生成
2. Blobとしてダウンロード提供

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| インポート確定 | product | INSERT/UPDATE | 商品の作成・更新 |
| インポート確定 | product_variant | INSERT/UPDATE | バリアントの作成・更新 |
| インポート確定 | product_option | INSERT/UPDATE | オプションの作成・更新 |

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

#### product

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT/UPDATE | title | CSVのtitle列 | 必須 |
| INSERT/UPDATE | description | CSVのdescription列 | |
| INSERT/UPDATE | handle | CSVのhandle列 | ユニーク |
| INSERT/UPDATE | (その他) | CSVの各列 | |

## メッセージ仕様

| 種別 | メッセージキー | 表示条件 |
|------|--------------|---------|
| 情報 | products.import.success.title | インポート確定成功時 |
| 情報 | products.import.success.description | インポート確定成功時（説明） |
| エラー | (API error message) | アップロード/確定失敗時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| CSVファイル形式エラー | エラートースト表示、ファイル状態クリア |
| データバリデーションエラー | サマリーでエラー件数表示 |
| API呼び出し失敗 | エラートースト表示 |

## 備考

- RouteDrawerコンポーネントを使用したドロワー形式
- インポートは2段階処理（プリプロセス → 確定）
- プリプロセス段階でCSVの検証とサマリー生成が行われる
- 確定後はバックグラウンドで処理されるため、即座にモーダルを閉じる
- テンプレートファイルは動的に生成（getProductImportCsvTemplate）

---

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

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

### 推奨読解順序

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

まず、インポート処理のデータ構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | products.tsx | `packages/admin/dashboard/src/hooks/api/products.tsx` | useImportProducts, useConfirmImportProductsの定義（428-454行目） |

**読解のコツ**: インポートは2つのAPIで構成される。createImportでプリプロセス（検証+サマリー生成）、confirmImportで実際のインポート実行。

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

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

**主要処理フロー**:
- **12-27行目**: ProductImport - ドロワーのラッパー
- **30-143行目**: ProductImportContent - メインのインポートロジック

#### Step 3: インポート処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | product-import.tsx | `packages/admin/dashboard/src/routes/products/product-import/product-import.tsx` | ProductImportContentの詳細 |

**主要処理フロー**:
- **32行目**: filenameの状態管理
- **34-35行目**: useImportProducts, useConfirmImportProductsミューテーション
- **38-40行目**: テンプレート生成（useMemo）
- **42-53行目**: handleUploaded - ファイルアップロード処理
- **55-71行目**: handleConfirm - インポート確定処理

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

```
ProductImport (product-import.tsx)
    │
    └─ ProductImportContent
           │
           ├─ useState (filename)
           │
           ├─ useImportProducts
           │      └─ sdk.admin.product.createImport
           │
           ├─ useConfirmImportProducts
           │      └─ sdk.admin.product.confirmImport
           │
           ├─ getProductImportCsvTemplate (helpers)
           │
           ├─ UploadImport (components)
           │      └─ ファイル選択/ドラッグ&ドロップUI
           │
           ├─ FilePreview (components)
           │      └─ アップロード済みファイル表示
           │
           └─ ImportSummary (components)
                  └─ インポートサマリー表示
```

### データフロー図

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

CSVファイル選択 ──────────▶ UploadImport ───────────────────▶ filename設定
        │
        └─ handleUploaded
               │
               └─ useImportProducts
                      └─ sdk.admin.product.createImport
                             │
                             ├─ transaction_id ──────────▶ 状態保存
                             └─ summary ─────────────────▶ ImportSummary表示

Importボタン ─────────────▶ handleConfirm ──────────────────▶ インポート実行
        │
        └─ useConfirmImportProducts
               └─ sdk.admin.product.confirmImport
                      │
                      └─ バックグラウンド処理開始
                             └─ 成功トースト → ドロワー閉じる
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| product-import.tsx | `packages/admin/dashboard/src/routes/products/product-import/product-import.tsx` | ソース | メインコンポーネント |
| upload-import.tsx | `packages/admin/dashboard/src/routes/products/product-import/components/upload-import.tsx` | ソース | アップロードUI |
| import-summary.tsx | `packages/admin/dashboard/src/routes/products/product-import/components/import-summary.tsx` | ソース | サマリー表示 |
| import-template.ts | `packages/admin/dashboard/src/routes/products/product-import/helpers/import-template.ts` | ソース | テンプレート生成 |
| index.ts | `packages/admin/dashboard/src/routes/products/product-import/index.ts` | ソース | エクスポート定義 |
| products.tsx | `packages/admin/dashboard/src/hooks/api/products.tsx` | ソース | インポート関連APIフック |
| file-preview.tsx | `packages/admin/dashboard/src/components/common/file-preview/file-preview.tsx` | ソース | ファイルプレビューコンポーネント |
