# 画面設計書 37-コレクション詳細画面

## 概要

本ドキュメントは、Medusa Admin Dashboard におけるコレクション詳細画面の設計を記述したものです。

### 本画面の処理概要

商品コレクションの詳細情報を表示し、編集・削除・商品管理を行う画面です。コレクションの基本情報と、紐付けられた商品の一覧を確認・管理できます。

**業務上の目的・背景**：ECサイト運営において、作成したコレクションの内容を確認し、必要に応じて編集や商品の追加・削除を行う必要があります。この画面では、コレクションのタイトル・ハンドルなどの基本情報と、所属する商品の一覧を一元的に管理できます。商品の追加・削除をスムーズに行うことで、プロモーションや季節に応じた商品展開を迅速に実行できます。

**画面へのアクセス方法**：コレクション一覧画面でコレクション行をクリック、またはURL直接アクセスで表示されます。

**主要な操作・処理内容**：
1. コレクション基本情報の表示 - タイトル、ハンドル
2. コレクションの編集 - 編集画面への遷移
3. コレクションの削除 - 確認後に削除
4. 商品一覧の表示 - コレクション内商品をテーブル表示
5. 商品の追加 - 商品追加画面への遷移
6. 商品の削除 - 選択した商品をコレクションから削除
7. メタデータの表示 - JSONビューアーでメタデータ表示
8. 翻訳管理（有効な場合） - 翻訳編集画面への遷移

**画面遷移**：コレクション一覧画面から遷移してきます。編集ボタンで編集画面へ、商品追加ボタンで商品追加画面へ、商品行クリックで商品詳細画面へ遷移します。

**権限による表示制御**：管理者権限を持つユーザーのみがアクセスできます。認証されていないユーザーはログイン画面にリダイレクトされます。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 5 | 商品コレクション管理 | 主機能 | コレクション詳細情報の表示 |
| 1 | 商品CRUD | 補助機能 | コレクション内商品の表示 |

## 画面種別

詳細

## URL/ルーティング

`/collections/:id`

## 入出力項目

| 項目名 | 項目ID | 型 | 必須 | 最大長 | 入力/出力 | 説明 |
|--------|--------|-----|------|--------|-----------|------|
| コレクションID | id | string | - | - | 入力(URL) | 表示対象のコレクションID |

## 表示項目

| 項目名 | 表示形式 | 説明 |
|--------|----------|------|
| コレクションタイトル | Heading | コレクションのタイトル |
| ハンドル | Text | /{handle}形式で表示 |
| アクションメニュー | ActionMenu | 編集、翻訳管理、削除 |
| 商品セクション | Container | 商品一覧 |
| 商品テーブル | DataTable | コレクション内商品一覧（10件/ページ） |
| 商品追加ボタン | ActionMenu | 商品追加画面への遷移 |
| メタデータ | JSONビューア | メタデータの表示 |

## イベント仕様

### 1-編集ボタン押下

コレクション編集画面へ遷移します。

**処理フロー**:
1. ActionMenuから「Edit」を選択
2. `/collections/:id/edit` へ遷移

### 2-削除ボタン押下

確認ダイアログを表示し、承認後にコレクションを削除します。

**処理フロー**:
1. ActionMenuから「Delete」を選択
2. usePromptで確認ダイアログを表示
3. 確認された場合、useDeleteCollectionでAPI呼び出し
4. 成功時: コレクション一覧画面へ遷移
5. 失敗時: エラーメッセージを表示

**API呼び出し**:
- エンドポイント: `DELETE /admin/collections/:id`

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

商品追加画面へ遷移します。

**処理フロー**:
1. 商品セクションのActionMenuから「Add」を選択
2. `/collections/:id/products` へ遷移（相対パス "products"）

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

選択した商品の詳細画面へ遷移します。

**処理フロー**:
1. navigateToプロパティで `/products/:id` へ遷移

### 5-商品削除（複数選択）

選択した商品をコレクションから削除します。

**処理フロー**:
1. 確認ダイアログを表示
2. 確認された場合、useUpdateCollectionProductsで{ remove: ids }をAPI送信
3. 成功時: トースト通知を表示
4. 失敗時: エラーメッセージをトーストで表示

**API呼び出し**:
- エンドポイント: `POST /admin/collections/:id/products`
- リクエストボディ:
  ```json
  {
    "remove": ["prod_xxx", "prod_yyy"]
  }
  ```

### 6-商品削除（個別）

商品行のアクションメニューから削除を選択すると、その商品をコレクションから削除します。

### 7-翻訳管理（有効な場合）

翻訳機能が有効な場合、ActionMenuに翻訳管理オプションが表示されます。

**処理フロー**:
1. ActionMenuから「Manage Translations」を選択
2. `/settings/translations/edit?reference=product_collection&reference_id=:id` へ遷移

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| コレクション削除 | product_collection | DELETE | コレクションを削除 |
| 商品削除 | product_collection_product | DELETE | コレクションと商品の紐付けを削除 |

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

#### product_collection

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | * | id = URLパラメータ | コレクション詳細取得 |
| DELETE | - | id = URLパラメータ | コレクション削除 |

#### product_collection_product（中間テーブル）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| DELETE | - | collection_id, product_id | 商品の紐付け解除 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示タイミング |
|------------|------|--------------|--------------|
| general.areYouSure | 確認 | 本当によろしいですか？ | 削除確認ダイアログ |
| collections.deleteWarning | 確認 | このコレクションを削除しますか？ | コレクション削除確認 |
| collections.removeProductsWarning | 確認 | 選択した商品を削除しますか？ | 複数商品削除確認 |
| collections.removeSingleProductWarning | 確認 | この商品を削除しますか？ | 個別商品削除確認 |
| collections.products.remove.successToast | 成功 | 商品を削除しました | 商品削除成功時 |
| collections.products.list.noRecordsMessage | 情報 | 商品がありません | 商品が0件の場合 |

## 例外処理

| 例外状況 | 処理内容 |
|---------|---------|
| コレクションが見つからない | エラーをスローし、エラーバウンダリで処理 |
| データ取得エラー | エラーをスローし、エラーバウンダリで処理 |
| 削除失敗 | トーストでエラーメッセージを表示 |
| 認証エラー | ログイン画面にリダイレクト |

## 備考

- SingleColumnPageレイアウトを使用
- 拡張機能ウィジェット（product_collection.details.before/after）をサポート
- ローダーを使用して初期データをプリフェッチ（collectionLoader）
- showJSON、showMetadataオプションでJSON/メタデータビューアーを表示
- 商品テーブルは10件/ページ（PAGE_SIZE = 10）
- コレクション削除後は一覧画面へ相対遷移（"../"）
- 翻訳機能はuseFeatureFlagで制御

---

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

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

### 推奨読解順序

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

コレクションのデータ型を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | collections.tsx | `packages/admin/dashboard/src/hooks/api/collections.tsx` | useCollection（21-40行目）のレスポンス型（HttpTypes.AdminCollection）を確認 |

**読解のコツ**: collection.title, collection.handle, collection.productsなどのプロパティを把握します。

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

ルートコンポーネントから画面がどのように構成されるかを理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | collection-detail.tsx | `packages/admin/dashboard/src/routes/collections/collection-detail/collection-detail.tsx` | useLoaderDataでプリフェッチ、useCollectionでデータ取得、SingleColumnPageでレイアウト |

**主要処理フロー**:
1. **12-14行目**: useLoaderDataでプリフェッチされたデータを取得
2. **16-18行目**: useParamsでID取得、useCollectionでデータフェッチ
3. **21行目**: useExtensionでウィジェット取得関数を取得
4. **23-25行目**: ローディング中はスケルトン表示
5. **32-44行目**: SingleColumnPageに各セクションを配置

#### Step 3: 基本情報セクションを理解する

コレクションの基本情報表示と操作を把握します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | collection-general-section.tsx | `packages/admin/dashboard/src/routes/collections/collection-detail/components/collection-general-section/collection-general-section.tsx` | タイトル表示、ActionMenu（編集、翻訳、削除）、削除処理の実装 |

**主要処理フロー**:
- **22行目**: useDeleteCollectionでミューテーションフック取得
- **24-39行目**: handleDeleteで確認ダイアログ→API呼び出し→遷移
- **45-81行目**: ActionMenuで編集、翻訳管理、削除アクションを定義

#### Step 4: 商品セクションを理解する

コレクション内商品の表示と管理を把握します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | collection-product-section.tsx | `packages/admin/dashboard/src/routes/collections/collection-detail/components/collection-product-section/collection-product-section.tsx` | 商品テーブル、追加ボタン、削除処理の実装 |

**主要処理フロー**:
- **27-38行目**: useProductsでコレクション内商品を取得（collection_id: [collection.id]）
- **58行目**: useUpdateCollectionProductsでミューテーションフック取得
- **60-93行目**: handleRemoveで複数商品の削除処理
- **103-116行目**: ActionMenuで商品追加アクションを定義
- **133-140行目**: commandsで一括削除コマンドを定義

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

```
CollectionDetail (collection-detail.tsx)
    │
    ├─ useLoaderData() → プリフェッチデータ取得
    │
    ├─ useCollection(id) → コレクション詳細取得
    │      └─ sdk.admin.productCollection.retrieve()
    │
    ├─ useExtension() → ウィジェット取得
    │
    └─ SingleColumnPage
           │
           ├─ Widgets (product_collection.details.before)
           │
           ├─ CollectionGeneralSection
           │      │
           │      ├─ useDeleteCollection() → 削除ミューテーション
           │      │      └─ sdk.admin.productCollection.delete()
           │      │
           │      └─ ActionMenu → 編集、翻訳管理、削除
           │
           ├─ CollectionProductSection
           │      │
           │      ├─ useProducts() → 商品一覧取得
           │      │      └─ sdk.admin.product.list()
           │      │
           │      ├─ useUpdateCollectionProducts() → 商品削除
           │      │      └─ sdk.admin.productCollection.updateProducts()
           │      │
           │      ├─ useDataTable() → テーブル制御
           │      │
           │      └─ _DataTable → 商品一覧表示
           │
           └─ Widgets (product_collection.details.after)
```

### データフロー図

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

URLパラメータ(:id) ───▶ collectionLoader ───▶ プリフェッチ
                              │
                              ▼
                        useCollection ───▶ コレクション詳細表示
                              │
                              ▼
                        useProducts ───▶ 商品一覧表示
                        (collection_id)
                              │
                              ▼
編集アクション ────────▶ 編集画面へ遷移 (/collections/:id/edit)
                              │
削除アクション ────────▶ useDeleteCollection ───▶ 一覧画面へ遷移
                              │
商品追加 ──────────────▶ 商品追加画面へ遷移 (/collections/:id/products)
                              │
商品削除 ──────────────▶ useUpdateCollectionProducts ───▶ 商品一覧更新
                        (remove: ids)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| collection-detail.tsx | `packages/admin/dashboard/src/routes/collections/collection-detail/collection-detail.tsx` | ソース | ルートコンポーネント |
| collection-general-section.tsx | `packages/admin/dashboard/src/routes/collections/collection-detail/components/collection-general-section/collection-general-section.tsx` | ソース | 基本情報セクション |
| collection-product-section.tsx | `packages/admin/dashboard/src/routes/collections/collection-detail/components/collection-product-section/collection-product-section.tsx` | ソース | 商品セクション |
| loader.ts | `packages/admin/dashboard/src/routes/collections/collection-detail/loader.ts` | ソース | ローダー |
| breadcrumb.tsx | `packages/admin/dashboard/src/routes/collections/collection-detail/breadcrumb.tsx` | ソース | パンくずリスト |
| index.ts | `packages/admin/dashboard/src/routes/collections/collection-detail/index.ts` | ソース | エクスポート定義 |
| collections.tsx | `packages/admin/dashboard/src/hooks/api/collections.tsx` | ソース | コレクションAPI フック |
| products.tsx | `packages/admin/dashboard/src/hooks/api/products.tsx` | ソース | 商品API フック |
| SingleColumnPage | `packages/admin/dashboard/src/components/layout/pages/` | ソース | ページレイアウト |
| _DataTable | `packages/admin/dashboard/src/components/table/data-table/` | ソース | データテーブル |
| ActionMenu | `packages/admin/dashboard/src/components/common/action-menu/` | ソース | アクションメニュー |
