# 画面設計書 67-インポート/エクスポート

## 概要

本ドキュメントは、Shopware 6 管理画面（Administration）におけるインポート/エクスポート画面の設計を記述したものです。商品、顧客、注文などのデータを一括でインポート・エクスポートするための管理画面です。

### 本画面の処理概要

インポート/エクスポート画面は、Shopwareのデータを CSV ファイル形式で一括インポート・エクスポートするための画面です。データ移行、バックアップ、外部システム連携などに使用されます。

**業務上の目的・背景**：ECサイト運営において、商品情報の一括登録・更新、顧客データの移行、在庫情報の同期など、大量のデータを効率的に処理する必要があります。本画面では、定義済みまたはカスタムのプロファイルを使用して、様々なエンティティのデータをインポート・エクスポートできます。

**画面へのアクセス方法**：管理画面にログイン後、左メニューの「設定」 > 「自動化」セクション > 「インポート/エクスポート」をクリックしてアクセスします。URL パスは `#/sw/import-export/index` です。

**主要な操作・処理内容**：
1. **インポート**：CSV ファイルをアップロードしてデータを一括登録・更新
2. **エクスポート**：選択したプロファイルに基づいてデータを CSV 形式で出力
3. **プロファイル管理**：インポート/エクスポート用のマッピング定義を作成・編集
4. **アクティビティ確認**：過去のインポート/エクスポート履歴と結果の確認
5. **進捗表示**：処理中の進捗状況をリアルタイムで表示

**画面遷移**：
- 遷移元：設定一覧画面（sw-settings-index）
- 遷移先：なし（処理完了後は同画面に留まる）
- 内部タブ：インポート、エクスポート、プロファイル

**権限による表示制御**：
- `system.import_export`：インポート/エクスポート機能へのアクセスが可能

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 51 | データ同期（同期処理実行） | 主機能 | インポート・エクスポート・プロファイル管理 |

## 画面種別

操作

## URL/ルーティング

| 項目 | 値 |
|------|---|
| モジュール名 | sw-import-export |
| メインルート | sw.import.export.index |
| インポートタブルート | sw.import.export.index.import |
| エクスポートタブルート | sw.import.export.index.export |
| プロファイルタブルート | sw.import.export.index.profiles |
| URLパス | #/sw/import-export/index |

## 入出力項目

### インポート設定

| 項目名 | 項目ID | 型 | 必須 | 説明 |
|--------|--------|-----|------|------|
| プロファイル | profileId | UUID | Yes | 使用するインポートプロファイル |
| ファイル | file | File | Yes | インポートする CSV ファイル |
| ドライラン | dryRun | Boolean | No | テスト実行（実際にデータ変更しない） |

### エクスポート設定

| 項目名 | 項目ID | 型 | 必須 | 説明 |
|--------|--------|-----|------|------|
| プロファイル | profileId | UUID | Yes | 使用するエクスポートプロファイル |

### プロファイル設定

| 項目名 | 項目ID | 型 | 必須 | 説明 |
|--------|--------|-----|------|------|
| 名前 | name | String | Yes | プロファイル名 |
| 対象エンティティ | sourceEntity | String | Yes | インポート/エクスポート対象 |
| マッピング | mapping | Array | Yes | フィールドマッピング定義 |
| 区切り文字 | delimiter | String | No | CSV区切り文字（デフォルト: セミコロン） |
| 囲み文字 | enclosure | String | No | フィールド囲み文字 |
| 更新基準 | updateBy | Array | No | 更新時の識別フィールド |

## 表示項目

### インポートタブ

| セクション | 表示項目 | 説明 |
|------------|----------|------|
| プロファイル選択 | ドロップダウン | インポート用プロファイルの選択 |
| ファイルアップロード | ドラッグ&ドロップエリア | CSV ファイルのアップロード |
| オプション | ドライランチェック | テスト実行オプション |
| 実行 | インポートボタン | インポート処理の開始 |
| 進捗 | プログレスバー | 処理進捗の表示 |
| アクティビティ | 履歴一覧 | 過去のインポート履歴 |

### エクスポートタブ

| セクション | 表示項目 | 説明 |
|------------|----------|------|
| プロファイル選択 | ドロップダウン | エクスポート用プロファイルの選択 |
| 実行 | エクスポートボタン | エクスポート処理の開始 |
| 進捗 | プログレスバー | 処理進捗の表示 |
| アクティビティ | 履歴一覧 | 過去のエクスポート履歴 |

### プロファイルタブ

| セクション | 表示項目 | 説明 |
|------------|----------|------|
| プロファイル一覧 | データグリッド | 登録済みプロファイルの一覧 |
| アクション | 追加ボタン | 新規プロファイル作成 |
| アクション | 編集ボタン | プロファイル編集モーダル |
| アクション | 複製ボタン | プロファイルの複製 |
| アクション | 削除ボタン | プロファイルの削除 |

## イベント仕様

### 1-インポート実行

**トリガー**: 「インポート」ボタンクリック

**処理フロー**:
1. ファイルとプロファイルのバリデーション
2. `importExportService.import()` API を呼び出し
3. 進捗をポーリングで監視
4. 完了時: 結果サマリーを表示
5. エラー時: エラー詳細をモーダルで表示

**データフロー**:
```
CSVファイル → importExportService.import() → API → バックグラウンド処理 → Database
```

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

**トリガー**: 「エクスポート」ボタンクリック

**処理フロー**:
1. プロファイルのバリデーション
2. `importExportService.export()` API を呼び出し
3. 進捗をポーリングで監視
4. 完了時: ダウンロードリンクを表示
5. エラー時: エラー詳細をモーダルで表示

### 3-プロファイル作成

**トリガー**: 「新規プロファイル」ボタンクリック

**処理フロー**:
1. プロファイルウィザードモーダルを表示
2. 基本情報入力（名前、対象エンティティ）
3. CSV設定（区切り文字等）
4. マッピング定義
5. `importExportProfileRepository.save()` で保存

### 4-プロファイル編集

**トリガー**: プロファイル行の編集ボタンクリック

**処理フロー**:
1. 編集モーダルを表示
2. 既存設定を読み込み
3. 変更を入力
4. `importExportProfileRepository.save()` で保存

### 5-アクティビティ詳細表示

**トリガー**: アクティビティ行のクリック

**処理フロー**:
1. `sw-import-export-activity-log-info-modal` モーダルを表示
2. 処理結果の詳細（成功件数、エラー件数、エラー詳細）を表示
3. エラーログのダウンロードオプション

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| インポート実行 | 対象エンティティのテーブル | INSERT/UPDATE | データのインポート |
| インポート実行 | import_export_log | INSERT | ログレコード作成 |
| エクスポート実行 | import_export_log | INSERT | ログレコード作成 |
| エクスポート実行 | import_export_file | INSERT | ファイルレコード作成 |
| プロファイル作成 | import_export_profile | INSERT | プロファイルレコード作成 |
| プロファイル更新 | import_export_profile | UPDATE | プロファイル情報更新 |
| プロファイル削除 | import_export_profile | DELETE | プロファイルレコード削除 |

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

#### import_export_profile

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT/UPDATE | name | 入力値 | プロファイル名 |
| INSERT/UPDATE | source_entity | エンティティ名 | 対象エンティティ |
| INSERT/UPDATE | mapping | JSON配列 | フィールドマッピング |
| INSERT/UPDATE | config | JSON | CSV設定等 |

#### import_export_log

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | activity | import/export | 処理種別 |
| INSERT | state | 処理状態 | pending/processing/completed/failed |
| INSERT | records | 処理件数 | 処理したレコード数 |
| INSERT | profile_id | UUID | 使用したプロファイル |

## メッセージ仕様

| 種別 | メッセージキー | メッセージ内容 | 表示条件 |
|------|--------------|--------------|---------|
| 成功 | sw-import-export.importer.messageImportSuccess | インポートが完了しました | インポート成功時 |
| エラー | sw-import-export.importer.messageImportError | インポートに失敗しました | インポート失敗時 |
| 成功 | sw-import-export.exporter.messageExportSuccess | エクスポートが完了しました | エクスポート成功時 |
| エラー | sw-import-export.exporter.messageExportError | エクスポートに失敗しました | エクスポート失敗時 |
| 成功 | sw-import-export.profile.messageSaveSuccess | プロファイルを保存しました | プロファイル保存成功時 |
| エラー | sw-import-export.profile.messageSaveError | プロファイルの保存に失敗しました | プロファイル保存失敗時 |

## 例外処理

| 例外状態 | 対応処理 | 画面表示 |
|---------|---------|---------|
| 権限不足 | 画面アクセス不可 | 設定メニューに表示されない |
| ファイル形式エラー | インポート中止 | 「ファイル形式が無効です」メッセージ |
| マッピングエラー | エラー詳細表示 | エラーログモーダルで詳細表示 |
| 処理タイムアウト | 再試行オプション | 「処理がタイムアウトしました」メッセージ |
| プロファイル不正 | 保存拒否 | バリデーションエラーを表示 |

## 備考

- 大量データのインポート/エクスポートはバックグラウンドで処理されます
- ドライランオプションを使用すると、実際のデータ変更なしにインポートをテストできます
- エクスポートファイルは一定期間後に自動削除されます
- システムプロファイルは編集・削除できません
- カスタムプロファイルではマッピングを自由に定義できます

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ImportExportProfileDefinition | `src/Core/Content/ImportExport/ImportExportProfileDefinition.php` | プロファイルエンティティの定義 |
| 1-2 | ImportExportLogDefinition | `src/Core/Content/ImportExport/ImportExportLogDefinition.php` | ログエンティティの定義 |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.js | `src/Administration/Resources/app/administration/src/module/sw-import-export/index.js` | モジュール登録とルート定義 |

**主要処理フロー**:
1. **10-22行目**: ImportExportService等のサービス登録
2. **25-85行目**: コンポーネントの遅延ロード登録
3. **88-147行目**: `Module.register` でモジュールを登録
4. **100-138行目**: ルート定義（import、export、profiles）

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

```
sw-import-export (Page)
    │
    ├─ sw-import-export-view-import (View)
    │      └─ sw-import-export-importer
    │             └─ importExportService.import()
    │
    ├─ sw-import-export-view-export (View)
    │      └─ sw-import-export-exporter
    │             └─ importExportService.export()
    │
    ├─ sw-import-export-view-profiles (View)
    │      ├─ importExportProfileRepository
    │      └─ sw-import-export-edit-profile-modal
    │
    └─ sw-import-export-activity
           └─ importExportLogRepository
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.js | `src/Administration/Resources/app/administration/src/module/sw-import-export/index.js` | ソース | モジュール登録・ルート定義 |
| importExport.service.js | `src/Administration/Resources/app/administration/src/module/sw-import-export/service/importExport.service.js` | ソース | インポート/エクスポートAPIサービス |
| sw-import-export-importer/index.js | `src/Administration/Resources/app/administration/src/module/sw-import-export/component/sw-import-export-importer/index.js` | ソース | インポートコンポーネント |
| sw-import-export-exporter/index.js | `src/Administration/Resources/app/administration/src/module/sw-import-export/component/sw-import-export-exporter/index.js` | ソース | エクスポートコンポーネント |
| sw-import-export-edit-profile-modal/index.js | `src/Administration/Resources/app/administration/src/module/sw-import-export/component/sw-import-export-edit-profile-modal/index.js` | ソース | プロファイル編集モーダル |
| sw-import-export-activity/index.js | `src/Administration/Resources/app/administration/src/module/sw-import-export/component/sw-import-export-activity/index.js` | ソース | アクティビティ履歴コンポーネント |
