# 画面設計書 9-一覧画面

## 概要

本ドキュメントは、Payload CMSの管理画面における一覧画面の設計について記載する。コレクションのドキュメント一覧を表示し、検索・フィルタ・ソート・ページネーション・グループ化などの機能を提供する画面である。

### 本画面の処理概要

本画面は、特定のコレクションに属するドキュメントの一覧をテーブル形式で表示する画面である。検索、フィルタリング、ソート、ページネーション、グループ化、一括操作などの高度な機能を提供し、効率的なコンテンツ管理を支援する。

**業務上の目的・背景**：コレクション内のドキュメントを効率的に管理・操作するためのインターフェースを提供する。大量のドキュメントを扱う場合でも、検索・フィルタ・ソート機能により素早く目的のドキュメントを見つけることができる。一括編集・一括削除機能により、複数ドキュメントへの操作を効率化する。Query Presets機能により、よく使うフィルタ条件を保存・再利用できる。

**画面へのアクセス方法**：ダッシュボードのコレクションカードをクリックする。またはサイドナビゲーションからコレクションを選択する。URLパターンは `/admin/collections/{collectionSlug}` となる。

**主要な操作・処理内容**：
1. ドキュメント一覧をテーブル形式で表示
2. 検索バーでテキスト検索を実行
3. フィルターでドキュメントを絞り込み
4. 列ヘッダーをクリックしてソート
5. ページネーションでページ切り替え
6. グループ化機能でドキュメントをグループ表示
7. 行選択と一括操作（編集・削除）
8. 新規作成ボタンでドキュメント作成画面へ遷移
9. 行クリックでドキュメント編集画面へ遷移

**画面遷移**：
- 遷移元：ダッシュボード画面、サイドナビゲーション
- 遷移先：ドキュメント編集画面（新規作成/編集）、ゴミ箱画面、フォルダ表示画面

**権限による表示制御**：ユーザーの権限に基づいて、作成・編集・削除ボタンの表示が制御される。フィールドレベルの権限により、表示される列も制限される。コレクションへのreadアクセスがない場合は404エラーとなる。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | コレクション管理 | 主機能 | コレクションドキュメントの一覧取得・表示 |
| 30 | Admin UI | 補助機能 | テーブル、フィルター、ページネーションUIの表示 |
| 11 | REST API | API連携 | ドキュメント一覧のフェッチ処理 |
| 63 | アクセス制御 | API連携 | コレクション・ドキュメントレベルの権限チェック |
| 61 | プリファレンス | API連携 | 列表示設定、ソート設定の保存・読込 |

## 画面種別

一覧

## URL/ルーティング

- **URL**: `/admin/collections/{collectionSlug}`
- **ルーティング定義**: `packages/next/src/routes/collections/list`
- **クエリパラメータ**:
  - `page` - ページ番号
  - `limit` - 1ページあたりの件数
  - `sort` - ソート列
  - `search` - 検索文字列
  - `where` - フィルタ条件（JSON）
  - `columns` - 表示列（JSON）
  - `groupBy` - グループ化フィールド
  - `preset` - Query Preset ID

## 入出力項目

| 項目名 | 項目ID | 入出力区分 | データ型 | 必須 | 最大長 | 説明 |
|--------|--------|------------|----------|------|--------|------|
| 検索文字列 | search | 入力 | string | 任意 | - | 全文検索クエリ |
| フィルタ条件 | where | 入力 | object | 任意 | - | フィルタ条件オブジェクト |
| ページ番号 | page | 入力 | number | 任意 | - | 現在のページ番号 |
| 件数制限 | limit | 入力 | number | 任意 | - | 1ページあたりの件数 |
| ソート | sort | 入力 | string | 任意 | - | ソート列と方向 |
| 表示列 | columns | 入力 | array | 任意 | - | 表示する列の配列 |
| グループ化 | groupBy | 入力 | string | 任意 | - | グループ化フィールド |
| プリセット | preset | 入力 | string | 任意 | - | Query Preset ID |

## 表示項目

| 項目名 | 表示位置 | データソース | 説明 |
|--------|----------|--------------|------|
| コレクション名 | ヘッダー | collectionConfig.labels | コレクションの表示名 |
| 説明文 | ヘッダー下 | collectionConfig.admin.description | コレクションの説明 |
| 検索バー | ツールバー | - | テキスト検索入力 |
| フィルターボタン | ツールバー | - | フィルター条件設定 |
| 列設定ボタン | ツールバー | - | 表示列のカスタマイズ |
| 新規作成ボタン | ツールバー | - | 新規ドキュメント作成へ |
| テーブル | メインエリア | data.docs | ドキュメント一覧 |
| ページネーション | フッター | data | ページ切り替え |
| 一括操作メニュー | ツールバー | - | 選択行への一括操作 |

## イベント仕様

### 1-検索実行

- **トリガー**: 検索バーで入力後Enter押下またはデバウンス後
- **処理内容**:
  1. searchパラメータを更新
  2. ページを1にリセット
  3. 一覧を再取得
- **結果**: フィルタされた一覧を表示

### 2-フィルター適用

- **トリガー**: フィルター条件を設定してApply
- **処理内容**:
  1. whereパラメータを更新
  2. ページを1にリセット
  3. 一覧を再取得
- **結果**: フィルタされた一覧を表示

### 3-ソート実行

- **トリガー**: 列ヘッダーをクリック
- **処理内容**:
  1. sortパラメータを更新（昇順/降順切り替え）
  2. 一覧を再取得
- **結果**: ソートされた一覧を表示

### 4-ページ切り替え

- **トリガー**: ページネーションコントロール操作
- **処理内容**:
  1. pageパラメータを更新
  2. 一覧を再取得
- **結果**: 指定ページの一覧を表示

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

- **トリガー**: 新規作成ボタン押下
- **処理内容**: ドキュメント編集画面（新規）へ遷移
- **遷移先**: `/admin/collections/{collectionSlug}/create`

### 6-行クリック

- **トリガー**: テーブル行をクリック
- **処理内容**: ドキュメント編集画面へ遷移
- **遷移先**: `/admin/collections/{collectionSlug}/{docId}`

### 7-一括削除

- **トリガー**: 行選択後、一括削除を実行
- **処理内容**:
  1. 確認ダイアログを表示
  2. 選択されたドキュメントを削除
  3. 一覧を再取得
- **結果**: 削除後の一覧を表示

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面表示 | {collectionSlug} | SELECT | ドキュメント一覧取得 |
| 検索・フィルター | {collectionSlug} | SELECT | 条件付きドキュメント取得 |
| 一括削除 | {collectionSlug} | DELETE | 選択ドキュメント削除 |
| プリファレンス保存 | payload-preferences | UPDATE/INSERT | 列・ソート設定保存 |

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

#### {collectionSlug}

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | * | where条件、search条件、sort条件 | 一覧取得 |
| DELETE | - | 選択されたドキュメントID | 一括削除 |

#### payload-preferences

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE/INSERT | value | columns, sort, limit設定 | ユーザープリファレンス |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|----------|
| - | 情報 | ドキュメントが見つかりませんでした | 検索結果0件時 |
| - | 確認 | 選択したドキュメントを削除しますか？ | 一括削除確認 |
| - | 成功 | ドキュメントを削除しました | 削除成功時 |
| - | エラー | 削除に失敗しました | 削除失敗時 |

## 例外処理

| 例外状況 | 処理内容 |
|----------|---------|
| コレクションが存在しない | 404エラー画面を表示 |
| read権限なし | 404エラー画面を表示 |
| クエリエラー | エラーログを出力、空の一覧を表示 |
| ネットワークエラー | エラーメッセージを表示 |
| ドキュメントが見つからない | notFoundパラメータ付きでリダイレクト |

## 備考

- `enableListViewSelectAPI`設定でSELECTクエリの最適化が可能
- `baseFilter`/`baseListFilter`でデフォルトのフィルタ条件を設定可能
- `orderable`設定でドラッグ&ドロップによる並び替えが可能
- Query Presetsでフィルタ条件を保存・共有可能
- Drawerモードでも一覧表示が可能（リレーションフィールド選択時など）

---

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

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

### 推奨読解順序

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

まず、一覧画面で使用されるデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | PaginatedDocs | `packages/payload/src/types.ts` | ページネーション付きドキュメント一覧の構造 |
| 1-2 | ListQuery | `packages/payload/src/types.ts` | 一覧取得時のクエリ構造 |
| 1-3 | Column | `packages/payload/src/admin/types.ts` | 列定義の構造 |

**読解のコツ**: PaginatedDocsはdocs配列と共に、hasNextPage、hasPrevPage、totalDocs、totalPagesなどのメタ情報を含む。

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

処理の起点となる関数を特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | renderListView | `packages/next/src/views/List/index.tsx` | 一覧レンダリングの中核関数 |

**主要処理フロー**:
1. **行75-112**: 引数からcollectionConfig、permissions、queryを取得
2. **行117-123**: コレクションの存在確認と権限チェック
3. **行125-191**: クエリパラメータの処理とプリファレンス取得
4. **行193-220**: baseFilterとsearch条件のマージ
5. **行258-327**: データ取得（通常またはgroupBy）
6. **行339-344**: フィルターのレンダリング
7. **行404-445**: ListQueryProviderとRenderServerComponentでUI構築

#### Step 3: テーブルレンダリングを理解する

テーブルのレンダリング処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | renderTable | `packages/ui/src/rsc/renderTable.tsx` | テーブルレンダリング |

#### Step 4: 一括操作を理解する

一括編集・削除の処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | BulkActions | `packages/ui/src/elements/BulkActions/index.tsx` | 一括操作UI |

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

```
ListView (Server Component)
    |
    +-- renderListView()
            |
            +-- upsertPreferences()
            |
            +-- getDocumentPermissions()
            |
            +-- [groupByあり]
            |     +-- handleGroupBy()
            |           +-- payload.find() (グループ別)
            |           +-- renderTable() (グループ別)
            |
            +-- [groupByなし]
            |     +-- payload.find()
            |     +-- enrichDocsWithVersionStatus()
            |     +-- renderTable()
            |
            +-- renderFilters()
            |
            +-- resolveAllFilterOptions()
            |
            +-- renderListViewSlots()
            |
            +-- HydrateAuthProvider
            |
            +-- ListQueryProvider
            |
            +-- RenderServerComponent
                  +-- DefaultListView / カスタムコンポーネント
```

### データフロー図

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

URL params --------> renderListView
        |                 |
        v                 v
  searchParams -----> クエリ構築
  collectionSlug          |
                          v
                    payload.find()
                          |
                          v
                    PaginatedDocs
                          |
                          v
                    renderTable()
                          |
                          v
                    Table + columnState
                          |
                          v
                    ListQueryProvider
                          |
                          v
                    DefaultListView
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.tsx | `packages/next/src/views/List/index.tsx` | ソース | サーバーコンポーネント |
| handleGroupBy.ts | `packages/next/src/views/List/handleGroupBy.ts` | ソース | グループ化処理 |
| enrichDocsWithVersionStatus.ts | `packages/next/src/views/List/enrichDocsWithVersionStatus.ts` | ソース | バージョンステータス付与 |
| renderListViewSlots.ts | `packages/next/src/views/List/renderListViewSlots.ts` | ソース | スロットレンダリング |
| resolveAllFilterOptions.ts | `packages/next/src/views/List/resolveAllFilterOptions.ts` | ソース | フィルターオプション解決 |
| DefaultListView | `packages/ui/src/views/List/index.tsx` | ソース | デフォルト一覧UI |
| ListQueryProvider | `packages/ui/src/providers/ListQuery/index.tsx` | ソース | 一覧クエリコンテキスト |
| renderTable.tsx | `packages/ui/src/rsc/renderTable.tsx` | ソース | テーブルレンダリング |
| renderFilters.tsx | `packages/ui/src/rsc/renderFilters.tsx` | ソース | フィルターレンダリング |
