# 画面設計書 86-顧客グループ作成画面

## 概要

本ドキュメントは、Medusa Admin Dashboard における顧客グループ作成画面の設計仕様を定義したものである。新規顧客グループを作成するためのモーダル形式の画面について記述する。

### 本画面の処理概要

顧客グループ作成画面は、新しい顧客グループを作成するためのフルスクリーンモーダル形式の画面である。グループ名を入力して保存することで、顧客をセグメント化するための新しいグループを作成できる。

**業務上の目的・背景**：ECサイト運営において、顧客セグメンテーションはマーケティング活動の効率化と顧客満足度向上の基盤となる。新しい顧客グループを作成することで、特定の顧客層に対してカスタマイズされたプロモーション、価格設定、コミュニケーション戦略を適用できるようになる。本画面は、シンプルな操作で迅速にグループを作成できるインターフェースを提供し、柔軟な顧客管理を支援する。

**画面へのアクセス方法**：顧客グループ一覧画面の「作成」ボタンをクリック、またはURLパス `/customer-groups/create` に直接アクセスすることで本画面を開く。画面はフルスクリーンモーダル形式で表示される。

**主要な操作・処理内容**：
1. グループ名の入力（必須）
2. 保存ボタンでグループを作成
3. 作成成功後、詳細画面へ自動遷移

**画面遷移**：顧客グループ一覧画面から遷移してくる。作成成功後は顧客グループ詳細画面へ遷移、キャンセル時は一覧画面に戻る。

**権限による表示制御**：認証済みの管理者ユーザーのみがアクセス可能。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 27 | 顧客グループ管理 | 主機能 | 新規顧客グループの作成 |

## 画面種別

登録（モーダル/フルスクリーンモーダル形式）

## URL/ルーティング

`/customer-groups/create`

## 入出力項目

| 項目名 | 項目ID | データ型 | 必須 | 最大長 | 入力/出力 | バリデーション | 備考 |
|--------|--------|----------|------|--------|-----------|----------------|------|
| グループ名 | name | string | 必須 | - | 入力 | 最小1文字（zod.string().min(1)） | |

## 表示項目

| 項目名 | 表示位置 | 説明 |
|--------|----------|------|
| ヘッダータイトル | モーダルヘッダー | 「顧客グループを作成」（customerGroups.create.header） |
| 説明テキスト | タイトル下部 | 「顧客をセグメント化するためのグループを作成」（customerGroups.create.hint） |
| グループ名ラベル | フォーム | 「名前」（fields.name） |
| キャンセルボタン | フッター | モーダルを閉じる |
| 作成ボタン | フッター | グループを作成 |

## イベント仕様

### 1-作成ボタン押下

ユーザーが作成ボタンを押下すると、以下の処理が実行される：
1. フォームのバリデーションを実行
2. バリデーション成功時、`useCreateCustomerGroup` フックを通じて API を呼び出し
3. 成功時：成功トーストを表示し、作成されたグループの詳細画面 `/customer-groups/:id` へ遷移
4. 失敗時：エラートーストを表示

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

モーダルを閉じて顧客グループ一覧画面に戻る。

### 3-フォーム入力

グループ名フィールドへの入力は React Hook Form によって管理され、リアルタイムでバリデーションが実行される。

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 作成ボタン押下 | customer_group | INSERT | 顧客グループの新規作成 |

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

#### customer_group

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | id | 自動生成 | UUID形式 |
| INSERT | name | フォーム入力値 | グループ名 |
| INSERT | created_at | 現在日時 | 自動設定 |
| INSERT | updated_at | 現在日時 | 自動設定 |

## メッセージ仕様

| 種別 | メッセージキー | 表示条件 | メッセージ内容（参考） |
|------|---------------|----------|----------------------|
| 成功 | customerGroups.create.successToast | 作成成功時 | グループ {name} を作成しました |
| エラー | (動的) | API エラー時 | エラーメッセージを表示 |

## 例外処理

| 例外条件 | 処理内容 |
|----------|----------|
| API 作成エラー | エラートーストを表示 |
| バリデーションエラー | フィールドにエラーメッセージを表示 |
| 重複名エラー | API からのエラーメッセージをトーストで表示 |

## 備考

- モーダルは RouteFocusModal コンポーネントを使用しており、フルスクリーン形式で表示
- フォームは KeyboundForm を使用しており、キーボードショートカットによる操作が可能
- 作成成功後は自動的に詳細画面へ遷移し、すぐに顧客の追加などの操作が可能
- フォームレイアウトは 2 カラムのグリッド構成だが、名前フィールドは1つのみ
- 作成時に顧客は含まれず、詳細画面で後から追加する

---

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

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

### 推奨読解順序

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

グループ作成のスキーマを把握することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | create-customer-group-form.tsx | `packages/admin/dashboard/src/routes/customer-groups/customer-group-create/components/create-customer-group-form/create-customer-group-form.tsx` | CreateCustomerGroupSchema（15-17行目）で定義されるフォームのバリデーションスキーマ |

**読解のコツ**: zod ライブラリによるスキーマ定義。`zod.string().min(1)` で最低1文字を要求。

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

ルートコンポーネントの構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | customer-group-create.tsx | `packages/admin/dashboard/src/routes/customer-groups/customer-group-create/customer-group-create.tsx` | CustomerGroupCreate コンポーネント（4-10行目）。RouteFocusModal でフォームをラップ |

**主要処理フロー**:
1. **6行目**: RouteFocusModal でフルスクリーンモーダルを表示
2. **7行目**: CreateCustomerGroupForm コンポーネントを描画

#### Step 3: フォームコンポーネントを理解する

フォームの実装詳細を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | create-customer-group-form.tsx | `packages/admin/dashboard/src/routes/customer-groups/customer-group-create/components/create-customer-group-form/create-customer-group-form.tsx` | フォームの実装全体（19-110行目） |

**主要処理フロー**:
- **23-28行目**: useForm でフォーム初期化、空文字をデフォルト値として設定
- **30行目**: useCreateCustomerGroup フックで作成用ミューテーションを取得
- **32-52行目**: handleSubmit で保存処理を実装
- **38行目**: 成功時に詳細画面へ遷移（handleSuccess(\`/customer-groups/\${customer_group.id}\`)）
- **73-88行目**: グループ名フィールドの実装

#### Step 4: API フックを理解する

バックエンドとの通信処理を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | customer-groups.tsx | `packages/admin/dashboard/src/hooks/api/customer-groups.tsx` | useCreateCustomerGroup フック（63-80行目） |

**主要処理フロー**:
- **71行目**: sdk.admin.customerGroup.create(payload) で API 呼び出し
- **73-75行目**: 成功時にキャッシュを無効化

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

```
CustomerGroupCreate (customer-group-create.tsx)
    │
    └─ RouteFocusModal
           │
           └─ CreateCustomerGroupForm (create-customer-group-form.tsx)
                  │
                  ├─ useForm() ─── フォーム状態管理
                  │
                  ├─ useCreateCustomerGroup()
                  │      └─ sdk.admin.customerGroup.create()
                  │             └─ queryClient.invalidateQueries()
                  │
                  └─ Form.Field ─── グループ名フィールド
```

### データフロー図

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

グループ名入力 ─────────▶ useForm() ───▶ バリデーション済みデータ
                              │
                              ▼
                        useCreateCustomerGroup() ───▶ API 作成リクエスト
                              │
                              ▼
                        成功 ───▶ customer_group オブジェクト
                              │
                              ▼
                        handleSuccess() ───▶ 詳細画面遷移 (/customer-groups/:id)
                              │
                              ▼
                        トースト通知
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| customer-group-create.tsx | `packages/admin/dashboard/src/routes/customer-groups/customer-group-create/customer-group-create.tsx` | ソース | ルートコンポーネント |
| create-customer-group-form.tsx | `packages/admin/dashboard/src/routes/customer-groups/customer-group-create/components/create-customer-group-form/create-customer-group-form.tsx` | ソース | フォームコンポーネント |
| index.ts | `packages/admin/dashboard/src/routes/customer-groups/customer-group-create/index.ts` | ソース | エクスポート定義 |
| customer-groups.tsx | `packages/admin/dashboard/src/hooks/api/customer-groups.tsx` | ソース | 顧客グループ API フック |
| RouteFocusModal | `packages/admin/dashboard/src/components/modals/` | ソース | フルスクリーンモーダルコンポーネント |
| Form | `packages/admin/dashboard/src/components/common/form/` | ソース | フォームコンポーネント |
| KeyboundForm | `packages/admin/dashboard/src/components/utilities/keybound-form/` | ソース | キーボード対応フォーム |
