# 画面設計書 35-コレクション一覧画面

## 概要

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

### 本画面の処理概要

商品コレクションの一覧を表示し、検索・フィルタ・並び替えを行う画面です。コレクションの作成画面への遷移や、各コレクションの詳細画面への遷移が可能です。

**業務上の目的・背景**：ECサイトにおけるコレクションは、商品をテーマやシーズン、プロモーションなどで柔軟にグルーピングするための機能です。「夏のセール」「新着商品」「ベストセラー」など、カテゴリとは異なる軸で商品を管理・表示できます。一覧画面では登録されているコレクションを把握し、必要に応じて編集・削除を行うことで、マーケティング施策や商品展開の管理を効率的に行えます。

**画面へのアクセス方法**：メインメニューの「コレクション」をクリック、またはURL直接アクセスで表示されます。

**主要な操作・処理内容**：
1. コレクション一覧の表示 - ページネーション付きで表示（20件/ページ）
2. コレクションの検索 - タイトルでの検索
3. コレクションのフィルタリング - 各種条件でのフィルタ
4. コレクションのソート - タイトル、ハンドル、作成日、更新日
5. コレクション作成 - 「作成」ボタンで新規作成画面へ遷移
6. コレクション詳細 - 行クリックで詳細画面へ遷移
7. コレクション削除 - 行アクションメニューから削除

**画面遷移**：メインメニューから遷移してきます。「作成」ボタンでコレクション作成画面へ、行クリックでコレクション詳細画面へ遷移します。

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 5 | 商品コレクション管理 | 主機能 | コレクション一覧の取得・表示 |

## 画面種別

一覧

## URL/ルーティング

`/collections`

## 入出力項目

| 項目名 | 項目ID | 型 | 必須 | 最大長 | 入力/出力 | 説明 |
|--------|--------|-----|------|--------|-----------|------|
| 検索クエリ | q | string | 任意 | - | 入力 | コレクションタイトルでの検索 |
| ページ番号 | offset | number | 任意 | - | 入力 | ページネーション用オフセット |
| ソートキー | order | string | 任意 | - | 入力 | ソート対象（title, handle, created_at, updated_at） |
| フィルター | - | various | 任意 | - | 入力 | useCollectionTableFiltersで定義されたフィルター |

## 表示項目

| 項目名 | 表示形式 | 説明 |
|--------|----------|------|
| ヘッダータイトル | Heading | "Collections"（i18n: collections.domain） |
| サブタイトル | Text | コレクションの説明（i18n: collections.subtitle） |
| 作成ボタン | Button | "Create"（i18n: actions.create） |
| コレクションテーブル | DataTable | コレクション一覧 |
| 検索ボックス | Input | 検索入力フィールド |
| フィルター | Filter | フィルター条件 |
| ソートオプション | Select | タイトル、ハンドル、作成日、更新日 |
| ページネーション | Pagination | 20件/ページ |
| 行アクション | ActionMenu | 編集、削除 |

## イベント仕様

### 1-作成ボタン押下

コレクション作成画面へ遷移します。

**処理フロー**:
1. react-router-domのLinkコンポーネントで `/collections/create` へ遷移

### 2-コレクション行クリック

選択したコレクションの詳細画面へ遷移します。

**処理フロー**:
1. navigateToプロパティで `/collections/:id` へ遷移
2. row.original.id からコレクションIDを取得

### 3-行削除アクション

行のアクションメニューから「削除」を選択すると、確認後にコレクションを削除します。

**処理フロー**:
1. 確認ダイアログを表示
2. 確認された場合、useDeleteCollectionでAPI呼び出し
3. 成功時: 一覧を更新
4. 失敗時: エラーメッセージを表示

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

### 4-検索

検索ボックスに入力すると、コレクションタイトルでフィルタリングされます。

### 5-ソート

ソートオプションを変更すると、指定されたキーで並び替えられます。

### 6-ページネーション

ページを切り替えると、次のページのコレクションが読み込まれます。

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 行削除アクション | product_collection | DELETE | コレクションを削除 |

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

#### product_collection

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | * | - | コレクション一覧取得 |
| DELETE | - | id = 選択されたコレクションID | コレクション削除 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示タイミング |
|------------|------|--------------|--------------|
| general.areYouSure | 確認 | 本当によろしいですか？ | 削除確認ダイアログ |
| collections.deleteWarning | 確認 | このコレクションを削除しますか？ | 削除確認ダイアログ |

## 例外処理

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

## 備考

- SingleColumnPageレイアウトを使用
- 拡張機能ウィジェット（product_collection.list.before/after）をサポート
- 1ページあたり20件の表示（PAGE_SIZE = 20）
- useCollectionsフックでデータ取得
- keepPreviousDataでページネーション時のチラつきを防止
- useCollectionTableColumnsで標準カラムを使用
- 行アクションはCollectionRowActionsコンポーネントで定義

---

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

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

### 推奨読解順序

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

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

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

**読解のコツ**: @medusajs/typesパッケージのHttpTypes.AdminCollectionで定義された型を参照します。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | collection-list.tsx | `packages/admin/dashboard/src/routes/collections/collection-list/collection-list.tsx` | SingleColumnPageでレイアウト、CollectionListTableを子コンポーネントとして配置 |

**主要処理フロー**:
1. **6行目**: useExtensionでウィジェット取得関数を取得
2. **9-16行目**: SingleColumnPageにウィジェット設定を渡す
3. **15行目**: CollectionListTableコンポーネントを配置

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

コレクション一覧テーブルの実装を把握します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | collection-list-table.tsx | `packages/admin/dashboard/src/routes/collections/collection-list/components/collection-list-table/collection-list-table.tsx` | useCollectionsでデータ取得、useDataTableでテーブル制御、_DataTableで表示 |

**主要処理フロー**:
- **17行目**: PAGE_SIZE = 20を定義
- **21行目**: useCollectionTableQueryでクエリパラメータ管理
- **22-30行目**: useCollectionsでコレクション一覧取得（+products.idで商品数も取得）
- **32行目**: useCollectionTableFiltersでフィルター定義
- **33行目**: useColumnsでカラム定義
- **35-42行目**: useDataTableでテーブル設定（ページネーション、行ID）
- **57行目**: Linkで作成画面への遷移
- **63-79行目**: _DataTableにテーブル設定を渡す

#### Step 4: 行アクションを理解する

各行の操作メニューの実装を把握します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | collection-row-actions.tsx | `packages/admin/dashboard/src/routes/collections/collection-list/components/collection-list-table/collection-row-actions.tsx` | 編集リンク、削除処理の実装を確認 |

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

```
CollectionList (collection-list.tsx)
    │
    ├─ useExtension() → ウィジェット取得
    │
    └─ SingleColumnPage
           │
           ├─ Widgets (product_collection.list.before)
           │
           ├─ CollectionListTable (collection-list-table.tsx)
           │      │
           │      ├─ useCollectionTableQuery() → クエリパラメータ管理
           │      │
           │      ├─ useCollections() → コレクション一覧取得
           │      │      └─ sdk.admin.productCollection.list()
           │      │
           │      ├─ useCollectionTableFilters() → フィルター定義
           │      │
           │      ├─ useColumns() → カラム定義
           │      │      ├─ useCollectionTableColumns() → 標準カラム
           │      │      └─ CollectionRowActions → 行アクション
           │      │
           │      ├─ useDataTable() → テーブル制御
           │      │
           │      └─ _DataTable → テーブル表示
           │
           └─ Widgets (product_collection.list.after)
```

### データフロー図

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

URLパラメータ ─────────▶ useCollectionTableQuery ───▶ 検索パラメータ
                              │
                              ▼
検索/フィルター ─────────▶ useCollections ───▶ コレクション一覧
                              │
                              ▼
                        useDataTable ───▶ テーブル状態管理
                              │
                              ▼
                        _DataTable ───▶ UI表示
                              │
                              ▼
行クリック ────────────────────────────────▶ 詳細画面へ遷移
                              │
                              ▼
削除アクション ───────────▶ useDeleteCollection ───▶ コレクション削除
                              │
                              ▼
                        クエリキャッシュ無効化 ───▶ 一覧更新
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| collection-list.tsx | `packages/admin/dashboard/src/routes/collections/collection-list/collection-list.tsx` | ソース | ルートコンポーネント |
| collection-list-table.tsx | `packages/admin/dashboard/src/routes/collections/collection-list/components/collection-list-table/collection-list-table.tsx` | ソース | テーブルコンポーネント |
| collection-row-actions.tsx | `packages/admin/dashboard/src/routes/collections/collection-list/components/collection-list-table/collection-row-actions.tsx` | ソース | 行アクションコンポーネント |
| index.ts | `packages/admin/dashboard/src/routes/collections/collection-list/index.ts` | ソース | エクスポート定義 |
| collections.tsx | `packages/admin/dashboard/src/hooks/api/collections.tsx` | ソース | コレクションAPI フック |
| SingleColumnPage | `packages/admin/dashboard/src/components/layout/pages/` | ソース | ページレイアウト |
| _DataTable | `packages/admin/dashboard/src/components/table/data-table/` | ソース | データテーブルコンポーネント |
| use-collection-table-columns.tsx | `packages/admin/dashboard/src/hooks/table/columns/` | ソース | コレクションテーブルカラム |
| use-collection-table-filters.tsx | `packages/admin/dashboard/src/hooks/table/filters/` | ソース | コレクションテーブルフィルター |
| use-collection-table-query.tsx | `packages/admin/dashboard/src/hooks/table/query/` | ソース | コレクションテーブルクエリ |
