# 画面設計書 73-価格表詳細画面

## 概要

本ドキュメントは、Medusa Admin Dashboardにおける「価格表詳細画面」の画面設計書です。特定の価格表（Price List）の詳細情報を表示し、編集・削除・商品管理を行うための画面について記述します。

### 本画面の処理概要

この画面では、選択された価格表の詳細情報を2カラムレイアウトで表示します。メインエリアには基本情報と関連商品一覧が、サイドバーには設定情報が表示されます。

**業務上の目的・背景**：価格表の詳細画面は、作成済みの価格表の内容を確認し、必要に応じて編集・更新を行うための中心的な画面です。価格表に含まれる商品の一覧確認、価格のオーバーライド数の確認、有効期間の確認など、価格表の運用状況を把握するために使用されます。

**画面へのアクセス方法**：価格表一覧画面の行クリック、またはURL `/price-lists/{id}` に直接アクセスすることで表示されます。

**主要な操作・処理内容**：
1. 価格表の基本情報（タイトル、タイプ、説明、ステータス）の表示
2. 価格オーバーライド数の表示
3. 設定情報（有効期間、顧客グループ）の表示
4. 関連商品一覧の表示と検索・フィルタリング
5. 商品の追加・価格編集・削除
6. 価格表自体の編集・削除

**画面遷移**：
- 遷移元：価格表一覧画面
- 遷移先：価格表編集画面（edit）、価格表設定画面（configuration）、商品追加画面（products/add）、価格編集画面（products/edit）、商品詳細画面

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

## 関連機能

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

## 画面種別

詳細画面（TwoColumnPage）

## URL/ルーティング

`/price-lists/:id`

## 入出力項目

### パスパラメータ（入力）

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| id | string | Yes | 価格表のID |

## 表示項目

### 画面レイアウト

```
+------------------------------------------+
| General Section                     [edit]|
| ----------------------------------------- |
| Title: {price_list.title}    [Status]    |
| Type: {type label}                        |
| Description: {description}               |
| Price Overrides: {count}                 |
+------------------------------------------+

+------------------------------------------+
| Products Section              [add][edit]|
| ----------------------------------------- |
| [Search] [Filter] [Sort]                 |
| +-------+--------+--------+--------+     |
| | Title | Status | Prices | Actions|     |
| +-------+--------+--------+--------+     |
| | ...   | ...    | ...    | ...    |     |
| +-------+--------+--------+--------+     |
| [Pagination]                             |
+------------------------------------------+

サイドバー:
+------------------------------------------+
| Configuration Section             [edit] |
| ----------------------------------------- |
| Customer Groups: {group names}           |
| Start Date: {starts_at}                  |
| End Date: {ends_at}                      |
+------------------------------------------+
```

### General Section（基本情報）

| 項目名 | データ型 | 説明 |
|--------|---------|------|
| Title | string | 価格表のタイトル（ヘッダー表示） |
| Status | StatusBadge | ステータス（active/draft/scheduled/expired） |
| Type | string | タイプ（Sale/Override） |
| Description | string | 説明文 |
| Price Overrides | number | 価格オーバーライドの件数 |

### Products Section（商品一覧）

| 列名 | データ型 | 説明 |
|------|---------|------|
| Checkbox | boolean | 行選択チェックボックス |
| Title | string | 商品名 |
| Status | string | 商品ステータス |
| Variants | number | バリアント数 |
| Actions | ActionMenu | 編集・削除アクション |

### Configuration Section（設定情報）

| 項目名 | データ型 | 説明 |
|--------|---------|------|
| Customer Groups | array | 適用対象の顧客グループ名一覧 |
| Start Date | Date | 有効開始日時 |
| End Date | Date | 有効終了日時 |

## イベント仕様

### 1-基本情報編集ボタン押下

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

### 2-価格表削除

General Sectionのアクションメニューから「Delete」を選択すると、確認ダイアログが表示されます。確認後、価格表が削除され、一覧画面に遷移します。

### 3-設定編集ボタン押下

Configuration Sectionの編集アイコンをクリックすると、設定編集画面（`/price-lists/{id}/configuration`）に遷移します。

### 4-商品追加ボタン押下

Products Sectionのアクションメニューから「Add Products」を選択すると、商品追加画面（`/price-lists/{id}/products/add`）に遷移します。

### 5-価格編集ボタン押下

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

### 6-商品行クリック

商品一覧の行をクリックすると、該当商品の詳細画面（`/products/{product_id}`）に遷移します。

### 7-商品削除

商品行のアクションメニューから「Remove」を選択、または選択した商品を一括削除すると、確認ダイアログが表示されます。確認後、価格表から商品が削除されます。

### 8-商品検索・フィルタ

検索フィールドに入力すると、商品名で絞り込みが行われます。フィルタオプションで追加の絞り込みが可能です。

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面表示 | price_list | SELECT | 価格表詳細の取得 |
| 画面表示 | price | SELECT | 価格オーバーライド数の取得 |
| 画面表示 | product | SELECT | 関連商品一覧の取得 |
| 価格表削除 | price_list | DELETE | 価格表の削除 |
| 商品削除 | price_list_product | DELETE | 商品リンクの削除 |

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

#### price_list_product（商品削除時）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| DELETE | price_list_id | 現在の価格表ID | |
| DELETE | product_id | 選択した商品ID | 複数指定可能 |

## メッセージ仕様

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

## 例外処理

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

## 備考

- TwoColumnPageレイアウトを使用（メイン2セクション、サイドバー1セクション）
- showJSON=trueでJSONビューワーを表示
- ウィジェット拡張ポイント（before/after/sideBefore/sideAfter）あり
- 商品テーブルのページサイズは10件

---

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

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

### 推奨読解順序

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

ページコンポーネントの構成とデータ取得処理を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | price-list-detail.tsx | `packages/admin/dashboard/src/routes/price-lists/price-list-detail/price-list-detail.tsx` | TwoColumnPage構成、usePriceListでのデータ取得 |

**主要処理フロー**:
1. **13行目**: useParamsでURLからid取得
2. **15行目**: usePriceListで価格表データ取得
3. **16行目**: useExtensionでウィジェット取得
4. **28-46行目**: TwoColumnPageでレイアウト構成

#### Step 2: General Sectionを理解する

基本情報表示セクションを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | price-list-general-section.tsx | `packages/admin/dashboard/src/routes/price-lists/price-list-detail/components/price-list-general-section/price-list-general-section.tsx` | 基本情報表示、ステータス計算、アクションメニュー |

**主要処理フロー**:
- **19-25行目**: usePriceListPricesで価格オーバーライド数を取得
- **27行目**: getPriceListStatusでステータス表示を計算
- **29行目**: useDeletePriceListActionで削除処理
- **42-63行目**: ActionMenuで編集・削除アクション

#### Step 3: Configuration Sectionを理解する

設定情報表示セクションを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | price-list-configuration-section.tsx | `packages/admin/dashboard/src/routes/price-lists/price-list-detail/components/price-list-configuration-section/price-list-configuration-section.tsx` | 設定情報表示、顧客グループ表示 |

**主要処理フロー**:
- **58-69行目**: rulesから顧客グループIDを抽出し、useCustomerGroupsで名前を取得
- **42-46行目**: DateRangeDisplayで有効期間を表示

#### Step 4: Products Sectionを理解する

商品一覧セクションを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | price-list-product-section.tsx | `packages/admin/dashboard/src/routes/price-lists/price-list-detail/components/price-list-product-section/price-list-product-section.tsx` | 商品一覧表示、行選択、削除処理 |

**主要処理フロー**:
- **35-47行目**: useProductsで商品一覧取得（price_list_idでフィルタ）
- **51行目**: usePriceListLinkProductsで商品リンク管理
- **68-101行目**: handleDeleteで商品削除処理
- **136-166行目**: _DataTableでテーブル表示

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

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

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

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

```
PriceListDetails (price-list-detail.tsx)
    │
    ├─ usePriceList() - 価格表詳細取得
    │
    ├─ useExtension() - ウィジェット取得
    │
    └─ TwoColumnPage
           │
           ├─ Main
           │    │
           │    ├─ PriceListGeneralSection
           │    │      │
           │    │      ├─ usePriceListPrices() - 価格オーバーライド数取得
           │    │      │
           │    │      ├─ getPriceListStatus() - ステータス計算
           │    │      │
           │    │      ├─ useDeletePriceListAction()
           │    │      │      └─ useDeletePriceList()
           │    │      │
           │    │      └─ ActionMenu (Edit/Delete)
           │    │
           │    └─ PriceListProductSection
           │           │
           │           ├─ useProductTableQuery() - クエリパラメータ
           │           │
           │           ├─ useProducts() - 商品一覧取得
           │           │
           │           ├─ usePriceListLinkProducts() - 商品リンク管理
           │           │
           │           ├─ useDataTable() - テーブル状態
           │           │
           │           └─ _DataTable
           │                  └─ ProductRowAction
           │                         └─ handleDelete()
           │
           └─ Sidebar
                └─ PriceListConfigurationSection
                       │
                       ├─ useCustomerGroups() - 顧客グループ取得
                       │
                       ├─ CustomerGroupDisplay
                       │
                       └─ DateRangeDisplay
```

### データフロー図

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

URL param (id) ──────▶ usePriceList() ──────▶ price_list

price_list.id ──────▶ usePriceListPrices() ──────▶ overrideCount

price_list.rules ──────▶ useCustomerGroups() ──────▶ customer_groups

price_list.id ──────▶ useProducts() ──────▶ products
                       (price_list_id filter)

削除アクション ──────▶ usePriceListLinkProducts()
                       │
                       └─▶ mutateAsync({ remove: productIds })
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| price-list-detail.tsx | `packages/admin/dashboard/src/routes/price-lists/price-list-detail/price-list-detail.tsx` | ソース | ページコンポーネント |
| price-list-general-section.tsx | `packages/admin/dashboard/src/routes/price-lists/price-list-detail/components/price-list-general-section/price-list-general-section.tsx` | ソース | 基本情報セクション |
| price-list-configuration-section.tsx | `packages/admin/dashboard/src/routes/price-lists/price-list-detail/components/price-list-configuration-section/price-list-configuration-section.tsx` | ソース | 設定情報セクション |
| price-list-product-section.tsx | `packages/admin/dashboard/src/routes/price-lists/price-list-detail/components/price-list-product-section/price-list-product-section.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` | ソース | 削除アクションフック |
| utils.ts | `packages/admin/dashboard/src/routes/price-lists/common/utils.ts` | ソース | ステータス計算ユーティリティ |
