# 画面設計書 8-ダッシュボード画面

## 概要

本ドキュメントは、Payload CMSの管理画面におけるダッシュボード画面の設計について記載する。管理画面のトップページとして、コレクションやグローバルへのナビゲーションを提供する画面である。

### 本画面の処理概要

本画面は、Payload CMS管理画面のトップページとして機能し、ユーザーがアクセス可能なコレクションやグローバルの一覧をカード形式で表示する。モジュラーダッシュボードとウィジェットに対応しており、カスタマイズが可能である。

**業務上の目的・背景**：管理者がシステム全体を俯瞰し、各コンテンツ管理機能へ素早くアクセスできるようにする。コレクション、グローバル、ショートカットなどを一覧表示し、効率的なコンテンツ管理を支援する。モジュラーダッシュボードにより、プロジェクト固有のニーズに合わせたカスタマイズが可能であり、重要な情報やアクションへのアクセスを最適化できる。

**画面へのアクセス方法**：ログイン成功後に自動的に遷移する。または管理画面のロゴやナビゲーションのダッシュボードリンクをクリックする。URLパターンは `/admin` となる。

**主要な操作・処理内容**：
1. アクセス可能なコレクション一覧をカード形式で表示
2. アクセス可能なグローバル一覧をカード形式で表示
3. 各カードをクリックして対応する一覧画面または編集画面へ遷移
4. カスタムウィジェットの表示（設定による）
5. ナビゲーショングループによる整理された表示

**画面遷移**：
- 遷移元：ログイン画面、初回ユーザー作成画面、各種管理画面のロゴクリック
- 遷移先：コレクション一覧画面、グローバル編集画面、フォルダブラウズ画面、アカウント設定画面

**権限による表示制御**：ユーザーの権限に基づいて、表示されるコレクションやグローバルがフィルタリングされる。visibleEntitiesとpermissionsに基づいて、アクセス権のあるエンティティのみが表示される。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 30 | Admin UI | 主機能 | 管理画面トップページのレンダリング |
| 1 | コレクション管理 | 補助機能 | コレクション一覧のナビゲーション表示 |
| 2 | グローバル管理 | 補助機能 | グローバル一覧のナビゲーション表示 |
| 63 | アクセス制御 | API連携 | 表示可能なエンティティの権限チェック |

## 画面種別

ダッシュボード（トップページ）

## URL/ルーティング

- **URL**: `/admin`
- **ルーティング定義**: `packages/next/src/routes/dashboard`

## 入出力項目

本画面は入力項目を持たない。

## 表示項目

| 項目名 | 表示位置 | データソース | 説明 |
|--------|----------|--------------|------|
| ナビゲーショングループ | メインエリア | navGroups | コレクション・グローバルをグループ化して表示 |
| コレクションカード | ナビゲーショングループ内 | visibleEntities.collections | 各コレクションへのナビゲーションカード |
| グローバルカード | ナビゲーショングループ内 | visibleEntities.globals | 各グローバルへのナビゲーションカード |
| beforeDashboardコンポーネント | 上部 | config.admin.components.beforeDashboard | カスタムコンポーネント挿入エリア |
| afterDashboardコンポーネント | 下部 | config.admin.components.afterDashboard | カスタムコンポーネント挿入エリア |
| モジュラーダッシュボード | 中央 | ModularDashboard | ウィジェットベースのダッシュボード |

## イベント仕様

### 1-コレクションカードクリック

- **トリガー**: コレクションカードクリック
- **処理内容**: 対象コレクションの一覧画面へ遷移
- **遷移先**: コレクション一覧画面（`/admin/collections/{collectionSlug}`）

### 2-グローバルカードクリック

- **トリガー**: グローバルカードクリック
- **処理内容**: 対象グローバルの編集画面へ遷移
- **遷移先**: グローバル編集画面（`/admin/globals/{globalSlug}`）

### 3-フォルダビューリンククリック

- **トリガー**: フォルダビューリンククリック
- **処理内容**: フォルダブラウズ画面へ遷移
- **遷移先**: フォルダブラウズ画面

### 4-アカウントリンククリック

- **トリガー**: アカウントリンククリック（ヘッダー/ナビゲーション）
- **処理内容**: アカウント設定画面へ遷移
- **遷移先**: アカウント設定画面

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面表示 | globals（各グローバル） | SELECT | グローバルのロック状態と編集情報を取得 |

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

#### globals（各グローバル）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | _isLocked | - | ロック状態 |
| SELECT | _lastEditedAt | - | 最終編集日時 |
| SELECT | _userEditing | - | 編集中ユーザー |

## メッセージ仕様

本画面では特別なメッセージは表示されない。各コレクション・グローバルのラベルは設定から取得される。

## 例外処理

| 例外状況 | 処理内容 |
|----------|---------|
| グローバルデータ取得失敗 | エラーログを出力、該当グローバルのカードは表示しない |
| 権限なし | ダッシュボード自体が表示されず、権限エラー画面へリダイレクト |

## 備考

- config.admin.components.views.dashboard.Componentでカスタムダッシュボードコンポーネントを指定可能
- DefaultDashboardがフォールバックとして使用される
- SetStepNavで空のナビゲーションパスが設定される
- HydrateAuthProviderで権限情報がクライアントに渡される
- モジュラーダッシュボードは将来的にウィジェットベースのカスタマイズを提供

---

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

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

### 推奨読解順序

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

まず、ダッシュボードで使用されるデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | DashboardViewServerProps | `packages/next/src/views/Dashboard/Default/index.tsx` | サーバーpropsの構造 |
| 1-2 | navGroups型 | `packages/ui/src/shared/groupNavItems.ts` | ナビゲーショングループの構造 |

**読解のコツ**: navGroupsはgroupNavItems関数で生成され、コレクションとグローバルをグループ化した構造を持つ。

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

処理の起点となるサーバーコンポーネントを特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | DashboardView | `packages/next/src/views/Dashboard/index.tsx` | サーバーコンポーネント |

**主要処理フロー**:
1. **行12-24**: initPageResultから必要な情報を抽出
2. **行26**: getGlobalDataでグローバルのデータを取得
3. **行27**: getNavGroupsでナビゲーショングループを構築
4. **行29-53**: HydrateAuthProvider、SetStepNav、RenderServerComponentでレンダリング

#### Step 3: デフォルトダッシュボードを理解する

デフォルトのダッシュボードUIを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | DefaultDashboard | `packages/next/src/views/Dashboard/Default/index.tsx` | デフォルトUI |

**主要処理フロー**:
- **行42-78**: Gutterでラップ、beforeDashboard/afterDashboardの挿入、ModularDashboardの表示

#### Step 4: モジュラーダッシュボードを理解する

ウィジェットベースのダッシュボードを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | ModularDashboard | `packages/next/src/views/Dashboard/Default/ModularDashboard/index.tsx` | ウィジェットダッシュボード |

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

```
DashboardView (Server Component)
    |
    +-- getGlobalData()
    |
    +-- getNavGroups()
    |
    +-- HydrateAuthProvider
    |
    +-- SetStepNav (nav=[])
    |
    +-- RenderServerComponent
            |
            +-- [カスタムコンポーネント]
            |     +-- config.admin.components.views.dashboard.Component
            |
            +-- [フォールバック]
                  +-- DefaultDashboard
                        |
                        +-- Gutter
                              |
                              +-- beforeDashboard
                              |
                              +-- ModularDashboard
                              |     +-- ナビゲーションカード
                              |     +-- ウィジェット
                              |
                              +-- afterDashboard
```

### データフロー図

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

initPageResult --------> DashboardView
        |                      |
        v                      v
  permissions --------> getNavGroups()
  visibleEntities               |
  config                        v
        |               navGroups
        |                      |
        v                      v
  req -----------> getGlobalData() -----> globalData
                              |
                              v
                     DefaultDashboard
                              |
                              v
                     ModularDashboard
                              |
                              v
                     ナビゲーションカード表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.tsx | `packages/next/src/views/Dashboard/index.tsx` | ソース | サーバーコンポーネント |
| Default/index.tsx | `packages/next/src/views/Dashboard/Default/index.tsx` | ソース | デフォルトダッシュボード |
| ModularDashboard/index.tsx | `packages/next/src/views/Dashboard/Default/ModularDashboard/index.tsx` | ソース | モジュラーダッシュボード |
| groupNavItems.ts | `packages/ui/src/shared/groupNavItems.ts` | ソース | ナビゲーショングループ構築 |
| getGlobalData.ts | `packages/ui/src/shared/getGlobalData.ts` | ソース | グローバルデータ取得 |
| Gutter | `packages/ui/src/elements/Gutter/index.tsx` | ソース | レイアウトコンポーネント |
| HydrateAuthProvider | `packages/ui/src/providers/Auth/HydrateAuth.tsx` | ソース | 権限情報プロバイダー |
