# 画面設計書 85-顧客グループ一覧画面

## 概要

本ドキュメントは、Medusa Admin Dashboard における顧客グループ一覧画面の設計仕様を定義したものである。登録されている顧客グループの一覧を表示・管理するための画面について記述する。

### 本画面の処理概要

顧客グループ一覧画面は、システムに登録されているすべての顧客グループを一覧形式で表示し、検索・フィルタリング・並び替えを行うことができる画面である。新規グループの作成や既存グループへの遷移も本画面から行う。

**業務上の目的・背景**：ECサイト運営において、顧客セグメンテーションは効果的なマーケティング戦略の基盤となる。VIP顧客、法人顧客、地域別顧客、購買頻度別顧客など、様々な切り口でグループを作成し管理することで、ターゲットを絞った施策（プロモーション、価格設定、コミュニケーション）が可能になる。本画面は、これらの顧客グループを俯瞰的に把握し、効率的に管理するためのダッシュボードを提供する。

**画面へのアクセス方法**：サイドメニューの「顧客グループ」をクリック、または設定画面から「顧客グループ」を選択、またはURLパス `/customer-groups` に直接アクセスすることで本画面を開く。

**主要な操作・処理内容**：
1. 顧客グループ一覧の表示（ページネーション付き）
2. グループ名での検索
3. 作成日・更新日でのフィルタリング
4. カラムによるソート（名前、作成日、更新日）
5. グループ行クリックで詳細画面へ遷移
6. アクションメニューから編集・削除
7. 新規作成ボタンで作成画面へ遷移

**画面遷移**：ホーム画面または設定画面から遷移。グループ行クリックで詳細画面、新規作成ボタンで作成画面、編集アクションで編集画面へ遷移する。

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 27 | 顧客グループ管理 | 主機能 | 顧客グループ一覧の取得・表示 |

## 画面種別

一覧

## URL/ルーティング

`/customer-groups`

## 入出力項目

| 項目名 | 項目ID | データ型 | 必須 | 最大長 | 入力/出力 | バリデーション | 備考 |
|--------|--------|----------|------|--------|-----------|----------------|------|
| 検索キーワード | q | string | - | - | 入力 | なし | URLクエリパラメータ |
| ソート順 | order | string | - | - | 入力 | なし | カラム名と方向 |
| オフセット | offset | number | - | - | 入力 | なし | ページネーション用 |
| 作成日フィルタ | created_at | object | - | - | 入力 | JSON形式 | 日付範囲 |
| 更新日フィルタ | updated_at | object | - | - | 入力 | JSON形式 | 日付範囲 |

## 表示項目

| 項目名 | 表示位置 | 説明 |
|--------|----------|------|
| ヘッダータイトル | テーブルヘッダー | 「顧客グループ」（customerGroups.domain） |
| 検索ボックス | テーブルヘッダー | グループ名で検索 |
| 新規作成ボタン | テーブルヘッダー | 「作成」（actions.create） |
| グループ名 | テーブルカラム | 顧客グループの名前（ソート可能） |
| 顧客数 | テーブルカラム | グループに所属する顧客の数 |
| 作成日 | テーブルカラム | グループの作成日時（ソート可能） |
| 更新日 | テーブルカラム | グループの更新日時（ソート可能） |
| アクションメニュー | 各行末尾 | 編集・削除アクション |
| ページネーション | テーブルフッター | ページ切り替え |
| 日付フィルター | フィルターパネル | 作成日・更新日フィルター |

## イベント仕様

### 1-グループ行クリック

テーブルの行をクリックすると、該当グループの詳細画面 `/customer-groups/:id` へ遷移する。

### 2-新規作成ボタンクリック

「作成」ボタンをクリックすると、顧客グループ作成画面 `/customer-groups/create` へ遷移する。

### 3-編集アクション

アクションメニューの「編集」を選択すると、顧客グループ編集画面 `/customer-groups/:id/edit` へ遷移する。

### 4-削除アクション

アクションメニューの「削除」を選択すると、以下の処理が実行される：
1. 削除確認ダイアログを表示（グループ名の入力による確認）
2. ユーザーがグループ名を入力して確認
3. `useDeleteCustomerGroupLazy` フックを通じて API を呼び出し
4. 成功時：成功トーストを表示し、一覧を更新
5. 失敗時：エラートーストを表示

### 5-検索

検索ボックスへの入力でリアルタイムにフィルタリングが実行される。URLクエリパラメータ `q` として保持される。

### 6-ソート

カラムヘッダーをクリックすると、そのカラムでソートが切り替わる。URLクエリパラメータ `order` として保持される。

### 7-フィルター

日付フィルターで作成日・更新日の範囲を指定できる。URLクエリパラメータとしてJSON形式で保持される。

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 削除アクション | customer_group | DELETE | 顧客グループの削除 |

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

#### customer_group

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| DELETE | - | id = 選択されたグループID | グループ全体を削除 |

## メッセージ仕様

| 種別 | メッセージキー | 表示条件 | メッセージ内容（参考） |
|------|---------------|----------|----------------------|
| 成功 | customerGroups.delete.successToast | 削除成功時 | グループ {name} を削除しました |
| エラー | (動的) | API エラー時 | エラーメッセージを表示 |
| 空状態 | customerGroups.list.empty.heading | データなし時 | 顧客グループがありません |
| 空状態 | customerGroups.list.empty.description | データなし時 | 新しいグループを作成してください |
| フィルタ結果なし | customerGroups.list.filtered.heading | 検索結果なし時 | 該当するグループがありません |
| フィルタ結果なし | customerGroups.list.filtered.description | 検索結果なし時 | 検索条件を変更してください |

## 例外処理

| 例外条件 | 処理内容 |
|----------|----------|
| グループ一覧取得エラー | エラーをスローしてエラー境界で処理 |
| 削除エラー | エラートーストを表示 |

## 備考

- DataTable コンポーネントを使用しており、ページネーション、ソート、フィルタリング機能を標準提供
- 1ページあたりの表示件数は10件（PAGE_SIZE = 10）
- 顧客数の表示のため、グループ取得時に顧客IDも含めて取得（fields: "id,name,created_at,updated_at,customers.id"）
- 削除確認にはグループ名のタイプ確認が必要（verificationText）
- keepPreviousData オプションにより、データ取得中も前のデータを表示
- SingleColumnPage レイアウトを使用し、拡張ウィジェットの挿入ポイントを提供

---

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

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

### 推奨読解順序

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

顧客グループの型定義を把握することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | HttpTypes.AdminCustomerGroup | `@medusajs/types` | 顧客グループの型定義（id, name, customers, created_at, updated_at） |

**読解のコツ**: HttpTypes パッケージで定義される AdminCustomerGroup 型を参照。customers はリレーションで取得。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | customer-group-list.tsx | `packages/admin/dashboard/src/routes/customer-groups/customer-group-list/customer-group-list.tsx` | CustomerGroupsList コンポーネント（5-18行目）。SingleColumnPage でレイアウト |

**主要処理フロー**:
1. **6行目**: `useExtension()` でウィジェット取得
2. **9-16行目**: SingleColumnPage 内に CustomerGroupListTable を配置

#### Step 3: テーブルコンポーネントを理解する

一覧テーブルの実装詳細を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | customer-group-list-table.tsx | `packages/admin/dashboard/src/routes/customer-groups/customer-group-list/components/customer-group-list-table/customer-group-list-table.tsx` | テーブルの実装全体（27-223行目） |

**主要処理フロー**:
- **31-37行目**: useQueryParams でURLパラメータを取得
- **42-56行目**: useCustomerGroups でグループ一覧を取得
- **69-96行目**: DataTable コンポーネントを描画
- **100-215行目**: useColumns でカラム定義（名前、顧客数、作成日、更新日、アクション）
- **110-140行目**: handleDeleteCustomerGroup で削除処理

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | customer-groups.tsx | `packages/admin/dashboard/src/hooks/api/customer-groups.tsx` | useCustomerGroups フック（42-61行目）、useDeleteCustomerGroupLazy フック（130-151行目） |

**主要処理フロー**:
- **54-55行目**: sdk.admin.customerGroup.list(query) で API 呼び出し
- **138行目**: sdk.admin.customerGroup.delete(id) で削除 API 呼び出し
- **139-145行目**: 成功時にキャッシュを無効化

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

```
CustomerGroupsList (customer-group-list.tsx)
    │
    ├─ useExtension() ─── ウィジェット取得
    │
    └─ SingleColumnPage
           │
           └─ CustomerGroupListTable (customer-group-list-table.tsx)
                  │
                  ├─ useQueryParams() ─── URLパラメータ取得
                  │
                  ├─ useColumns() ─── カラム定義
                  │
                  ├─ useFilters() ─── フィルター定義
                  │
                  ├─ useCustomerGroups() ─── グループ一覧取得
                  │      └─ sdk.admin.customerGroup.list()
                  │
                  ├─ useDeleteCustomerGroupLazy() ─── 削除処理
                  │      └─ sdk.admin.customerGroup.delete()
                  │
                  └─ DataTable ─── テーブル表示
```

### データフロー図

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

URLパラメータ ─────────▶ useQueryParams() ───▶ q, order, offset, filters
                              │
                              ▼
API呼び出し ───────────▶ useCustomerGroups() ───▶ グループ一覧
                              │
                              ▼
                        DataTable ───▶ テーブル表示
                              │
行クリック ────────────▶ rowHref ───▶ 詳細画面遷移 (/customer-groups/:id)
                              │
削除アクション ────────▶ handleDeleteCustomerGroup() ───▶ 確認ダイアログ
                              │
                              ▼
                        useDeleteCustomerGroupLazy() ───▶ API 削除
                              │
                              ▼
                        成功/エラー ───▶ トースト通知 + 一覧更新
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| customer-group-list.tsx | `packages/admin/dashboard/src/routes/customer-groups/customer-group-list/customer-group-list.tsx` | ソース | ルートコンポーネント |
| customer-group-list-table.tsx | `packages/admin/dashboard/src/routes/customer-groups/customer-group-list/components/customer-group-list-table/customer-group-list-table.tsx` | ソース | テーブルコンポーネント |
| index.ts | `packages/admin/dashboard/src/routes/customer-groups/customer-group-list/index.ts` | ソース | エクスポート定義 |
| customer-groups.tsx | `packages/admin/dashboard/src/hooks/api/customer-groups.tsx` | ソース | 顧客グループ API フック |
| DataTable | `packages/admin/dashboard/src/components/data-table/` | ソース | データテーブルコンポーネント |
| SingleColumnPage | `packages/admin/dashboard/src/components/layout/pages/` | ソース | 単一カラムレイアウト |
| useDataTableDateFilters | `packages/admin/dashboard/src/components/data-table/helpers/` | ソース | 日付フィルターヘルパー |
