# 画面設計書 11-ゴミ箱画面

## 概要

本ドキュメントは、Payload CMSの管理画面における「ゴミ箱画面」の設計仕様を定義するものである。削除されたドキュメントの一覧表示、復元、完全削除機能を提供する画面である。

### 本画面の処理概要

ゴミ箱画面は、ソフトデリート（論理削除）されたドキュメントを一覧表示し、復元または完全削除を行うための画面である。

**業務上の目的・背景**：CMS運用において、誤削除からのデータ復旧は重要な業務要件である。ゴミ箱機能により、ユーザーは削除したドキュメントを一定期間保持し、必要に応じて復元することができる。これにより、運用ミスによるデータ損失リスクを軽減し、安全なコンテンツ管理を実現する。また、不要なデータを完全に削除する機能も提供し、ストレージの最適化を支援する。

**画面へのアクセス方法**：コレクション一覧画面のヘッダーメニューから「ゴミ箱」ボタンをクリックするか、URLで `/{admin}/collections/{collectionSlug}/trash` に直接アクセスすることで表示される。

**主要な操作・処理内容**：
1. 削除済みドキュメントの一覧表示（削除日時、タイトル、ステータス等の情報を含む）
2. 個別ドキュメントの選択と復元操作
3. 一括選択による複数ドキュメントの復元
4. 削除済みドキュメントの詳細表示
5. ページネーション・ソート・検索によるリスト操作

**画面遷移**：
- 遷移元：コレクション一覧画面からゴミ箱ボタン押下
- 遷移先：ドキュメント編集画面（削除済みドキュメントの詳細表示）、コレクション一覧画面（戻るボタン）

**権限による表示制御**：コレクションの `read` 権限を持つユーザーのみがゴミ箱を閲覧可能。復元操作には `update` 権限、完全削除には `delete` 権限が必要となる。権限がない操作ボタンは非表示またはdisabled状態となる。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | コレクション管理 | 主機能 | 削除済みドキュメントの一覧表示・復元処理 |
| 30 | Admin UI | 補助機能 | ゴミ箱一覧UIのレンダリング |
| 11 | REST API | API連携 | 削除済みドキュメントのフェッチ処理 |

## 画面種別

一覧

## URL/ルーティング

`/{adminRoute}/collections/{collectionSlug}/trash`

- `{adminRoute}`: 管理画面のベースパス（デフォルト: `/admin`）
- `{collectionSlug}`: 対象コレクションのスラッグ

## 入出力項目

| 項目名 | 入力/出力 | データ型 | 必須 | 説明 |
|--------|----------|---------|------|------|
| collectionSlug | 入力 | string | Yes | 対象コレクションのスラッグ（URLパラメータ） |
| page | 入力 | number | No | 現在のページ番号（クエリパラメータ） |
| limit | 入力 | number | No | 1ページあたりの表示件数（クエリパラメータ） |
| sort | 入力 | string | No | ソート条件（クエリパラメータ） |
| search | 入力 | string | No | 検索クエリ（クエリパラメータ） |
| docs | 出力 | array | - | 削除済みドキュメントの配列 |
| totalDocs | 出力 | number | - | 削除済みドキュメントの総数 |
| totalPages | 出力 | number | - | 総ページ数 |
| hasNextPage | 出力 | boolean | - | 次ページの有無 |
| hasPrevPage | 出力 | boolean | - | 前ページの有無 |

## 表示項目

| 項目名 | データ型 | 説明 |
|--------|---------|------|
| チェックボックス | boolean | 一括選択用のチェックボックス |
| タイトル（useAsTitle） | string | ドキュメントを識別するタイトル |
| 削除日時 | datetime | ドキュメントが削除された日時 |
| ステータス | string | ドキュメントのステータス（draft/published） |
| 更新日時 | datetime | 最終更新日時 |
| 作成者 | string | ドキュメント作成者 |

## イベント仕様

### 1-ゴミ箱一覧表示

画面初期表示時に削除済みドキュメントを取得し、テーブルに表示する。

**処理フロー**：
1. URLパラメータから `collectionSlug` を取得
2. `deletedAt` フィールドが存在するドキュメントを検索条件として設定
3. `payload.find()` APIを呼び出し、削除済みドキュメントを取得
4. テーブルコンポーネントにデータをバインドして表示

### 2-ドキュメント復元

選択したドキュメントをゴミ箱から復元し、通常の一覧に戻す。

**処理フロー**：
1. 復元対象のドキュメントIDを取得
2. `payload.update()` APIで `deletedAt` フィールドを `null` に更新
3. 成功時はトースト通知を表示し、一覧を再取得

### 3-ページネーション操作

ページ切り替え時に該当ページのデータを取得する。

**処理フロー**：
1. ページ番号をURLクエリパラメータに設定
2. サーバーサイドでデータを再取得
3. テーブルを更新表示

### 4-ソート操作

カラムヘッダーをクリックしてソート順を変更する。

**処理フロー**：
1. ソート対象のフィールド名とソート方向をURLクエリパラメータに設定
2. サーバーサイドでソート済みデータを取得
3. テーブルを更新表示

### 5-ドキュメント詳細表示

一覧から削除済みドキュメントをクリックして詳細を表示する。

**処理フロー**：
1. ドキュメントIDを取得
2. ドキュメント編集画面へ遷移（trash=true パラメータ付き）

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| ゴミ箱一覧表示 | {collectionSlug} | SELECT | deletedAtが存在するドキュメントを取得 |
| ドキュメント復元 | {collectionSlug} | UPDATE | deletedAtフィールドをnullに更新 |
| 完全削除 | {collectionSlug} | DELETE | ドキュメントを物理削除 |

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

#### {collectionSlug}（対象コレクション）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | - | WHERE deletedAt IS NOT NULL | ゴミ箱表示用 |
| UPDATE | deletedAt | null | 復元時に削除日時をクリア |
| DELETE | - | WHERE id = {docId} | 完全削除時 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|----------|
| trash.restored | 成功 | ドキュメントが復元されました | 復元処理成功時 |
| trash.deleted | 成功 | ドキュメントが完全に削除されました | 完全削除成功時 |
| trash.restoreError | エラー | ドキュメントの復元に失敗しました | 復元処理失敗時 |
| trash.deleteError | エラー | ドキュメントの削除に失敗しました | 完全削除失敗時 |
| trash.noPermission | エラー | この操作を実行する権限がありません | 権限不足時 |

## 例外処理

| 例外状態 | 対応 |
|---------|------|
| コレクションが存在しない | 404 Not Foundページを表示 |
| 読取権限がない | 403 Forbiddenエラーを返却 |
| 削除済みドキュメントが0件 | 「削除済みドキュメントはありません」メッセージを表示 |
| ネットワークエラー | エラートーストを表示し、リトライを促す |
| トークン期限切れ | ログイン画面へリダイレクト |

## 備考

- ゴミ箱画面は、一覧画面（ListView）のコンポーネントを再利用して実装されている
- `trash: true` パラメータを `renderListView` に渡すことで、ゴミ箱モードとして動作する
- 削除済みドキュメントは `deletedAt` フィールドの有無で識別される
- `enableRowSelections: true` により、一括選択・一括操作が可能

---

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

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

### 推奨読解順序

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

ゴミ箱画面で扱うデータ構造の理解が重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | types.ts | `packages/payload/src/types/index.ts` | PaginatedDocs型の構造（docs, totalDocs, hasNextPage等） |
| 1-2 | ListQuery | `packages/payload/src/admin/types.ts` | リスト表示用クエリパラメータの型定義 |

**読解のコツ**: TypeScriptの型定義から、画面で扱うデータの全体像を把握する。`PaginatedDocs` 型がページネーション付きリストの標準形式である。

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

ゴミ箱画面のエントリーポイントとなるファイルを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.tsx | `packages/next/src/views/CollectionTrash/index.tsx` | TrashViewコンポーネントの構造 |

**主要処理フロー**:
1. **行22-23**: TrashViewコンポーネントの定義、argsからパラメータを受け取る
2. **行25-31**: renderListViewを呼び出し、trash: true, viewType: 'trash' を設定
3. **行33**: レンダリング結果を返却
4. **行35-38**: エラー時のnot-found処理

#### Step 3: リスト表示ロジックを理解する

ゴミ箱画面は一覧画面のロジックを再利用している。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.tsx | `packages/next/src/views/List/index.tsx` | renderListView関数の実装 |

**主要処理フロー**:
- **行208-219**: trash=true の場合、whereクエリに `deletedAt: { exists: true }` を追加
- **行286-302**: payload.find() でドキュメントを取得
- **行310-326**: renderTable() でテーブルをレンダリング

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

```
TrashView (CollectionTrash/index.tsx)
    │
    └─ renderListView (List/index.tsx)
           │
           ├─ upsertPreferences() - ユーザー設定の取得・保存
           │
           ├─ payload.find() - 削除済みドキュメント取得
           │      └─ where: { deletedAt: { exists: true } }
           │
           ├─ enrichDocsWithVersionStatus() - バージョン情報付与
           │
           ├─ renderTable() - テーブルUIレンダリング
           │
           └─ DefaultListView - クライアントコンポーネント
                  │
                  ├─ Table - テーブル表示
                  ├─ Pagination - ページネーション
                  └─ BulkActions - 一括操作
```

### データフロー図

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

URLパラメータ ───▶ TrashView ───▶ テーブル表示
  - collectionSlug         │
  - page                   ├─▶ renderListView()
  - limit                  │      │
  - sort                   │      ├─▶ payload.find(trash: true)
                           │      │      │
                           │      │      └─▶ 削除済みドキュメント取得
                           │      │
                           │      └─▶ renderTable()
                           │             │
                           │             └─▶ Table/Pagination表示
                           │
                           └─▶ クライアントへレスポンス
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.tsx | `packages/next/src/views/CollectionTrash/index.tsx` | ソース | ゴミ箱画面のエントリーポイント |
| index.tsx | `packages/next/src/views/List/index.tsx` | ソース | 一覧表示ロジック（再利用） |
| renderListViewSlots.tsx | `packages/next/src/views/List/renderListViewSlots.tsx` | ソース | リストビューのスロット定義 |
| DefaultListView | `packages/ui/src/views/List/Default.tsx` | ソース | クライアント側リストビューコンポーネント |
| Table | `packages/ui/src/elements/Table/index.tsx` | ソース | テーブルUIコンポーネント |
| Pagination | `packages/ui/src/elements/Pagination/index.tsx` | ソース | ページネーションコンポーネント |
| index.scss | `packages/next/src/views/List/index.scss` | スタイル | リストビューのスタイル定義 |
