# 画面設計書 25-顧客グループ登録ページ

## 概要

本ドキュメントは、Shopware 6 Storefrontの顧客グループ登録ページ（Customer Group Registration Page）の画面設計書である。特定の顧客グループ（例：B2B顧客、卸売業者）への登録申請を行うための画面について記載する。

### 本画面の処理概要

顧客グループ登録ページは、特定の顧客グループへの登録を希望するユーザーが、必要な情報を入力して登録申請を行うための画面である。

**業務上の目的・背景**：ECサイトでは、B2B顧客や特定の会員グループに対して、特別価格や限定商品へのアクセスを提供することがある。このような顧客グループへの参加には審査が必要な場合があり、この画面を通じて登録申請を受け付ける。顧客グループごとに異なる登録フォーム設定（法人登録のみ、追加フィールドなど）が可能。

**画面へのアクセス方法**：
- 特定のURL（/customer-group-registration/{customerGroupId}）に直接アクセス
- ショップ内のリンクから遷移（招待制の場合）

**主要な操作・処理内容**：
1. 顧客グループ情報の表示（グループ名、説明、登録条件）
2. 登録フォームの入力（個人/法人情報、住所等）
3. 登録申請の送信
4. ダブルオプトイン（設定による）

**画面遷移**：
- 遷移元：ホームページ、専用リンク
- 遷移先：アカウントホームページ（登録成功時）、ログアウトページ（ゲスト顧客の場合）

**権限による表示制御**：
- 未ログインユーザー：登録フォーム表示
- ログイン済みユーザー：アカウントホームページへリダイレクト
- ゲスト顧客：ログアウトページへリダイレクト
- 顧客グループ設定により法人登録のみに制限可能

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 10 | 顧客グループ登録 | 主機能 | 特定顧客グループへの登録（RegisterController::customerGroupRegistration） |

## 画面種別

登録

## URL/ルーティング

| ルート名 | URL | HTTPメソッド | 説明 |
|----------|-----|--------------|------|
| frontend.account.customer-group-registration.page | /customer-group-registration/{customerGroupId} | GET | 顧客グループ登録画面表示 |

## 入出力項目

### 入力項目（パスパラメータ）

| 項目名 | パラメータ名 | 型 | 必須 | 説明 |
|--------|-------------|-----|------|------|
| 顧客グループID | customerGroupId | string(UUID) | 必須 | 登録対象の顧客グループID |

### 入力項目（フォーム）

| 項目名 | パラメータ名 | 型 | 必須 | 説明 |
|--------|-------------|-----|------|------|
| アカウント種別 | accountType | string | - | private/business |
| 敬称 | salutationId | string(UUID) | - | 敬称ID |
| 名 | firstName | string | 必須 | 名前 |
| 姓 | lastName | string | 必須 | 姓 |
| メールアドレス | email | string | 必須 | メールアドレス |
| パスワード | password | string | 必須 | パスワード |
| 会社名 | billingAddress.company | string | - | 法人の場合必須 |
| 部署 | billingAddress.department | string | - | 部署名 |
| VAT ID | vatIds | array | - | VAT番号（法人） |
| 住所（通り） | billingAddress.street | string | 必須 | 住所 |
| 郵便番号 | billingAddress.zipcode | string | 必須 | 郵便番号 |
| 市区町村 | billingAddress.city | string | 必須 | 市区町村 |
| 国 | billingAddress.countryId | string(UUID) | 必須 | 国ID |
| 州/県 | billingAddress.countryStateId | string(UUID) | - | 州/県ID |
| 電話番号 | billingAddress.phoneNumber | string | - | 電話番号 |

### 出力項目

| 項目名 | 型 | 説明 |
|--------|-----|------|
| page | CustomerGroupRegistrationPage | 登録ページオブジェクト |
| page.group | CustomerGroupEntity | 顧客グループ情報 |

## 表示項目

### 顧客グループ情報

| 項目名 | データソース | 説明 |
|--------|-------------|------|
| グループ名 | group.registrationTitle | 登録画面用タイトル |
| 説明 | group.registrationIntro | 登録説明文 |
| 利用規約 | group.registrationTerms | 登録時の利用規約 |

### 登録フォーム

標準の顧客登録フォームと同様。ただし、顧客グループ設定により以下が制御される：
- registrationOnlyCompanyRegistration: trueの場合、法人登録のみ

## イベント仕様

### 1-登録フォーム送信

登録ボタンクリックでfrontend.account.register.saveへPOST。登録処理は標準のRegisterController::registerを使用。

### 2-ダブルオプトイン

システム設定（core.loginRegistration.doubleOptInRegistration）に応じて、確認メール送信後に登録完了。

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 登録申請 | customer | INSERT | 顧客レコード作成 |
| 登録申請 | customer_address | INSERT | 住所レコード作成 |
| 登録申請 | customer_group_registration_sales_channels | INSERT | グループ登録申請記録 |

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

#### customer

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | requested_customer_group_id | 申請先顧客グループID | 承認待ち状態 |
| INSERT | customer_group_id | デフォルト顧客グループID | 承認前は標準グループ |
| INSERT | active | true/false | ダブルオプトイン設定による |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|----------|
| account.registerPersonalHeader | 表示 | 個人情報 | フォームヘッダー |
| account.optInRegistrationAlert | 成功 | 確認メールを送信しました | ダブルオプトイン時 |
| error.* | エラー | バリデーションエラーメッセージ | 入力エラー時 |

## 例外処理

| 例外 | 原因 | 処理内容 |
|------|------|----------|
| CustomerGroupNotFoundException | 顧客グループが存在しない | 404エラー |
| ConstraintViolationException | 入力バリデーションエラー | エラーメッセージ表示、フォーム再表示 |

## 備考

- 顧客グループにregistrationOnlyCompanyRegistrationが設定されている場合、accountTypeは自動的にbusinessに設定
- 登録後の顧客は requested_customer_group_id に申請先グループIDが設定され、管理者の承認を待つ
- 顧客グループのSEOメタ情報（registrationSeoMetaDescription, registrationTitle）がページのメタ情報に設定される
- v6.8.0からHTTPキャッシュが有効化される予定（PERFORMANCE_TWEAKS機能フラグ）

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | CustomerGroupRegistrationPage.php | `src/Storefront/Page/Account/CustomerGroupRegistration/CustomerGroupRegistrationPage.php` | groupプロパティ |
| 1-2 | CustomerGroupEntity.php | `src/Core/Checkout/Customer/Aggregate/CustomerGroup/CustomerGroupEntity.php` | registration*プロパティ |

**読解のコツ**: CustomerGroupEntityのregistration*プロパティ（registrationTitle, registrationIntro等）が登録ページ専用の設定。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | RegisterController.php | `src/Storefront/Controller/RegisterController.php` | customerGroupRegistration()メソッド |

**主要処理フロー**:
1. **114-118行**: ルート定義（/customer-group-registration/{customerGroupId}）
2. **119-154行**: customerGroupRegistration() - ページ表示処理
3. **122-128行**: ログイン状態チェックとリダイレクト
4. **138行**: ページローダー呼び出し
5. **140-142行**: 法人登録のみ設定の適用

#### Step 3: ページローダーを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | CustomerGroupRegistrationPageLoader.php | `src/Storefront/Page/Account/CustomerGroupRegistration/CustomerGroupRegistrationPageLoader.php` | load()メソッド |

**主要処理フロー**:
- **29-53行**: load() - ログインページを基に作成、顧客グループ情報取得、メタ情報設定

#### Step 4: テンプレートを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | index.html.twig | `src/Storefront/Resources/views/storefront/page/account/customer-group-register/index.html.twig` | メインテンプレート |
| 4-2 | customer-group-register.html.twig | `src/Storefront/Resources/views/storefront/component/account/customer-group-register.html.twig` | 登録フォームコンポーネント |

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

```
RegisterController::customerGroupRegistration()
    │
    ├─ [ログイン状態チェック]
    │      ├─ ゲスト → redirect to logout
    │      └─ ログイン済み → redirect to home
    │
    ├─ CustomerGroupRegistrationPageLoader::load()
    │      ├─ AccountLoginPageLoader::load()
    │      ├─ AbstractCustomerGroupRegistrationSettingsRoute::load()
    │      │      └─ CustomerGroupEntity取得
    │      ├─ setMetaInformation()
    │      └─ CustomerGroupRegistrationPageLoadedEvent dispatch
    │
    ├─ [registrationOnlyCompanyRegistration]
    │      └─ data.set('accountType', 'business')
    │
    └─ renderStorefront('customer-group-register/index.html.twig')

RegisterController::register() [フォーム送信時]
    │
    └─ AbstractRegisterRoute::register()
           └─ customer INSERT (requested_customer_group_id設定)
```

### データフロー図

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

Request (customerGroupId)
         │
         ▼
 RegisterController::customerGroupRegistration()
         │
         ├─► ログイン状態チェック
         │
         └─► CustomerGroupRegistrationPageLoader::load()
                   │
                   ├─► AccountLoginPageLoader
                   │         │
                   │         └─► 基本ページ情報
                   │
                   ├─► CustomerGroupRegistrationSettingsRoute
                   │         │
                   │         └─► CustomerGroupEntity
                   │
                   └─► CustomerGroupRegistrationPage
                            │
                            ▼
                       index.html.twig
                            │
                            └─► customer-group-register.html.twig
                                     │
                                     ▼
                               登録フォーム表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| RegisterController.php | `src/Storefront/Controller/RegisterController.php` | コントローラー | リクエスト処理 |
| CustomerGroupRegistrationPageLoader.php | `src/Storefront/Page/Account/CustomerGroupRegistration/CustomerGroupRegistrationPageLoader.php` | ページローダー | ページデータ組み立て |
| CustomerGroupRegistrationPage.php | `src/Storefront/Page/Account/CustomerGroupRegistration/CustomerGroupRegistrationPage.php` | ページエンティティ | ページデータ型定義 |
| AbstractCustomerGroupRegistrationSettingsRoute.php | `src/Core/Checkout/Customer/SalesChannel/AbstractCustomerGroupRegistrationSettingsRoute.php` | Store API | グループ設定取得 |
| index.html.twig | `src/Storefront/Resources/views/storefront/page/account/customer-group-register/index.html.twig` | テンプレート | メイン画面 |
| customer-group-register.html.twig | `src/Storefront/Resources/views/storefront/component/account/customer-group-register.html.twig` | テンプレート | 登録フォームコンポーネント |
