# 画面設計書 68-一括編集

## 概要

本ドキュメントは、Shopware 6 管理画面（Administration）における一括編集画面の設計を記述したものです。複数の商品、注文、顧客データを選択して一括で編集するための操作画面です。

### 本画面の処理概要

一括編集画面は、複数のエンティティ（商品、注文、顧客）を選択した状態で、共通の項目を一括で変更するための画面です。個別に編集する手間を省き、効率的なデータ管理を実現します。

**業務上の目的・背景**：ECサイト運営において、セール価格の一括設定、在庫状況の一括変更、注文ステータスの一括更新など、複数のレコードに対して同じ変更を適用したい場面が多くあります。本画面では、一覧画面で選択した複数レコードに対して、共通の変更を一括で適用できます。

**画面へのアクセス方法**：商品一覧、注文一覧、または顧客一覧画面で複数のレコードを選択し、「一括編集」ボタンをクリックしてアクセスします。設定メニューからは直接アクセスできません。

**主要な操作・処理内容**：
1. **商品一括編集**：価格、在庫、カテゴリ、タグ、公開設定などの一括変更
2. **注文一括編集**：注文ステータス、配送ステータス、ドキュメント生成の一括処理
3. **顧客一括編集**：顧客グループ、タグ、有効/無効状態の一括変更
4. **変更タイプ選択**：上書き、追加、削除などの変更方法を選択
5. **変更内容確認**：適用前に変更内容を確認
6. **処理進捗表示**：一括処理の進捗をリアルタイムで表示

**画面遷移**：
- 遷移元：商品一覧（sw-product-list）、注文一覧（sw-order-list）、顧客一覧（sw-customer-list）
- 遷移先：遷移元の一覧画面に戻る

**権限による表示制御**：
- 商品一括編集: `product.editor` 権限が必要
- 注文一括編集: `order.editor` 権限が必要
- 顧客一括編集: `customer.editor` 権限が必要

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 22 | 商品詳細（基本情報入力） | 補助機能 | 商品一括編集 |
| 9 | 顧客詳細（基本情報入力） | 補助機能 | 顧客一括編集 |
| 18 | 注文ステータス変更 | 補助機能 | 注文一括編集 |

## 画面種別

操作

## URL/ルーティング

| 項目 | 値 |
|------|---|
| モジュール名 | sw-bulk-edit |
| 商品一括編集ルート | sw.bulk.edit.product |
| 注文一括編集ルート | sw.bulk.edit.order |
| 顧客一括編集ルート | sw.bulk.edit.customer |
| URLパス（商品） | #/sw/bulk/edit/product/:parentId/:includesDigital |
| URLパス（注文） | #/sw/bulk/edit/order/:excludeDelivery |
| URLパス（顧客） | #/sw/bulk/edit/customer |

## 入出力項目

### 商品一括編集

| 項目名 | 項目ID | 型 | 必須 | 説明 |
|--------|--------|-----|------|------|
| 有効 | active | Boolean | No | 商品の有効/無効 |
| 価格 | price | Object | No | 価格情報 |
| 在庫 | stock | Integer | No | 在庫数 |
| カテゴリ | categories | Array | No | 所属カテゴリ |
| タグ | tags | Array | No | 商品タグ |
| メディア | media | Array | No | 商品画像 |
| 説明 | description | String | No | 商品説明 |
| 公開設定 | visibilities | Array | No | 販売チャネル公開設定 |
| カスタムフィールド | customFields | Object | No | カスタムフィールド |

### 注文一括編集

| 項目名 | 項目ID | 型 | 必須 | 説明 |
|--------|--------|-----|------|------|
| 注文ステータス | orderState | String | No | 注文ステータス |
| 配送ステータス | deliveryState | String | No | 配送ステータス |
| 支払ステータス | paymentState | String | No | 支払ステータス |
| ドキュメント生成 | documents | Object | No | 請求書等のドキュメント生成 |

### 顧客一括編集

| 項目名 | 項目ID | 型 | 必須 | 説明 |
|--------|--------|-----|------|------|
| 有効 | active | Boolean | No | アカウントの有効/無効 |
| 顧客グループ | groupId | UUID | No | 顧客グループ |
| タグ | tags | Array | No | 顧客タグ |
| カスタムフィールド | customFields | Object | No | カスタムフィールド |

## 表示項目

### 共通セクション

| セクション | 表示項目 | 説明 |
|------------|----------|------|
| ヘッダー | 選択件数表示 | 一括編集対象の件数 |
| ヘッダー | 適用ボタン | 変更を適用するボタン |
| 変更タイプ | 変更タイプ選択 | 上書き/追加/削除などの選択 |
| 変更項目 | 各フィールド | エンティティ固有の編集項目 |

### 保存モーダル

| セクション | 表示項目 | 説明 |
|------------|----------|------|
| 確認 | sw-bulk-edit-save-modal-confirm | 変更内容の確認表示 |
| 処理中 | sw-bulk-edit-save-modal-process | 処理進捗の表示 |
| 成功 | sw-bulk-edit-save-modal-success | 処理成功のサマリー |
| エラー | sw-bulk-edit-save-modal-error | エラー詳細の表示 |

## イベント仕様

### 1-適用ボタン押下

**トリガー**: 「適用」ボタンクリック

**処理フロー**:
1. 変更内容のバリデーション
2. 確認モーダル（sw-bulk-edit-save-modal-confirm）を表示
3. 確認後、処理モーダル（sw-bulk-edit-save-modal-process）に遷移
4. バルクAPI で一括更新を実行
5. 完了時: 成功モーダル（sw-bulk-edit-save-modal-success）を表示
6. エラー時: エラーモーダル（sw-bulk-edit-save-modal-error）を表示

**データフロー**:
```
変更設定 → BulkEditService → Bulk API → Database → 結果サマリー
```

### 2-変更タイプ変更

**トリガー**: 変更タイプドロップダウンの値変更

**処理フロー**:
1. `sw-bulk-edit-change-type` コンポーネントで変更タイプを選択
2. 選択に応じて入力フィールドの表示を切り替え
   - 上書き: 新しい値を入力
   - 追加: 追加する値を入力
   - 削除: 削除する値を選択
   - クリア: 値をクリア

### 3-ドキュメント生成（注文一括編集）

**トリガー**: ドキュメント生成オプションの選択

**処理フロー**:
1. `sw-bulk-edit-order-documents` コンポーネントで設定
2. 生成するドキュメントタイプを選択（請求書、配送票等）
3. 適用時にバックグラウンドでドキュメントを生成
4. 生成後にダウンロードオプションを提供

### 4-処理完了後の遷移

**トリガー**: 処理完了モーダルの「閉じる」ボタン

**処理フロー**:
1. モーダルを閉じる
2. 遷移元の一覧画面に戻る（parentPath に基づく）

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 商品一括編集 | product | UPDATE | 商品情報の一括更新 |
| 商品一括編集 | product_category | INSERT/DELETE | カテゴリ関連の更新 |
| 商品一括編集 | product_tag | INSERT/DELETE | タグ関連の更新 |
| 注文一括編集 | order | UPDATE | 注文情報の一括更新 |
| 注文一括編集 | order_delivery | UPDATE | 配送情報の一括更新 |
| 注文一括編集 | document | INSERT | ドキュメント生成 |
| 顧客一括編集 | customer | UPDATE | 顧客情報の一括更新 |
| 顧客一括編集 | customer_tag | INSERT/DELETE | タグ関連の更新 |

## メッセージ仕様

| 種別 | メッセージキー | メッセージ内容 | 表示条件 |
|------|--------------|--------------|---------|
| 成功 | sw-bulk-edit.notification.saveSuccess | 一括編集が完了しました | 処理成功時 |
| エラー | sw-bulk-edit.notification.saveError | 一括編集に失敗しました | 処理失敗時 |
| 情報 | sw-bulk-edit.notification.processingInfo | 処理中です... | 処理中 |

## 例外処理

| 例外状態 | 対応処理 | 画面表示 |
|---------|---------|---------|
| 選択レコードなし | 一括編集不可 | エラーメッセージを表示 |
| 権限不足 | 編集不可 | 権限エラーを表示 |
| 一部レコード更新失敗 | 部分成功 | 成功/失敗件数を表示 |
| 処理タイムアウト | 再試行オプション | タイムアウトエラーを表示 |
| バリデーションエラー | 処理中止 | エラー詳細を表示 |

## 備考

- 一括編集は Bulk API を使用してサーバー側で処理されます
- 大量レコードの処理は分割して実行される場合があります
- 処理中は他の画面への遷移を防ぐ確認ダイアログが表示されます
- 注文の一括ドキュメント生成は非同期で処理されます
- カスタムフィールドも一括編集対象として設定可能です

---

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

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

### 推奨読解順序

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

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

**主要処理フロー**:
1. **7-71行目**: コンポーネントの遅延ロード登録
2. **77-190行目**: `Module.register` でモジュールを登録
3. **85-119行目**: 商品一括編集ルート定義
4. **120-153行目**: 注文一括編集ルート定義
5. **155-188行目**: 顧客一括編集ルート定義

#### Step 2: ページコンポーネントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | sw-bulk-edit-product/index.js | `src/Administration/Resources/app/administration/src/module/sw-bulk-edit/page/sw-bulk-edit-product/index.js` | 商品一括編集ページ |
| 2-2 | sw-bulk-edit-order/index.js | `src/Administration/Resources/app/administration/src/module/sw-bulk-edit/page/sw-bulk-edit-order/index.js` | 注文一括編集ページ |
| 2-3 | sw-bulk-edit-customer/index.js | `src/Administration/Resources/app/administration/src/module/sw-bulk-edit/page/sw-bulk-edit-customer/index.js` | 顧客一括編集ページ |

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

```
sw-bulk-edit-product / sw-bulk-edit-order / sw-bulk-edit-customer (Page)
    │
    ├─ sw-bulk-edit-change-type (Component)
    │      └─ 変更タイプの選択
    │
    ├─ sw-bulk-edit-change-type-field-renderer (Component)
    │      └─ 変更タイプに応じたフィールド表示
    │
    ├─ sw-bulk-edit-form-field-renderer (Component)
    │      └─ フォームフィールドのレンダリング
    │
    └─ sw-bulk-edit-save-modal (Component)
           ├─ sw-bulk-edit-save-modal-confirm
           ├─ sw-bulk-edit-save-modal-process
           ├─ sw-bulk-edit-save-modal-success
           └─ sw-bulk-edit-save-modal-error
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.js | `src/Administration/Resources/app/administration/src/module/sw-bulk-edit/index.js` | ソース | モジュール登録・ルート定義 |
| sw-bulk-edit-product/index.js | `src/Administration/Resources/app/administration/src/module/sw-bulk-edit/page/sw-bulk-edit-product/index.js` | ソース | 商品一括編集ページ |
| sw-bulk-edit-order/index.js | `src/Administration/Resources/app/administration/src/module/sw-bulk-edit/page/sw-bulk-edit-order/index.js` | ソース | 注文一括編集ページ |
| sw-bulk-edit-customer/index.js | `src/Administration/Resources/app/administration/src/module/sw-bulk-edit/page/sw-bulk-edit-customer/index.js` | ソース | 顧客一括編集ページ |
| sw-bulk-edit-change-type/index.js | `src/Administration/Resources/app/administration/src/module/sw-bulk-edit/component/sw-bulk-edit-change-type/index.js` | ソース | 変更タイプ選択コンポーネント |
| sw-bulk-edit-save-modal/index.js | `src/Administration/Resources/app/administration/src/module/sw-bulk-edit/component/sw-bulk-edit-save-modal/index.js` | ソース | 保存モーダルコンポーネント |
