# 画面設計書 15-バージョン詳細画面

## 概要

本ドキュメントは、Payload CMSの管理画面における「バージョン詳細画面」の設計仕様を定義するものである。特定バージョンの詳細内容と他バージョンとの差分を表示し、復元機能を提供する画面である。

### 本画面の処理概要

バージョン詳細画面は、選択された特定バージョンの詳細内容を表示し、他のバージョン（前バージョン、公開中バージョンなど）との差分を視覚的に比較できる画面である。

**業務上の目的・背景**：コンテンツの変更履歴を追跡する際、単にバージョンを一覧で確認するだけでなく、具体的にどのフィールドがどのように変更されたかを把握することが重要である。この画面により、ユーザーは2つのバージョン間の差分をフィールド単位で視覚的に確認でき、必要に応じて過去のバージョンに復元することができる。多言語サイトでは、ロケールごとの変更も確認可能である。

**画面へのアクセス方法**：バージョン一覧画面から特定のバージョンをクリック、またはURLで `/{admin}/collections/{collectionSlug}/{docId}/versions/{versionId}` に直接アクセスすることで表示される。

**主要な操作・処理内容**：
1. 選択バージョンの詳細情報表示（作成日時、ステータス）
2. 比較対象バージョンの選択（前バージョン、公開中、最新ドラフトなど）
3. フィールド単位の差分表示（追加・削除・変更を色分け）
4. 変更のあるフィールドのみ表示するフィルタリング
5. ロケール選択による多言語差分確認
6. 選択バージョンへの復元操作

**画面遷移**：
- 遷移元：バージョン一覧画面
- 遷移先：ドキュメント編集画面（復元後）、バージョン一覧画面（戻る）

**権限による表示制御**：ドキュメントの `read` 権限を持つユーザーがバージョン詳細を閲覧可能。復元操作には `update` 権限が必要。権限がない場合、復元ボタンは非表示となる。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 4 | バージョン管理 | 主機能 | 特定バージョンの詳細表示・差分比較・復元 |
| 3 | フィールドシステム | 補助機能 | フィールド単位の差分表示 |
| 51 | 翻訳システム | 補助機能 | ローカライズされたバージョン比較（多言語環境時） |

## 画面種別

詳細（バージョン比較）

## URL/ルーティング

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

パラメータ:
- `{adminRoute}`: 管理画面のベースパス
- `{collectionSlug}`: コレクションスラッグ
- `{docId}`: ドキュメントID
- `{globalSlug}`: グローバルスラッグ
- `{versionId}`: 表示するバージョンのID

クエリパラメータ:
- `versionFrom`: 比較対象バージョンID
- `localeCodes`: 表示するロケールコードのJSON配列
- `modifiedOnly`: 変更フィールドのみ表示（true/false）

## 入出力項目

| 項目名 | 入力/出力 | データ型 | 必須 | 説明 |
|--------|----------|---------|------|------|
| versionId | 入力 | string | Yes | 表示するバージョンID（URLパラメータ） |
| versionFrom | 入力 | string | No | 比較対象バージョンID（クエリパラメータ） |
| localeCodes | 入力 | string[] | No | 表示ロケール（クエリパラメータ） |
| modifiedOnly | 入力 | boolean | No | 変更フィールドのみ表示（デフォルト: true） |
| versionTo | 出力 | object | - | 表示対象バージョンのデータ |
| versionFromData | 出力 | object | - | 比較対象バージョンのデータ |
| RenderedDiff | 出力 | ReactNode | - | 差分表示コンポーネント |

## 表示項目

| 項目名 | データ型 | 説明 |
|--------|---------|------|
| バージョン作成日時 | datetime | 表示中バージョンの作成日時 |
| ステータスラベル | ReactNode | 公開済み/ドラフト/最新などのラベル |
| 比較対象選択 | SelectField | 比較するバージョンを選択するドロップダウン |
| ロケール選択 | Pills | 表示するロケールを選択するUI |
| 変更のみ表示 | Checkbox | 変更フィールドのみ表示するチェックボックス |
| 差分表示 | DiffView | フィールド単位の差分を色分け表示 |
| 復元ボタン | Button | このバージョンに復元するボタン |

## イベント仕様

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

画面表示時にバージョンデータと差分を取得して表示する。

**処理フロー**：
1. URLパラメータからversionId（versionTo）を取得
2. `fetchVersion()` で表示対象バージョンを取得
3. 比較対象バージョン（versionFrom）を決定
   - クエリパラメータで指定されていれば使用
   - なければ前バージョンを使用
4. 公開中バージョンと最新ドラフトバージョンを取得
5. `RenderDiff()` で差分表示コンポーネントを生成
6. 比較オプション一覧を構築

### 2-比較対象バージョン変更

比較するバージョンを変更する。

**処理フロー**：
1. SelectComparisonで新しいバージョンを選択
2. URLクエリパラメータ `versionFrom` を更新
3. ページを再レンダリング

### 3-変更のみ表示切り替え

変更フィールドのみ表示するかを切り替える。

**処理フロー**：
1. チェックボックスの状態を変更
2. URLクエリパラメータ `modifiedOnly` を更新
3. 差分表示を再レンダリング

### 4-ロケール選択

表示するロケールを選択する。

**処理フロー**：
1. ロケールPillsをクリックして選択/解除
2. URLクエリパラメータ `localeCodes` を更新
3. 差分表示を再レンダリング

### 5-バージョン復元

選択中のバージョンに復元する。

**処理フロー**：
1. 復元ボタンをクリック
2. 確認ダイアログを表示
3. 復元APIを呼び出し
4. ドキュメント編集画面にリダイレクト

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| バージョン詳細表示 | _{collectionSlug}_versions | SELECT | 指定バージョンと比較対象を取得 |
| バージョン復元 | {collectionSlug}, _{collectionSlug}_versions | UPDATE/INSERT | ドキュメントを更新、新バージョン作成 |

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

#### _{collectionSlug}_versions

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | - | WHERE id = {versionId} | 表示対象バージョン取得 |
| SELECT | - | WHERE updatedAt < {versionTo.updatedAt} ORDER BY updatedAt DESC LIMIT 1 | 前バージョン取得 |
| INSERT | - | 復元内容を新バージョンとして作成 | 復元時 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|----------|
| version.compareVersions | タイトル | バージョンを比較 | 画面タイトル |
| version.comparingAgainst | ラベル | 比較対象 | 比較元選択ラベル |
| version.currentlyViewing | ラベル | 現在表示中 | 表示中バージョンラベル |
| version.modifiedOnly | ラベル | 変更のみ表示 | フィルターラベル |
| version.versionAgo | 情報 | {distance}前 | 相対時間表示 |
| version.restored | 成功 | バージョンを復元しました | 復元成功時 |
| version.restoreError | エラー | バージョンの復元に失敗しました | 復元失敗時 |

## 例外処理

| 例外状態 | 対応 |
|---------|------|
| バージョンが存在しない | notFound()を呼び出し |
| 比較対象バージョンがない | 差分なしで表示 |
| 復元権限がない | 復元ボタンを非表示 |
| ゴミ箱内ドキュメント | 復元ボタンを非表示 |

## 備考

- versionToは常にURLのversionIdから取得される
- versionFromはデフォルトで前バージョン（versionToより古い最新バージョン）
- 比較オプションには以下が含まれる：
  - 前バージョン（Previous Version）
  - 最新ドラフト（Latest Draft）
  - 現在公開中（Currently Published）
  - 以前の公開版（Previously Published）
  - 特定バージョン（Specific Version）
- ローカライゼーション有効時、全ロケールまたは選択ロケールの差分を表示
- `modifiedOnly` はデフォルトtrueで、変更のあるフィールドのみ表示
- 復元はゴミ箱内ドキュメントでは無効

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | types.ts | `packages/next/src/views/Version/Default/types.ts` | DefaultVersionsViewProps, CompareOption型 |
| 1-2 | index.tsx | `packages/next/src/views/Version/index.tsx` | VersionView関数のprops構造 |

**読解のコツ**: `versionTo` が表示対象、`versionFrom` が比較対象である。両方とも `TypeWithVersion<T>` 型でラップされている。

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

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

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

**主要処理フロー**:
1. **行37**: versionToIDをURLセグメントから取得
2. **行61-72**: `fetchVersion()` で表示対象バージョン（versionTo）を取得
3. **行78-182**: Promise.all()で複数バージョンを並行取得
   - previousVersion: 前バージョン
   - versionFromResult: クエリパラメータ指定のバージョン
   - currentlyPublishedVersion: 公開中バージョン
   - latestDraftVersion: 最新ドラフト
   - previousPublishedVersion: 以前の公開版
4. **行236-258**: RenderDiff()で差分コンポーネント生成
5. **行304-427**: versionFromComparisonOptionsの構築

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

クライアント側の差分表示とインタラクションを確認する。

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

**主要処理フロー**:
- **行84-124**: updateSearchParams() でURL更新ロジック
- **行126-135**: onToggleModifiedOnly() で変更のみ表示切り替え
- **行137-145**: onChangeSelectedLocales() でロケール変更
- **行147-154**: onChangeVersionFrom() で比較対象変更
- **行237-244**: SelectComparison コンポーネントで比較対象選択UI
- **行254-265**: Restore コンポーネントで復元ボタン

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

```
VersionView (Version/index.tsx)
    │
    ├─ fetchVersion(versionToID) - 表示対象バージョン取得
    │
    ├─ Promise.all() - 並行処理
    │   ├─ fetchVersions() - 前バージョン取得
    │   │      └─ WHERE updatedAt < versionTo.updatedAt
    │   ├─ fetchVersion(versionFromID) - クエリ指定バージョン
    │   ├─ fetchLatestVersion(status: 'published')
    │   ├─ fetchLatestVersion(status: 'draft')
    │   └─ fetchVersions() - 以前の公開版
    │
    ├─ RenderDiff() - 差分表示コンポーネント生成
    │   ├─ clientSchemaMap
    │   ├─ fields
    │   ├─ versionFromSiblingData
    │   └─ versionToSiblingData
    │
    ├─ versionFromComparisonOptions構築
    │   ├─ previousVersion
    │   ├─ latestDraftVersion
    │   ├─ currentlyPublishedVersion
    │   └─ previousPublishedVersion
    │
    └─ DefaultVersionView
           │
           ├─ SelectComparison - 比較対象選択
           ├─ SelectLocales - ロケール選択
           ├─ CheckboxInput - 変更のみ表示
           ├─ RenderedDiff - 差分表示
           └─ Restore - 復元ボタン
```

### データフロー図

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

URLパラメータ ───▶ VersionView ───▶ 差分比較画面
  - versionId                 │
  (= versionTo)               ├─▶ fetchVersion(versionToID)
                              │      └─▶ 表示対象バージョン
クエリパラメータ ────────────┤
  - versionFrom               ├─▶ 比較対象決定
  - localeCodes               │      ├─▶ versionFromID指定あり → そのバージョン
  - modifiedOnly              │      └─▶ なし → 前バージョン
                              │
                              ├─▶ Promise.all() で複数バージョン取得
                              │
                              ├─▶ RenderDiff()
                              │      └─▶ フィールド単位差分生成
                              │
                              └─▶ DefaultVersionView
                                     ├─▶ 差分表示
                                     ├─▶ 比較対象選択UI
                                     └─▶ 復元ボタン
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.tsx | `packages/next/src/views/Version/index.tsx` | ソース | バージョン詳細画面のサーバーコンポーネント |
| index.tsx | `packages/next/src/views/Version/Default/index.tsx` | ソース | クライアント側UIコンポーネント |
| types.ts | `packages/next/src/views/Version/Default/types.ts` | 型定義 | props型定義 |
| fetchVersions.ts | `packages/next/src/views/Version/fetchVersions.ts` | ソース | バージョン取得ユーティリティ |
| RenderFieldsToDiff | `packages/next/src/views/Version/RenderFieldsToDiff/index.tsx` | ソース | 差分表示コンポーネント |
| SelectComparison | `packages/next/src/views/Version/SelectComparison/index.tsx` | ソース | 比較対象選択UI |
| SelectLocales | `packages/next/src/views/Version/SelectLocales/index.tsx` | ソース | ロケール選択UI |
| Restore | `packages/next/src/views/Version/Restore/index.tsx` | ソース | 復元ボタンコンポーネント |
| index.scss | `packages/next/src/views/Version/Default/index.scss` | スタイル | バージョン詳細のスタイル |
