# 画面設計書 88-顧客グループ編集画面

## 概要

本ドキュメントは、Medusa Admin Dashboard における顧客グループ編集画面の設計仕様を定義したものである。既存の顧客グループの名前を編集するためのドロワー形式の画面について記述する。

### 本画面の処理概要

顧客グループ編集画面は、既存の顧客グループの名前を変更するためのドロワー形式の画面である。グループの基本情報（名前）を編集し、保存することで顧客セグメントの管理を行う。

**業務上の目的・背景**：ECサイト運営において、顧客グループの名称は時間の経過とともに変更が必要になることがある。例えば、マーケティングキャンペーンの終了に伴う名称変更や、組織の方針変更による分類名の見直しなどが考えられる。本画面は、シンプルな操作で迅速にグループ名を更新できるインターフェースを提供する。

**画面へのアクセス方法**：顧客グループ詳細画面または一覧画面の「編集」アクションをクリックすることで本画面を開く。画面はドロワー形式で右側からスライドインして表示される。

**主要な操作・処理内容**：
1. グループ名の編集
2. 保存ボタンで変更を反映
3. 保存成功後、ドロワーを閉じて元の画面に戻る

**画面遷移**：顧客グループ詳細画面または一覧画面から遷移してくる。保存成功後またはキャンセル時は元の画面に戻る。

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

## 関連機能

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

## 画面種別

更新（ドロワー形式）

## URL/ルーティング

`/customer-groups/:id/edit`

## 入出力項目

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

## 表示項目

| 項目名 | 表示位置 | 説明 |
|--------|----------|------|
| ヘッダータイトル | ドロワーヘッダー | 「顧客グループを編集」（customerGroups.edit.header） |
| グループ名ラベル | フォーム | 「名前」（fields.name） |
| キャンセルボタン | フッター | ドロワーを閉じる |
| 保存ボタン | フッター | 変更を保存 |

## イベント仕様

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

ユーザーが保存ボタンを押下すると、以下の処理が実行される：
1. フォームのバリデーションを実行
2. バリデーション成功時、`useUpdateCustomerGroup` フックを通じて API を呼び出し
3. 成功時：成功トーストを表示し、`handleSuccess()` を呼び出してドロワーを閉じる
4. 失敗時：エラートーストを表示

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

ドロワーを閉じて元の画面に戻る。未保存の変更は破棄される。

### 3-フォーム入力

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

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 保存ボタン押下 | customer_group | UPDATE | 顧客グループ名の更新 |

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

#### customer_group

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

## メッセージ仕様

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

## 例外処理

| 例外条件 | 処理内容 |
|----------|----------|
| API 更新エラー | エラートーストを表示 |
| バリデーションエラー | フィールドにエラーメッセージを表示 |
| 重複名エラー | API からのエラーメッセージをトーストで表示 |
| グループ取得エラー | エラーをスロー（isError 時） |

## 備考

- ドロワーは RouteDrawer コンポーネントを使用しており、右側からスライドインして表示
- フォームは KeyboundForm を使用しており、キーボードショートカットによる操作が可能
- 既存のグループ名が初期値として入力フィールドに表示される
- グループ内の顧客は本画面では編集できず、詳細画面で管理する
- 保存中は保存ボタンにローディングインジケータが表示される

---

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

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

### 推奨読解順序

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

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

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

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

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | customer-group-edit.tsx | `packages/admin/dashboard/src/routes/customer-groups/customer-group-edit/customer-group-edit.tsx` | CustomerGroupEdit コンポーネント（8-28行目）。useCustomerGroup でデータを取得し、RouteDrawer でフォームをラップ |

**主要処理フロー**:
1. **9行目**: useParams で URL パラメータから id を取得
2. **10行目**: useCustomerGroup でグループデータを取得
3. **14-16行目**: エラー時はエラーをスロー
4. **23-25行目**: ローディング完了後、EditCustomerGroupForm を描画

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

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

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

**主要処理フロー**:
- **26-31行目**: useForm でフォーム初期化、既存のグループ名をデフォルト値として設定
- **33行目**: useUpdateCustomerGroup フックで更新用ミューテーションを取得
- **35-50行目**: handleSubmit で保存処理を実装
- **44行目**: 成功時に handleSuccess() を呼び出してドロワーを閉じる
- **59-73行目**: グループ名フィールドの実装

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

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

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

**主要処理フロー**:
- **91行目**: sdk.admin.customerGroup.update(id, payload) で API 呼び出し
- **93-99行目**: 成功時にキャッシュを無効化

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

```
CustomerGroupEdit (customer-group-edit.tsx)
    │
    ├─ useParams() ─── URL から id 取得
    │
    ├─ useCustomerGroup(id)
    │      └─ グループデータ取得
    │
    └─ RouteDrawer
           │
           └─ EditCustomerGroupForm (edit-customer-group-form.tsx)
                  │
                  ├─ useForm() ─── フォーム状態管理（既存データで初期化）
                  │
                  ├─ useUpdateCustomerGroup(group.id)
                  │      └─ sdk.admin.customerGroup.update()
                  │             └─ queryClient.invalidateQueries()
                  │
                  └─ Form.Field ─── グループ名フィールド
```

### データフロー図

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

URL パラメータ (id) ─────▶ useCustomerGroup() ───▶ customer_group データ
                                │
                                ▼
                          useForm() ───▶ 既存データで初期化
                                │
グループ名入力 ─────────────────▶│───▶ バリデーション済みデータ
                                │
                                ▼
                        useUpdateCustomerGroup() ───▶ API 更新リクエスト
                                │
                                ▼
                        成功 ───▶ 更新済み customer_group オブジェクト
                                │
                                ▼
                        handleSuccess() ───▶ ドロワーを閉じる
                                │
                                ▼
                        トースト通知
```

### 関連ファイル一覧

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