# 画面設計書 71-価格表一覧画面

## 概要

本ドキュメントは、Medusa Admin Dashboardにおける「価格表一覧画面」の画面設計書です。価格表（Price List）の一覧表示・検索・フィルタリング・削除機能を提供する画面について記述します。

### 本画面の処理概要

この画面では、ECストアに登録されている価格表（Price List）の一覧を表示し、管理者が価格表の管理を行うことができます。

**業務上の目的・背景**：価格表は、特定の顧客グループや期間に対して適用される特別価格を管理するための機能です。セール価格やB2B向け卸価格、会員限定価格など、通常価格とは異なる価格設定を柔軟に行う必要があるECビジネスにおいて、価格表機能は不可欠です。本画面は、これらの価格表を一元的に管理し、迅速に状況を把握するためのエントリーポイントとして機能します。

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

**主要な操作・処理内容**：
1. 価格表の一覧表示（タイトル、ステータス、価格オーバーライド数を表示）
2. キーワード検索による価格表の絞り込み
3. ステータス（active/draft/scheduled/expired）によるフィルタリング
4. 作成日・更新日によるソート
5. 新規価格表作成画面への遷移
6. 各価格表の編集画面への遷移
7. 価格表の削除（確認ダイアログ付き）

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

**権限による表示制御**：認証済みユーザーのみアクセス可能です。管理者権限を持つユーザーが利用することを想定しています。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 53 | 価格リスト管理 | 主機能 | 価格表一覧の取得・表示 |

## 画面種別

一覧画面

## URL/ルーティング

`/price-lists`

## 入出力項目

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

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| q | string | No | 検索キーワード |
| offset | number | No | ページングオフセット（デフォルト: 0） |
| order | string | No | ソート順（title, status, created_at, updated_at） |
| status | string | No | ステータスフィルタ（カンマ区切りで複数指定可能） |

## 表示項目

### テーブル列

| 項目名 | データ型 | 説明 |
|--------|---------|------|
| Title | string | 価格表のタイトル |
| Status | StatusBadge | 価格表のステータス（active/draft/scheduled/expired） |
| Price Overrides | number | 価格オーバーライドの件数 |
| Actions | ActionMenu | 編集・削除アクション |

### ステータス表示

| ステータス | 色 | 説明 |
|-----------|-----|------|
| active | green | 有効な価格表 |
| draft | grey | 下書き状態 |
| scheduled | orange | 開始日が未来の価格表 |
| expired | red | 終了日を過ぎた価格表 |

## イベント仕様

### 1-検索実行

検索フィールドにキーワードを入力すると、タイトルに対してあいまい検索が実行されます。入力後にデバウンス処理が行われ、URLのクエリパラメータ `q` が更新されます。

### 2-ソート変更

テーブルヘッダーのソート可能な列（Title, Status, Created At, Updated At）をクリックすると、該当列でソートが実行されます。URLのクエリパラメータ `order` が更新されます。

### 3-ページング

テーブル下部のページネーションコントロールを操作すると、表示ページが切り替わります。1ページあたり20件を表示し、URLのクエリパラメータ `offset` が更新されます。

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

「Create」ボタンをクリックすると、価格表作成画面（`/price-lists/create`）に遷移します。

### 5-行クリック

テーブルの行をクリックすると、該当価格表の詳細画面（`/price-lists/{id}`）に遷移します。

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

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

### 7-削除アクション選択

アクションメニューから「Delete」を選択すると、確認ダイアログが表示されます。確認後、価格表が削除されます。

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 一覧表示 | price_list | SELECT | 価格表一覧の取得 |
| 削除アクション | price_list | DELETE | 価格表の削除 |

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

#### price_list（削除時）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| DELETE | id | 選択した価格表のID | 論理削除または物理削除 |

## メッセージ仕様

| 種別 | 条件 | メッセージ |
|------|------|-----------|
| 成功 | 価格表削除成功時 | "{title}" was successfully deleted. |
| エラー | API呼び出し失敗時 | エラーメッセージをトースト表示 |
| 確認 | 削除確認時 | Are you sure you want to delete "{title}"? |

## 例外処理

| 状態 | 処理 |
|------|------|
| API エラー発生時 | エラーをスローし、エラーバウンダリーで捕捉 |
| データ取得中 | ローディング状態を表示 |
| 価格表が存在しない場合 | 空の状態を表示 |

## 備考

- ページサイズは20件固定
- 価格オーバーライド数は各価格表に対して別途APIリクエストで取得
- placeholderDataを使用してページング時のちらつきを防止

---

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

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

### 推奨読解順序

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

まず、価格表のデータ構造とAPI型定義を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | HttpTypes | `@medusajs/types` | AdminPriceList, AdminPriceListListParams の型定義を確認 |
| 1-2 | constants.ts | `packages/admin/dashboard/src/routes/price-lists/common/constants.ts` | PriceListStatus, PriceListType の列挙型定義 |

**読解のコツ**: HttpTypesは@medusajs/typesパッケージで定義されており、AdminPriceListがフロントエンドで扱う価格表のデータ構造を表します。

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

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

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

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

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | price-list-list-table.tsx | `packages/admin/dashboard/src/routes/price-lists/price-list-list/components/price-list-list-table/price-list-list-table.tsx` | データ取得、テーブル構成、ページング |
| 3-2 | use-pricing-table-query.tsx | `packages/admin/dashboard/src/routes/price-lists/price-list-list/components/price-list-list-table/use-pricing-table-query.tsx` | URLクエリパラメータの解析 |
| 3-3 | use-pricing-table-columns.tsx | `packages/admin/dashboard/src/routes/price-lists/price-list-list/components/price-list-list-table/use-pricing-table-columns.tsx` | テーブル列定義 |
| 3-4 | use-pricing-table-filters.tsx | `packages/admin/dashboard/src/routes/price-lists/price-list-list/components/price-list-list-table/use-pricing-table-filters.tsx` | フィルター定義 |

**主要処理フロー**:
- **17-25行目**: usePriceListsフックでAPI呼び出し、searchParamsでフィルタ条件を渡す
- **30-37行目**: useDataTableフックでテーブル状態管理
- **56-73行目**: _DataTableコンポーネントでテーブルレンダリング

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | price-lists.tsx | `packages/admin/dashboard/src/hooks/api/price-lists.tsx` | usePriceLists, useDeletePriceListフック |

**主要処理フロー**:
- **46-65行目**: usePriceLists - 価格表一覧取得
- **113-130行目**: useDeletePriceList - 価格表削除、キャッシュ無効化

#### Step 5: 削除アクションを理解する

削除処理の詳細実装を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | use-delete-price-list-action.tsx | `packages/admin/dashboard/src/routes/price-lists/common/hooks/use-delete-price-list-action.tsx` | 削除確認ダイアログ、削除実行 |

**主要処理フロー**:
- **19-27行目**: prompt()で確認ダイアログ表示
- **33-46行目**: mutateAsync()で削除実行、成功・失敗時の処理

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

```
PriceListList (price-list-list.tsx)
    │
    └─ PriceListListTable (price-list-list-table.tsx)
           │
           ├─ usePricingTableQuery() - URLパラメータ解析
           │
           ├─ usePriceLists() (price-lists.tsx)
           │      └─ sdk.admin.priceList.list() - API呼び出し
           │
           ├─ usePricingTableFilters() - フィルタ定義
           │
           ├─ usePricingTableColumns() - 列定義
           │      │
           │      ├─ StatusCell - ステータス表示
           │      │
           │      ├─ PriceCountCell (price-count-cell.tsx)
           │      │      └─ usePriceListPrices() - 価格数取得
           │      │
           │      └─ PriceListListTableActions (price-list-list-table-actions.tsx)
           │             └─ useDeletePriceListAction()
           │                    └─ useDeletePriceList() - 削除API
           │
           └─ _DataTable - 汎用テーブルコンポーネント
```

### データフロー図

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

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

searchParams ──────▶ usePriceLists() ──────▶ price_lists, count
                           │
                           └─▶ sdk.admin.priceList.list()

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

削除アクション ──────▶ useDeletePriceListAction()
                           │
                           ├─▶ prompt() (確認)
                           │
                           └─▶ useDeletePriceList()
                                  │
                                  └─▶ sdk.admin.priceList.delete()
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| price-list-list.tsx | `packages/admin/dashboard/src/routes/price-lists/price-list-list/price-list-list.tsx` | ソース | ページコンポーネント |
| price-list-list-table.tsx | `packages/admin/dashboard/src/routes/price-lists/price-list-list/components/price-list-list-table/price-list-list-table.tsx` | ソース | テーブルコンポーネント |
| use-pricing-table-query.tsx | `packages/admin/dashboard/src/routes/price-lists/price-list-list/components/price-list-list-table/use-pricing-table-query.tsx` | ソース | クエリパラメータ処理 |
| use-pricing-table-columns.tsx | `packages/admin/dashboard/src/routes/price-lists/price-list-list/components/price-list-list-table/use-pricing-table-columns.tsx` | ソース | テーブル列定義 |
| use-pricing-table-filters.tsx | `packages/admin/dashboard/src/routes/price-lists/price-list-list/components/price-list-list-table/use-pricing-table-filters.tsx` | ソース | フィルタ定義 |
| price-list-list-table-actions.tsx | `packages/admin/dashboard/src/routes/price-lists/price-list-list/components/price-list-list-table/price-list-list-table-actions.tsx` | ソース | 行アクションメニュー |
| price-count-cell.tsx | `packages/admin/dashboard/src/routes/price-lists/price-list-list/components/price-list-list-table/price-count-cell.tsx` | ソース | 価格数表示セル |
| price-lists.tsx | `packages/admin/dashboard/src/hooks/api/price-lists.tsx` | ソース | API呼び出しフック |
| use-delete-price-list-action.tsx | `packages/admin/dashboard/src/routes/price-lists/common/hooks/use-delete-price-list-action.tsx` | ソース | 削除アクションフック |
| constants.ts | `packages/admin/dashboard/src/routes/price-lists/common/constants.ts` | ソース | 定数定義 |
| utils.ts | `packages/admin/dashboard/src/routes/price-lists/common/utils.ts` | ソース | ユーティリティ関数 |
