# 機能設計書：グローバル管理

## 1. 機能概要

### 1.1 機能の目的
グローバル管理機能は、サイト全体で共有される単一のドキュメント（シングルトン）を管理する機能である。サイト設定、ナビゲーション、フッター情報など、複数のインスタンスを持たないデータの管理に使用される。

### 1.2 機能の範囲
- グローバルの設定定義と初期化
- グローバルドキュメントの取得（FindOne）
- グローバルドキュメントの更新（Update）
- アクセス制御とフック処理
- バージョン管理との連携

### 1.3 関連画面
| 画面ID | 画面名 | 関連操作 |
|--------|--------|----------|
| ADM-010 | グローバル設定 | findOne |
| ADM-011 | グローバル編集 | update |

---

## 2. 機能仕様

### 2.1 入力仕様

#### 2.1.1 FindOne操作
| パラメータ | 型 | 必須 | 説明 |
|-----------|-----|------|------|
| slug | string | Yes | グローバルのslug |
| depth | number | No | リレーション展開の深さ（デフォルト: 0） |
| locale | string | No | ロケール指定 |
| fallbackLocale | string | No | フォールバックロケール |
| overrideAccess | boolean | No | アクセス制御のオーバーライド |
| draft | boolean | No | 下書きを取得 |
| select | SelectType | No | 取得フィールドの選択 |

#### 2.1.2 Update操作
| パラメータ | 型 | 必須 | 説明 |
|-----------|-----|------|------|
| slug | string | Yes | グローバルのslug |
| data | object | Yes | 更新データ |
| depth | number | No | リレーション展開の深さ |
| locale | string | No | ロケール指定 |
| overrideAccess | boolean | No | アクセス制御のオーバーライド |
| draft | boolean | No | 下書きとして保存 |
| autosave | boolean | No | 自動保存フラグ |

### 2.2 出力仕様

#### 2.2.1 FindOne操作の戻り値
```typescript
{
  // グローバルドキュメントのフィールド値
  [fieldName: string]: any;
  // グローバル固有のメタ情報
  globalType: string;  // グローバルのslug
  createdAt?: string;  // 作成日時
  updatedAt?: string;  // 更新日時
}
```

#### 2.2.2 Update操作の戻り値
```typescript
{
  result: GlobalDocument;  // 更新後のドキュメント
  message: string;         // 操作結果メッセージ
}
```

### 2.3 処理フロー

```
[FindOne操作]
1. beforeOperation フック実行
2. アクセス制御チェック（read）
3. データベースからドキュメント取得
4. ドキュメントが存在しない場合は空オブジェクトを返却
5. afterRead フック実行
6. afterOperation フック実行
7. 結果を返却
```

```
[Update操作]
1. beforeOperation フック実行
2. アクセス制御チェック（update）
3. 既存ドキュメントの取得
4. beforeValidate フック実行
5. フィールドバリデーション
6. beforeChange フック実行
7. データベースの更新（upsert）
8. バージョン保存（有効時）
9. afterChange フック実行
10. afterRead フック実行
11. afterOperation フック実行
12. 結果を返却
```

### 2.4 バリデーションルール
- コレクションと同様のフィールドバリデーションを適用
- グローバル固有の制約（単一ドキュメント）

### 2.5 エラーハンドリング
| エラーコード | 説明 | HTTPステータス |
|-------------|------|---------------|
| NotFound | グローバルが定義されていない | 404 |
| Forbidden | アクセス権限がない | 403 |
| ValidationError | バリデーションエラー | 400 |

---

## 3. データ設計

### 3.1 グローバル設定スキーマ
```typescript
interface GlobalConfig {
  slug: string;                    // グローバル識別子
  label?: string | object;         // 表示ラベル
  fields: Field[];                 // フィールド定義
  access?: {
    read?: AccessFunction;         // 読取権限
    update?: AccessFunction;       // 更新権限
    readVersions?: AccessFunction; // バージョン読取権限
  };
  hooks?: {
    beforeOperation?: Hook[];
    beforeValidate?: Hook[];
    beforeChange?: Hook[];
    afterChange?: Hook[];
    afterRead?: Hook[];
    afterOperation?: Hook[];
  };
  admin?: {
    group?: string;                // 管理画面のグループ
    description?: string;          // 説明文
    hideAPIURL?: boolean;          // API URLの非表示
  };
  versions?: boolean | VersionConfig; // バージョン管理設定
  endpoints?: Endpoint[];          // カスタムエンドポイント
}
```

### 3.2 グローバルドキュメントスキーマ
```typescript
interface GlobalDocument {
  globalType: string;      // グローバルのslug
  createdAt?: string;      // ISO8601形式
  updatedAt?: string;      // ISO8601形式
  [fieldName: string]: any;
}
```

---

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

### 4.1 推奨読解順序

1. **型定義の理解**
   - `/packages/payload/src/globals/config/types.ts` - GlobalConfig型の定義
   - **1-50行目**: 基本的なグローバル設定の型定義
   - **51-100行目**: アクセス制御とフックの型定義
   - **101-150行目**: SanitizedGlobalConfigの定義

2. **FindOne操作の流れ**
   - `/packages/payload/src/globals/operations/findOne.ts`
   - **1-30行目**: 引数の型定義
   - **31-60行目**: beforeOperationフックの実行
   - **61-90行目**: アクセス制御のチェック
   - **91-120行目**: データベースからの取得処理
   - **121-150行目**: afterReadフックの実行

3. **Update操作の流れ**
   - `/packages/payload/src/globals/operations/update.ts`
   - **1-50行目**: 引数の型定義とトランザクション初期化
   - **51-100行目**: beforeOperationフックとアクセス制御
   - **101-150行目**: 既存データの取得とマージ
   - **151-200行目**: バリデーションとbeforeChangeフック
   - **201-250行目**: データベース更新とバージョン保存

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

```
payload.findGlobal()
  |
  +-- buildBeforeOperation()
  |     +-- beforeOperation hooks
  |
  +-- executeAccess()
  |     +-- access.read()
  |
  +-- payload.db.findGlobal()
  |     +-- Database Adapter
  |
  +-- afterRead hooks (fields)
  |
  +-- afterRead hooks (global)
  |
  +-- buildAfterOperation()
        +-- afterOperation hooks
```

```
payload.updateGlobal()
  |
  +-- buildBeforeOperation()
  |     +-- beforeOperation hooks
  |
  +-- executeAccess()
  |     +-- access.update()
  |
  +-- payload.db.findGlobal() [既存データ取得]
  |
  +-- beforeValidate hooks
  |
  +-- validateFields()
  |
  +-- beforeChange hooks
  |
  +-- payload.db.upsertGlobal()
  |     +-- Database Adapter
  |
  +-- saveVersion() [if versions enabled]
  |
  +-- afterChange hooks
  |
  +-- afterRead hooks
  |
  +-- buildAfterOperation()
        +-- afterOperation hooks
```

### 4.3 データフロー図

```
[FindOne]
+----------------+
| beforeOperation|
+----------------+
     |
     v
+----------------+
| Access Control | --> [Forbidden Error]
+----------------+
     |
     v
+----------------+
| Database Read  |
+----------------+
     |
     v
+----------------+
| afterRead      |
+----------------+
     |
     v
+----------------+
| afterOperation |
+----------------+
     |
     v
[GlobalDocument]
```

### 4.4 関連ファイル一覧

| ファイルパス | 種別 | 役割 |
|-------------|------|------|
| `/packages/payload/src/globals/config/types.ts` | 型定義 | グローバル設定の型定義 |
| `/packages/payload/src/globals/operations/findOne.ts` | 処理 | グローバル取得処理 |
| `/packages/payload/src/globals/operations/update.ts` | 処理 | グローバル更新処理 |
| `/packages/payload/src/globals/operations/docAccess.ts` | 処理 | ドキュメントアクセス制御 |
| `/packages/payload/src/versions/saveVersion.ts` | ユーティリティ | バージョン保存処理 |

---

## 5. 設計上の考慮事項

### 5.1 パフォーマンス考慮
- シングルトンのためキャッシュ効率が高い
- depth指定によるリレーション展開の制御

### 5.2 セキュリティ考慮
- read/updateの独立したアクセス制御
- フィールドレベルのアクセス制御

### 5.3 拡張性考慮
- フックシステムによる処理のカスタマイズ
- カスタムエンドポイントの追加
- バージョン管理による履歴追跡

---

## 6. 変更履歴

| 日付 | バージョン | 変更内容 | 担当者 |
|------|-----------|----------|--------|
| 2026-03-01 | 1.0.0 | 初版作成 | AI |
