# 画面設計書 69-初期設定ウィザード

## 概要

本ドキュメントは、Shopware 6 管理画面（Administration）における初期設定ウィザード画面の設計を記述したものです。Shopwareインストール後の初期セットアップを案内するウィザード形式の画面です。

### 本画面の処理概要

初期設定ウィザード（First Run Wizard）は、Shopwareをインストールした直後に表示される設定案内画面です。メール設定、PayPal連携、プラグインのインストール、Shopwareアカウント連携、デフォルト設定など、運用開始に必要な基本設定をステップバイステップで案内します。

**業務上の目的・背景**：ECサイトの初期構築時には、多くの設定項目があり、どこから始めればよいか分かりにくいことがあります。初期設定ウィザードは、必要な設定を順番に案内することで、スムーズな運用開始をサポートします。

**画面へのアクセス方法**：新規インストール後に自動的に表示されます。また、管理画面の「設定」 > 「システム」セクション > 「初期設定ウィザード」から再度アクセスできます。URL パスは `#/sw/first/run/wizard/index` です。

**主要な操作・処理内容**：
1. **ウェルカム画面**：ウィザードの開始画面
2. **データインポート**：既存データのインポート案内
3. **メール設定**：メール送信設定（SMTP、ローカル）
4. **PayPal連携**：PayPal決済の設定
5. **プラグイン**：推奨プラグインのインストール
6. **Shopwareアカウント**：Shopwareストアアカウントの連携
7. **ドメイン設定**：ショップドメインの設定
8. **ストア設定**：ストア基本設定
9. **デフォルト設定**：デフォルト値の設定
10. **完了画面**：設定完了とサマリー

**画面遷移**：
- 遷移元：新規インストール時に自動表示、または設定メニュー
- 遷移先：ダッシュボード（ウィザード完了後）
- ウィザード内：各ステップ間を「次へ」「戻る」ボタンで遷移

**権限による表示制御**：
- `admin`：初期設定ウィザードへのアクセスが可能（管理者権限必須）

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | ダッシュボード表示 | 遷移先 | ウィザード完了後の遷移先 |

## 画面種別

ウィザード

## URL/ルーティング

| 項目 | 値 |
|------|---|
| モジュール名 | sw-first-run-wizard |
| メインルート | sw.first.run.wizard.index |
| ウェルカムルート | sw.first.run.wizard.index.welcome |
| データインポートルート | sw.first.run.wizard.index.data-import |
| メール設定ルート | sw.first.run.wizard.index.mailer |
| PayPalルート | sw.first.run.wizard.index.paypal |
| プラグインルート | sw.first.run.wizard.index.plugins |
| Shopwareアカウントルート | sw.first.run.wizard.index.shopware |
| ストアルート | sw.first.run.wizard.index.store |
| デフォルトルート | sw.first.run.wizard.index.defaults |
| 完了ルート | sw.first.run.wizard.index.finish |
| URLパス | #/sw/first/run/wizard/index |

## 入出力項目

### メール設定（SMTP）

| 項目名 | 項目ID | 型 | 必須 | 説明 |
|--------|--------|-----|------|------|
| SMTPホスト | host | String | Yes | SMTPサーバーホスト名 |
| SMTPポート | port | Integer | Yes | SMTPサーバーポート番号 |
| ユーザー名 | username | String | No | SMTP認証ユーザー名 |
| パスワード | password | String | No | SMTP認証パスワード |
| 暗号化 | encryption | String | No | TLS/SSL設定 |
| 送信者メールアドレス | senderAddress | String | Yes | 送信元メールアドレス |

### PayPal設定

| 項目名 | 項目ID | 型 | 必須 | 説明 |
|--------|--------|-----|------|------|
| クライアントID | clientId | String | Yes | PayPal APIクライアントID |
| シークレット | secret | String | Yes | PayPal APIシークレット |
| サンドボックスモード | sandbox | Boolean | No | テストモードの有効化 |

### Shopwareアカウント

| 項目名 | 項目ID | 型 | 必須 | 説明 |
|--------|--------|-----|------|------|
| メールアドレス | email | String | Yes | Shopwareアカウントのメールアドレス |
| パスワード | password | String | Yes | Shopwareアカウントのパスワード |

### ドメイン設定

| 項目名 | 項目ID | 型 | 必須 | 説明 |
|--------|--------|-----|------|------|
| ショップドメイン | domain | String | Yes | ショップのドメイン名 |

## 表示項目

### ウィザード共通

| セクション | 表示項目 | 説明 |
|------------|----------|------|
| ヘッダー | 進捗インジケーター | 現在のステップと全体の進捗 |
| フッター | 戻るボタン | 前のステップに戻る |
| フッター | 次へボタン | 次のステップに進む |
| フッター | スキップボタン | 現在のステップをスキップ |

### ステップ別

| ステップ | 表示項目 | 説明 |
|----------|----------|------|
| ウェルカム | 紹介テキスト | ウィザードの説明 |
| データインポート | インポートオプション | 既存データのインポート案内 |
| メール設定 | 方式選択 | SMTP/ローカルの選択 |
| メール設定（SMTP） | 接続設定フォーム | SMTPサーバー設定入力 |
| PayPal | 連携案内 | PayPal連携の説明と設定 |
| プラグイン | 推奨プラグイン一覧 | インストール可能なプラグインカード |
| Shopwareアカウント | ログインフォーム | Shopwareアカウント連携 |
| ドメイン | ドメイン入力 | ショップドメインの設定 |
| ストア | 基本設定 | ストアの基本情報設定 |
| デフォルト | デフォルト値設定 | システムデフォルト値の設定 |
| 完了 | サマリー | 設定完了のサマリーと次のステップ案内 |

## イベント仕様

### 1-次へボタン押下

**トリガー**: 「次へ」ボタンクリック

**処理フロー**:
1. 現在のステップの入力値をバリデーション
2. バリデーション成功: 次のステップに遷移
3. バリデーション失敗: エラーメッセージを表示

### 2-戻るボタン押下

**トリガー**: 「戻る」ボタンクリック

**処理フロー**:
1. 前のステップに遷移
2. 入力済みの値は保持

### 3-スキップボタン押下

**トリガー**: 「スキップ」ボタンクリック

**処理フロー**:
1. 現在のステップをスキップ
2. 次のステップに遷移

### 4-メール設定保存

**トリガー**: メール設定ステップで「次へ」

**処理フロー**:
1. 入力値をバリデーション
2. `core.mailerSettings` に設定を保存
3. 接続テスト（オプション）
4. 次のステップに遷移

### 5-PayPalプラグインインストール

**トリガー**: PayPalステップでインストールボタン

**処理フロー**:
1. Shopwareストアからプラグインをダウンロード
2. プラグインをインストール・有効化
3. 認証情報を設定

### 6-Shopwareアカウントログイン

**トリガー**: Shopwareアカウントステップでログイン

**処理フロー**:
1. Shopware APIで認証
2. ストアアクセストークンを取得
3. プラグイン購入・ダウンロードが可能に

### 7-ウィザード完了

**トリガー**: 完了ステップで「完了」ボタン

**処理フロー**:
1. ウィザード完了フラグを設定
2. ダッシュボードに遷移
3. 次回からウィザードは自動表示されない

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| メール設定保存 | system_config | UPDATE/INSERT | メール設定の保存 |
| PayPal設定保存 | system_config | UPDATE/INSERT | PayPal設定の保存 |
| プラグインインストール | plugin | INSERT | プラグインレコード作成 |
| ドメイン設定保存 | sales_channel_domain | UPDATE | ドメイン設定の更新 |
| ウィザード完了 | system_config | UPDATE | ウィザード完了フラグ設定 |

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

#### system_config

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE/INSERT | configuration_key | core.mailerSettings.* | メール設定 |
| UPDATE/INSERT | configuration_key | SwagPayPal.settings.* | PayPal設定 |
| UPDATE/INSERT | configuration_key | frw.* | ウィザード関連設定 |

## メッセージ仕様

| 種別 | メッセージキー | メッセージ内容 | 表示条件 |
|------|--------------|--------------|---------|
| 成功 | sw-first-run-wizard.mailer.success | メール設定が保存されました | メール設定保存成功時 |
| エラー | sw-first-run-wizard.mailer.error | メール設定の保存に失敗しました | メール設定保存失敗時 |
| 成功 | sw-first-run-wizard.paypal.success | PayPal連携が完了しました | PayPal設定成功時 |
| エラー | sw-first-run-wizard.paypal.error | PayPal連携に失敗しました | PayPal設定失敗時 |
| 成功 | sw-first-run-wizard.account.success | Shopwareアカウントに接続しました | アカウントログイン成功時 |
| エラー | sw-first-run-wizard.account.error | ログインに失敗しました | アカウントログイン失敗時 |

## 例外処理

| 例外状態 | 対応処理 | 画面表示 |
|---------|---------|---------|
| 権限不足 | ウィザードアクセス不可 | 権限エラーページを表示 |
| SMTP接続失敗 | エラー表示、再試行オプション | 「SMTPサーバーに接続できません」メッセージ |
| PayPal認証失敗 | エラー表示、認証情報確認案内 | 「認証に失敗しました」メッセージ |
| プラグインインストール失敗 | エラー詳細表示 | インストールエラーの詳細 |
| ネットワークエラー | リトライオプション | 「接続エラーが発生しました」メッセージ |

## 備考

- 初期設定ウィザードは新規インストール時に一度だけ自動表示されます
- 各ステップはスキップ可能ですが、メール設定とデフォルト設定は推奨されます
- PayPal連携にはShopwareストアアカウントが必要です
- ウィザード完了後も設定メニューから再度アクセス可能です
- プラグインのインストールにはインターネット接続が必要です

---

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

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

### 推奨読解順序

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

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

**主要処理フロー**:
1. **4-35行目**: コンポーネントの遅延ロード登録
2. **42-194行目**: `Module.register` でモジュールを登録
3. **51-185行目**: ルート定義（各ウィザードステップ）
4. **188-193行目**: 設定メニューへの項目追加（systemグループ）

#### Step 2: ウィザードステップを理解する

各ステップは独立したビューコンポーネントとして実装されています。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | sw-first-run-wizard-welcome | `src/Administration/Resources/app/administration/src/module/sw-first-run-wizard/view/sw-first-run-wizard-welcome/` | ウェルカム画面 |
| 2-2 | sw-first-run-wizard-mailer-selection | `src/Administration/Resources/app/administration/src/module/sw-first-run-wizard/view/sw-first-run-wizard-mailer-selection/` | メール設定選択 |
| 2-3 | sw-first-run-wizard-paypal-info | `src/Administration/Resources/app/administration/src/module/sw-first-run-wizard/view/sw-first-run-wizard-paypal-info/` | PayPal情報 |
| 2-4 | sw-first-run-wizard-finish | `src/Administration/Resources/app/administration/src/module/sw-first-run-wizard/view/sw-first-run-wizard-finish/` | 完了画面 |

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

```
sw-first-run-wizard (Page)
    │
    ├─ sw-first-run-wizard-modal (Component)
    │      └─ ウィザードモーダルコンテナ
    │
    ├─ sw-first-run-wizard-welcome (View)
    │
    ├─ sw-first-run-wizard-data-import (View)
    │
    ├─ sw-first-run-wizard-mailer-base (View)
    │      ├─ sw-first-run-wizard-mailer-selection
    │      ├─ sw-first-run-wizard-mailer-smtp
    │      └─ sw-first-run-wizard-mailer-local
    │
    ├─ sw-first-run-wizard-paypal-base (View)
    │      ├─ sw-first-run-wizard-paypal-info
    │      └─ sw-first-run-wizard-paypal-credentials
    │
    ├─ sw-first-run-wizard-plugins (View)
    │      └─ sw-plugin-card
    │
    ├─ sw-first-run-wizard-shopware-base (View)
    │      ├─ sw-first-run-wizard-shopware-account
    │      └─ sw-first-run-wizard-shopware-domain
    │
    ├─ sw-first-run-wizard-store (View)
    │
    ├─ sw-first-run-wizard-defaults (View)
    │
    └─ sw-first-run-wizard-finish (View)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.js | `src/Administration/Resources/app/administration/src/module/sw-first-run-wizard/index.js` | ソース | モジュール登録・ルート定義 |
| sw-first-run-wizard-modal/index.js | `src/Administration/Resources/app/administration/src/module/sw-first-run-wizard/component/sw-first-run-wizard-modal/index.js` | ソース | ウィザードモーダルコンポーネント |
| sw-plugin-card/index.js | `src/Administration/Resources/app/administration/src/module/sw-first-run-wizard/component/sw-plugin-card/index.js` | ソース | プラグインカードコンポーネント |
| sw-first-run-wizard-welcome/index.js | `src/Administration/Resources/app/administration/src/module/sw-first-run-wizard/view/sw-first-run-wizard-welcome/index.js` | ソース | ウェルカム画面 |
| sw-first-run-wizard-mailer-smtp/index.js | `src/Administration/Resources/app/administration/src/module/sw-first-run-wizard/view/sw-first-run-wizard-mailer-smtp/index.js` | ソース | SMTP設定画面 |
| sw-first-run-wizard-finish/index.js | `src/Administration/Resources/app/administration/src/module/sw-first-run-wizard/view/sw-first-run-wizard-finish/index.js` | ソース | 完了画面 |
