# 画面設計書 78-顧客一覧画面

## 概要

本ドキュメントは、Medusa Admin Dashboardにおける「顧客一覧画面」の画面設計書です。ECストアの顧客情報を一覧表示し、管理するための画面について記述します。

### 本画面の処理概要

この画面では、ECストアに登録されている顧客の一覧を表示し、検索・フィルタリング・新規作成・詳細参照を行うことができます。

**業務上の目的・背景**：顧客管理は、ECビジネスにおいて重要な業務機能です。顧客の注文履歴、アカウント状態、連絡先情報などを把握し、適切なカスタマーサポートを提供するために使用されます。また、顧客グループへの割り当てや、価格表の適用対象として顧客を管理することも重要です。

**画面へのアクセス方法**：サイドナビゲーションの「Customers」メニューをクリック、またはURL `/customers` に直接アクセスすることで表示されます。

**主要な操作・処理内容**：
1. 顧客の一覧表示（メールアドレス、名前、会社名、アカウント状態、グループ）
2. キーワード検索による顧客の絞り込み
3. 各種フィルター（顧客グループ、作成日等）による絞り込み
4. ソート（メールアドレス、名前、作成日、更新日）
5. 新規顧客作成画面への遷移
6. 各顧客の詳細画面への遷移
7. 各顧客の編集画面への遷移

**画面遷移**：
- 遷移元：サイドナビゲーション、ホーム画面
- 遷移先：顧客作成画面（create）、顧客詳細画面（{id}）、顧客編集画面（{id}/edit）

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

## 関連機能

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

## 画面種別

一覧画面

## URL/ルーティング

`/customers`

## 入出力項目

### クエリパラメータ（入力）

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| q | string | No | 検索キーワード |
| offset | number | No | ページングオフセット（デフォルト: 0） |
| order | string | No | ソート順 |
| groups | string[] | No | 顧客グループフィルタ |
| created_at | object | No | 作成日フィルタ |

## 表示項目

### テーブル列

| 項目名 | データ型 | 説明 |
|--------|---------|------|
| Name | string | 顧客の名前（first_name + last_name） |
| Email | string | メールアドレス |
| Company | string | 会社名 |
| Account | StatusBadge | アカウント状態（Registered/Guest） |
| Groups | string | 所属顧客グループ名 |
| Actions | ActionMenu | 編集アクション |

### アカウント状態表示

| 状態 | 条件 | 説明 |
|------|------|------|
| Registered | has_account = true | 登録済みアカウント |
| Guest | has_account = false | ゲスト顧客 |

## イベント仕様

### 1-検索実行

検索フィールドにキーワードを入力すると、メールアドレス・名前に対して検索が実行されます。

### 2-ソート変更

テーブルヘッダーのソート可能な列をクリックすると、該当列でソートが実行されます。ソート可能列：email, first_name, last_name, has_account, created_at, updated_at

### 3-ページング

テーブル下部のページネーションコントロールを操作すると、表示ページが切り替わります。1ページあたり20件を表示します。

### 4-新規作成ボタン押下

「Create」ボタンをクリックすると、顧客作成画面（`/customers/create`）に遷移します。

### 5-行クリック

テーブルの行をクリックすると、該当顧客の詳細画面（`/customers/{id}`）に遷移します。

### 6-編集アクション選択

アクションメニューから「Edit」を選択すると、顧客編集画面（`/customers/{id}/edit`）に遷移します。

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 一覧表示 | customer | SELECT | 顧客一覧の取得 |

## メッセージ仕様

| 種別 | 条件 | メッセージ |
|------|------|-----------|
| 情報 | 顧客が存在しない場合 | No customers found（noRecordsMessage） |
| エラー | API呼び出し失敗時 | エラーをスローし、エラーバウンダリーで捕捉 |

## 例外処理

| 状態 | 処理 |
|------|------|
| API エラー発生時 | エラーをスローし、エラーバウンダリーで捕捉 |
| データ取得中 | ローディング状態を表示 |

## 備考

- ページサイズは20件固定
- placeholderDataを使用してページング時のちらつきを防止
- SingleColumnPageレイアウトを使用
- ウィジェット拡張ポイント（before/after）あり

---

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

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

### 推奨読解順序

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

処理の起点となるページコンポーネントを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | customer-list.tsx | `packages/admin/dashboard/src/routes/customers/customer-list/customer-list.tsx` | ページ全体の構成、ウィジェット拡張ポイント |

**主要処理フロー**:
1. **6行目**: useExtensionフックでウィジェット取得関数を取得
2. **8-16行目**: SingleColumnPageレイアウトで画面構成

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

一覧表示のメインロジックを実装しているテーブルコンポーネントを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | customer-list-table.tsx | `packages/admin/dashboard/src/routes/customers/customer-list/components/customer-list-table/customer-list-table.tsx` | データ取得、テーブル構成 |

**主要処理フロー**:
- **18行目**: PAGE_SIZE = 20
- **23行目**: useCustomerTableQueryでURLパラメータ解析
- **24-31行目**: useCustomersでAPI呼び出し
- **33行目**: useCustomerTableFiltersでフィルタ定義
- **36-43行目**: useDataTableでテーブル状態管理
- **59-81行目**: _DataTableでテーブルレンダリング

#### Step 3: API呼び出しを理解する

データ取得のAPIフック実装を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | customers.tsx | `packages/admin/dashboard/src/hooks/api/customers.tsx` | useCustomersフック |

**主要処理フロー**:
- **43-62行目**: useCustomers - 顧客一覧取得

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

```
CustomersList (customer-list.tsx)
    │
    ├─ useExtension() - ウィジェット取得
    │
    └─ SingleColumnPage
           │
           └─ CustomerListTable (customer-list-table.tsx)
                  │
                  ├─ useCustomerTableQuery() - URLパラメータ解析
                  │
                  ├─ useCustomers() (customers.tsx)
                  │      └─ sdk.admin.customer.list() - API呼び出し
                  │
                  ├─ useCustomerTableFilters() - フィルタ定義
                  │
                  ├─ useCustomerTableColumns() - 列定義
                  │
                  ├─ useDataTable() - テーブル状態管理
                  │
                  └─ _DataTable
                         └─ CustomerActions - 行アクションメニュー
```

### データフロー図

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

URLパラメータ ──────▶ useCustomerTableQuery() ──────▶ searchParams
(q, offset, order)

searchParams ──────▶ useCustomers() ──────▶ customers, count
                           │
                           └─▶ sdk.admin.customer.list()

customers ──────▶ useDataTable() ──────▶ table state
                        │
                        └─▶ _DataTable rendering

行クリック ──────▶ navigateTo={(row) => row.original.id}
                        │
                        └─▶ /customers/{id}
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| customer-list.tsx | `packages/admin/dashboard/src/routes/customers/customer-list/customer-list.tsx` | ソース | ページコンポーネント |
| customer-list-table.tsx | `packages/admin/dashboard/src/routes/customers/customer-list/components/customer-list-table/customer-list-table.tsx` | ソース | テーブルコンポーネント |
| customers.tsx | `packages/admin/dashboard/src/hooks/api/customers.tsx` | ソース | API呼び出しフック |
| use-customer-table-query.tsx | `packages/admin/dashboard/src/hooks/table/query/use-customer-table-query.tsx` | ソース | クエリパラメータ処理 |
| use-customer-table-columns.tsx | `packages/admin/dashboard/src/hooks/table/columns/use-customer-table-columns.tsx` | ソース | テーブル列定義 |
| use-customer-table-filters.tsx | `packages/admin/dashboard/src/hooks/table/filters/use-customer-table-filters.tsx` | ソース | フィルタ定義 |
