# 画面設計書 56-顧客グループ設定

## 概要

本ドキュメントは、Shopware 6 管理画面における顧客グループ設定（sw-settings-customer-group）画面の設計書です。ECサイトで使用する顧客グループの登録・編集・管理を行う画面について記述します。

### 本画面の処理概要

**業務上の目的・背景**：ECサイトにおいて、顧客を異なるグループに分類することで、グループごとの価格設定、税表示方法（税込/税抜）、特定のコンテンツへのアクセス制限などを実現できます。本画面では、顧客グループの基本情報と顧客グループ登録機能（B2B向けセルフサービス登録）の設定を管理します。

**画面へのアクセス方法**：管理画面にログイン後、左メニューの「設定」 > 「顧客グループ」をクリックして一覧画面にアクセスします。一覧画面から新規作成ボタンまたは既存の顧客グループ名をクリックして詳細画面に遷移します。

**主要な操作・処理内容**：
1. 顧客グループ一覧の表示・検索・ソート
2. 新規顧客グループの作成（グループ名、税表示方法の設定）
3. 既存顧客グループの編集
4. 顧客グループ登録機能の有効化/無効化
5. 登録フォームの設定（タイトル、説明、技術的URL、SEO設定）
6. インライン編集による迅速な更新
7. 顧客グループの削除

**画面遷移**：設定メニュー → 顧客グループ一覧画面 → 顧客グループ詳細画面。詳細画面から一覧画面への戻り遷移も可能です。

**権限による表示制御**：`customer_groups.viewer`権限で閲覧可能、`customer_groups.editor`権限で編集可能、`customer_groups.creator`権限で新規作成可能、`customer_groups.deleter`権限で削除可能です。権限がない場合、該当するボタンやアクションは無効化されます。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 21 | 顧客管理 | 参照元 | 顧客への顧客グループ割り当て |

## 画面種別

一覧 / 詳細 / 登録 / 編集

## URL/ルーティング

| 画面 | URL | コンポーネント |
|------|-----|---------------|
| 顧客グループ一覧 | `#/sw/settings/customer/group/index` | sw-settings-customer-group-list |
| 顧客グループ詳細 | `#/sw/settings/customer/group/detail/:id` | sw-settings-customer-group-detail |
| 顧客グループ新規作成 | `#/sw/settings/customer/group/create` | sw-settings-customer-group-create |

## 入出力項目

### 一覧画面

| 項目名 | 項目ID | 型 | 入力/出力 | 必須 | 説明 |
|--------|--------|-----|----------|------|------|
| 名前 | name | string | 入出力 | ○ | 顧客グループの表示名 |
| 税込表示 | displayGross | boolean | 入出力 | - | 税込価格表示フラグ |

### 詳細画面

| 項目名 | 項目ID | 型 | 入力/出力 | 必須 | 説明 |
|--------|--------|-----|----------|------|------|
| 名前 | name | string | 入力 | ○ | 顧客グループの表示名 |
| 税込表示 | displayGross | boolean | 入力 | - | 税込価格表示フラグ |
| 登録を有効化 | registrationActive | boolean | 入力 | - | 顧客グループ登録機能の有効化 |
| 登録タイトル | registrationTitle | string | 入力 | 条件付 | 登録フォームのタイトル（登録有効時必須） |
| 登録概要 | registrationIntroduction | text | 入力 | - | 登録フォームの説明文 |
| 追加の利用規約 | registrationOnlyCompanyRegistration | boolean | 入力 | - | 会社専用登録フラグ |
| SEO タイトル | registrationSeoMetaDescription | string | 入力 | - | SEO用メタディスクリプション |
| 販売チャネル | registrationSalesChannels | relation | 入力 | - | 登録フォームを表示する販売チャネル |

## 表示項目

### 一覧画面

| 項目名 | 説明 |
|--------|------|
| 顧客グループ名 | 顧客グループの表示名（詳細画面へのリンク） |
| 税込表示 | 税込価格表示フラグ |

### 詳細画面

| 項目名 | 説明 |
|--------|------|
| 基本情報 | グループ名、税表示設定 |
| 顧客グループ登録 | 登録機能の有効化、フォーム設定 |
| SEO/URL | 技術的URL、SEOメタ情報、販売チャネル別URL |
| カスタムフィールド | カスタムフィールドセットが定義されている場合に表示 |

## イベント仕様

### 1-保存ボタン押下

ユーザーが「保存」ボタンを押下すると、入力された顧客グループ情報がバリデーションされ、customerGroupリポジトリを通じてAPIに保存リクエストが送信されます。registrationActiveがtrueでregistrationTitleが空の場合、バリデーションエラーとなります。

### 2-キャンセルボタン押下

ユーザーが「キャンセル」ボタンを押下すると、変更を破棄して顧客グループ一覧画面に遷移します。

### 3-削除ボタン押下

一覧画面または詳細画面で削除を実行すると、customerGroupCanBeDeletedメソッドで削除可否がチェックされます。顧客または販売チャネルに関連付けられている場合は削除できません。

### 4-登録機能有効化/無効化

「顧客グループ登録を有効にする」トグルを切り替えると、hasRegistrationフラグが更新され、登録フォーム設定フィールドの表示/非表示が切り替わります。

### 5-販売チャネル選択

登録フォームを表示する販売チャネルを選択すると、registrationSalesChannelsが更新されます。選択された販売チャネルごとにSEO URLが自動生成されます。

### 6-インライン編集

一覧画面でセルをダブルクリックすると、インライン編集モードが有効になります。名前と税込表示がインライン編集可能です。

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 保存ボタン押下 | customer_group | INSERT/UPDATE | 顧客グループ情報の新規作成または更新 |
| 保存ボタン押下 | customer_group_translation | INSERT/UPDATE | 顧客グループの翻訳情報 |
| 販売チャネル選択 | customer_group_registration_sales_channels | INSERT/DELETE | 登録販売チャネルの関連付け |
| 削除ボタン押下 | customer_group | DELETE | 顧客グループの削除 |

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

#### customer_group

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT/UPDATE | id | UUIDv4 | 新規作成時は自動生成 |
| INSERT/UPDATE | name | 入力値 | 顧客グループ名 |
| INSERT/UPDATE | display_gross | 入力値 | 税込表示フラグ |
| INSERT/UPDATE | registration_active | 入力値 | 登録機能有効フラグ |
| INSERT/UPDATE | registration_title | 入力値 | 登録フォームタイトル |
| INSERT/UPDATE | registration_introduction | 入力値 | 登録フォーム説明 |
| INSERT/UPDATE | registration_only_company_registration | 入力値 | 会社専用登録フラグ |
| INSERT/UPDATE | registration_seo_meta_description | 入力値 | SEOメタディスクリプション |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|------------|------|--------------|----------|
| notificationSuccessMessage | 成功 | 顧客グループが正常に保存されました | 保存成功時 |
| notificationErrorMessage | エラー | 顧客グループの保存中にエラーが発生しました | 保存失敗時 |
| errorMessageCannotDeleteCustomerGroup | エラー | 顧客または販売チャネルに関連付けられているため削除できません | 削除失敗時 |
| requiredFieldsInvalid | エラー | 必須項目が入力されていません | 登録タイトル未入力時 |

## 例外処理

| 例外ケース | 処理内容 |
|-----------|---------|
| 顧客グループが見つからない | エラー通知を表示し、一覧画面にリダイレクト |
| 権限不足 | 該当するアクションボタンを無効化し、ツールチップで警告表示 |
| 通信エラー | エラー通知を表示し、ローディング状態を解除 |
| バリデーションエラー | registrationTitleError設定、該当項目にエラー表示 |
| 使用中の顧客グループ削除 | 削除不可エラー通知を表示 |
| 顧客との関連 | customers.length > 0 で削除不可 |
| 販売チャネルとの関連 | salesChannels.length > 0 で削除不可 |

## 備考

- 顧客グループ登録機能はB2B向けのセルフサービス登録を提供します
- 登録が有効な場合、登録タイトルはシステムデフォルト言語で必須となります
- 技術的URLは `/customer-group-registration/{id}#` 形式で自動生成されます
- SEO URLは販売チャネルごとに設定された言語に基づいて生成されます
- カスタムフィールドセットが定義されている場合、詳細画面にカスタムフィールドセクションが表示されます
- hasRegistrationはregistration !== undefinedで判定されます

---

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

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

### 推奨読解順序

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

顧客グループエンティティとその関連データの構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | CustomerGroupDefinition.php | `src/Core/Checkout/Customer/Aggregate/CustomerGroup/` | 顧客グループエンティティの定義 |
| 1-2 | CustomerGroupRegistrationDefinition.php | `src/Core/Checkout/Customer/Aggregate/CustomerGroupRegistration/` | 登録機能の関連エンティティ |

**読解のコツ**: 顧客グループは登録機能とSEO URLの両方の関連を持っています。

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

モジュール登録とルーティング設定を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-customer-group/index.js` | モジュール登録、ルート定義、権限設定 |

**主要処理フロー**:
1. **20-74行目**: Module.registerでモジュール登録
2. **32-64行目**: routes定義（index, detail, create）
3. **66-72行目**: settingsItem定義（設定メニューへの追加、customerグループ）

#### Step 3: 一覧画面コンポーネントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-customer-group/page/sw-settings-customer-group-list/index.js` | 一覧画面のロジック |

**主要処理フロー**:
- **51-58行目**: allCustomerGroupsCriteria - 顧客グループ一覧取得条件
- **70-90行目**: getList() - 顧客グループ一覧の取得
- **92-107行目**: getColumns() - グリッドカラム定義
- **123-128行目**: customerGroupCanBeDeleted() - 削除可否判定
- **130-140行目**: deleteCustomerGroup() - 削除処理

#### Step 4: 詳細画面コンポーネントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-customer-group/page/sw-settings-customer-group-detail/index.js` | 詳細画面のロジック |

**主要処理フロー**:
- **216-229行目**: createdComponent() - 初期化処理
- **231-242行目**: loadCustomerGroup() - 顧客グループデータの読み込み
- **170-181行目**: hasRegistration - 登録機能の有効/無効判定
- **285-306行目**: validateSaveRequest() - 登録タイトル必須バリデーション
- **308-327行目**: onSave() - 保存処理

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

```
sw-settings-customer-group (モジュール)
    │
    ├─ sw-settings-customer-group-list (一覧画面)
    │      ├─ customerGroupRepository.search() - 一覧取得
    │      ├─ customerGroupCanBeDeleted() - 削除可否判定
    │      └─ customerGroupRepository.delete() - 削除
    │
    └─ sw-settings-customer-group-detail (詳細画面)
           ├─ customerGroupRepository.get() - 詳細取得
           ├─ customerGroupRepository.create() - 新規作成
           ├─ customerGroupRepository.save() - 保存
           ├─ validateSaveRequest() - バリデーション
           │     └─ registrationTitleError 設定
           └─ seoUrlRepository - SEO URL管理
```

### データフロー図

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

顧客グループフォーム ───▶ sw-settings-customer-group-detail ──▶ customer_group テーブル
                              │
登録設定入力 ──────────▶      ├─▶ validateSaveRequest()
                              │     └─▶ registrationTitle チェック
                              │
販売チャネル選択 ─────▶       └─▶ customerGroupRepository.save()
                                        │
                                        ▼
                              Admin API (/api/customer-group)
                                        │
                                        ▼
                              CustomerGroupRepository (PHP)
                                        │
                                        ├─▶ customer_group
                                        ├─▶ customer_group_translation
                                        └─▶ seo_url
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-customer-group/index.js` | ソース | モジュール定義 |
| index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-customer-group/page/sw-settings-customer-group-list/index.js` | ソース | 一覧画面ロジック |
| sw-settings-customer-group-list.html.twig | `src/Administration/Resources/app/administration/src/module/sw-settings-customer-group/page/sw-settings-customer-group-list/sw-settings-customer-group-list.html.twig` | テンプレート | 一覧画面UI |
| index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-customer-group/page/sw-settings-customer-group-detail/index.js` | ソース | 詳細画面ロジック |
| sw-settings-customer-group-detail.html.twig | `src/Administration/Resources/app/administration/src/module/sw-settings-customer-group/page/sw-settings-customer-group-detail/sw-settings-customer-group-detail.html.twig` | テンプレート | 詳細画面UI |
| index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-customer-group/acl/index.js` | ソース | 権限定義 |
