# 画面設計書 14-バージョン一覧画面

## 概要

本ドキュメントは、Payload CMSの管理画面における「バージョン一覧画面」の設計仕様を定義するものである。ドキュメントの全バージョン履歴を一覧表示し、各バージョンへのナビゲーションを提供する画面である。

### 本画面の処理概要

バージョン一覧画面は、コレクションドキュメントまたはグローバルの全バージョン履歴を時系列で一覧表示し、特定バージョンの詳細表示や復元操作へのナビゲーションを提供する画面である。

**業務上の目的・背景**：コンテンツ管理において、変更履歴の追跡は非常に重要である。バージョン管理機能により、ユーザーは過去のコンテンツ状態を確認し、必要に応じて以前のバージョンに復元できる。この画面は、全てのバージョンを一覧で俯瞰し、公開済み・ドラフト・オートセーブの各ステータスを識別しながら、適切なバージョンを選択するためのハブとして機能する。

**画面へのアクセス方法**：ドキュメント編集画面のヘッダーから「バージョン履歴」ボタンをクリック、またはURLで `/{admin}/collections/{collectionSlug}/{docId}/versions` に直接アクセスすることで表示される。グローバルの場合は `/{admin}/globals/{globalSlug}/versions`。

**主要な操作・処理内容**：
1. 全バージョンのリスト表示（作成日時、ステータス、作成者情報）
2. バージョンのステータス表示（公開済み、ドラフト、オートセーブ、最新など）
3. 特定バージョンの詳細画面へのナビゲーション
4. ページネーションによる大量バージョンの閲覧
5. 表示件数の変更

**画面遷移**：
- 遷移元：ドキュメント編集画面
- 遷移先：バージョン詳細画面（バージョン選択時）、ドキュメント編集画面（戻る）

**権限による表示制御**：ドキュメントの `read` 権限を持つユーザーがバージョン一覧を閲覧可能。バージョン履歴は `versions` 設定が有効なコレクション/グローバルでのみ表示される。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 4 | バージョン管理 | 主機能 | ドキュメントの全バージョン履歴の一覧表示 |
| 30 | Admin UI | 補助機能 | バージョン一覧テーブルUIのレンダリング |
| 11 | REST API | API連携 | バージョンデータのフェッチ処理 |

## 画面種別

一覧

## URL/ルーティング

- コレクション: `/{adminRoute}/collections/{collectionSlug}/{docId}/versions`
- グローバル: `/{adminRoute}/globals/{globalSlug}/versions`
- ゴミ箱: `/{adminRoute}/collections/{collectionSlug}/{docId}/trash/versions`

パラメータ:
- `{adminRoute}`: 管理画面のベースパス（デフォルト: `/admin`）
- `{collectionSlug}`: 対象コレクションのスラッグ
- `{docId}`: ドキュメントID
- `{globalSlug}`: グローバルスラッグ

## 入出力項目

| 項目名 | 入力/出力 | データ型 | 必須 | 説明 |
|--------|----------|---------|------|------|
| collectionSlug | 入力 | string | Yes* | 対象コレクションのスラッグ（コレクション時） |
| globalSlug | 入力 | string | Yes* | 対象グローバルのスラッグ（グローバル時） |
| docId | 入力 | string | Yes* | ドキュメントID（コレクション時） |
| page | 入力 | number | No | 現在のページ番号 |
| limit | 入力 | number | No | 1ページあたりの表示件数 |
| sort | 入力 | string | No | ソート条件 |
| docs | 出力 | array | - | バージョンの配列 |
| totalDocs | 出力 | number | - | バージョンの総数 |
| totalPages | 出力 | number | - | 総ページ数 |
| hasNextPage | 出力 | boolean | - | 次ページの有無 |
| hasPrevPage | 出力 | boolean | - | 前ページの有無 |

## 表示項目

| 項目名 | データ型 | 説明 |
|--------|---------|------|
| 作成日時 | datetime | バージョンが作成された日時 |
| ステータスラベル | ReactNode | 公開済み/ドラフト/オートセーブ/最新などのラベル |
| ID | string | バージョンID |
| 相対時間 | string | 「3時間前」などの相対表記 |

## イベント仕様

### 1-バージョン一覧表示

画面表示時にドキュメントの全バージョンを取得して表示する。

**処理フロー**：
1. URLパラメータからcollectionSlug/globalSlug、docIdを取得
2. `fetchVersions()` でバージョンデータを取得
3. `fetchLatestVersion()` で現在公開中バージョンと最新ドラフトを取得
4. `buildVersionColumns()` でテーブルカラムを構築
5. テーブルコンポーネントにデータをバインドして表示

### 2-バージョン詳細表示

バージョンをクリックして詳細画面に遷移する。

**処理フロー**：
1. クリックされたバージョンのIDを取得
2. バージョン詳細画面 `/{admin}/.../versions/{versionId}` へ遷移

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

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

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

### 4-表示件数変更

1ページあたりの表示件数を変更する。

**処理フロー**：
1. 選択された件数をURLクエリパラメータ `limit` に設定
2. `handlePerPageChange` でデータを再取得
3. テーブルを更新表示

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| バージョン一覧表示 | _{collectionSlug}_versions / _globals_versions | SELECT | バージョン履歴を取得 |

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

#### _{collectionSlug}_versions（コレクションバージョン）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | - | WHERE parent = {docId} ORDER BY updatedAt DESC | バージョン履歴取得 |
| SELECT | - | WHERE status = 'published' LIMIT 1 | 現在公開バージョン取得 |
| SELECT | - | WHERE status = 'draft' LIMIT 1 | 最新ドラフト取得 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|----------|
| version.noFurtherVersionsFound | 情報 | これ以上のバージョンはありません | バージョンが0件の場合 |

## 例外処理

| 例外状態 | 対応 |
|---------|------|
| バージョン機能が無効 | バージョンタブを非表示 |
| バージョンデータ取得失敗 | notFound()を呼び出し |
| ドキュメントが存在しない | 404ページを表示 |
| read権限がない | not-foundエラー |

## 備考

- バージョン機能は `versions` 設定が有効なコレクション/グローバルでのみ利用可能
- `draftsEnabled` が有効な場合のみ、ドラフトとスナップショットの区別が行われる
- ローカライゼーション有効時、スナップショット（`snapshot: true`）は除外される
- `currentlyPublishedVersion` と `latestDraftVersion` は並行取得される
- テーブルカラムは `buildVersionColumns()` で動的に構築される
- ページネーション設定は `collectionConfig.admin.pagination` に従う

---

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

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

### 推奨読解順序

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

バージョン一覧画面で扱うデータ構造の理解が重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | types | `packages/payload/src/types/index.ts` | PaginatedDocs型、TypeWithVersion型 |
| 1-2 | index.tsx | `packages/next/src/views/Versions/index.tsx` | VersionsViewのprops構造（行15-33） |

**読解のコツ**: バージョンデータは `TypeWithVersion<T>` 型でラップされ、`version` フィールドに元のドキュメントデータが格納される。

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

バージョン一覧画面のエントリーポイントとなるファイルを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.tsx | `packages/next/src/views/Versions/index.tsx` | VersionsView関数の構造 |

**主要処理フロー**:
1. **行15-33**: propsの分解（initPageResult、searchParams等）
2. **行35**: hasDraftsEnabled() でドラフト機能の有無を確認
3. **行48-59**: whereQueryの構築（スナップショット除外）
4. **行65-78**: fetchVersions() でバージョン一覧を取得
5. **行84-141**: fetchLatestVersion() で公開版・ドラフト版を並行取得
6. **行148-158**: buildVersionColumns() でカラム定義を構築

#### Step 3: クライアントコンポーネントを理解する

クライアント側のUIロジックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.client.tsx | `packages/next/src/views/Versions/index.client.tsx` | VersionsViewClientコンポーネント |

**主要処理フロー**:
- **行23**: useListQuery() でリストデータとハンドラーを取得
- **行35-39**: バージョンが0件の場合のメッセージ表示
- **行40-74**: テーブル表示とページネーションUI

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

```
VersionsView (Versions/index.tsx)
    │
    ├─ hasDraftsEnabled() - ドラフト機能確認
    │
    ├─ whereQuery構築
    │   └─ snapshot: { not_equals: true } (ローカライゼーション時)
    │
    ├─ fetchVersions() - バージョン一覧取得
    │   └─ collectionSlug/globalSlug, parentID, page, limit
    │
    ├─ Promise.all() - 並行処理
    │   ├─ fetchLatestVersion(status: 'published')
    │   └─ fetchLatestVersion(status: 'draft')
    │
    ├─ buildVersionColumns() - カラム定義構築
    │   ├─ currentlyPublishedVersion
    │   ├─ latestDraftVersion
    │   └─ docs
    │
    ├─ SetDocumentStepNav - パンくず設定
    │
    └─ VersionsViewClient
           │
           ├─ useListQuery() - データ・ハンドラー
           │
           ├─ LoadingOverlayToggle - ローディング表示
           │
           ├─ Table - バージョンテーブル
           │
           └─ Pagination/PerPage - ページネーション
```

### データフロー図

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

URLパラメータ ───▶ VersionsView ───▶ バージョン一覧テーブル
  - collectionSlug           │
  - docId                    ├─▶ fetchVersions()
  - page                     │      └─▶ バージョン配列取得
  - limit                    │
                             ├─▶ fetchLatestVersion() x 2
                             │      ├─▶ currentlyPublishedVersion
                             │      └─▶ latestDraftVersion
                             │
                             ├─▶ buildVersionColumns()
                             │      └─▶ カラム定義生成
                             │           └─▶ ステータスラベル付与
                             │
                             └─▶ VersionsViewClient
                                    └─▶ Table + Pagination表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.tsx | `packages/next/src/views/Versions/index.tsx` | ソース | バージョン一覧画面のサーバーコンポーネント |
| index.client.tsx | `packages/next/src/views/Versions/index.client.tsx` | ソース | クライアント側UIコンポーネント |
| buildColumns.tsx | `packages/next/src/views/Versions/buildColumns.tsx` | ソース | テーブルカラム構築ロジック |
| fetchVersions.ts | `packages/next/src/views/Version/fetchVersions.ts` | ソース | バージョンデータ取得ユーティリティ |
| index.scss | `packages/next/src/views/Versions/index.scss` | スタイル | バージョン一覧のスタイル定義 |
| Table | `packages/ui/src/elements/Table/index.tsx` | ソース | テーブルUIコンポーネント |
| Pagination | `packages/ui/src/elements/Pagination/index.tsx` | ソース | ページネーションコンポーネント |
| PerPage | `packages/ui/src/elements/PerPage/index.tsx` | ソース | 表示件数選択コンポーネント |
