# 機能設計書：コレクション管理

## 1. 機能概要

### 1.1 機能の目的
コレクション管理機能は、Payload CMSの中核となるデータ管理機能である。コレクションとは、データベース内のドキュメント群を論理的にグループ化したものであり、この機能によりCRUD操作（作成・読取・更新・削除）を統一的なインターフェースで実行できる。

### 1.2 機能の範囲
- コレクションの設定定義と初期化
- ドキュメントの作成（Create）
- ドキュメントの検索（Find / FindByID）
- ドキュメントの更新（Update / UpdateByID）
- ドキュメントの削除（Delete / DeleteByID）
- アクセス制御とフック処理
- データローダーによるバッチ処理最適化

### 1.3 関連画面
| 画面ID | 画面名 | 関連操作 |
|--------|--------|----------|
| ADM-001 | コレクション一覧 | find |
| ADM-002 | ドキュメント詳細 | findByID |
| ADM-003 | ドキュメント作成 | create |
| ADM-004 | ドキュメント編集 | update |

---

## 2. 機能仕様

### 2.1 入力仕様

#### 2.1.1 Create操作
| パラメータ | 型 | 必須 | 説明 |
|-----------|-----|------|------|
| collection | string | Yes | コレクションのslug |
| data | object | Yes | 作成するドキュメントデータ |
| depth | number | No | リレーション展開の深さ（デフォルト: 0） |
| locale | string | No | ロケール指定 |
| overrideAccess | boolean | No | アクセス制御のオーバーライド |
| draft | boolean | No | 下書きとして作成 |
| autosave | boolean | No | 自動保存フラグ |
| file | File | No | アップロードファイル |

#### 2.1.2 Find操作
| パラメータ | 型 | 必須 | 説明 |
|-----------|-----|------|------|
| collection | string | Yes | コレクションのslug |
| where | Where | No | 検索条件 |
| limit | number | No | 取得件数上限（デフォルト: 10） |
| page | number | No | ページ番号 |
| sort | string | No | ソート条件 |
| depth | number | No | リレーション展開の深さ |
| pagination | boolean | No | ページネーション有効化 |

#### 2.1.3 Update操作
| パラメータ | 型 | 必須 | 説明 |
|-----------|-----|------|------|
| collection | string | Yes | コレクションのslug |
| id | string/number | Yes | ドキュメントID |
| data | object | Yes | 更新データ |
| depth | number | No | リレーション展開の深さ |
| locale | string | No | ロケール指定 |
| overrideAccess | boolean | No | アクセス制御のオーバーライド |

#### 2.1.4 Delete操作
| パラメータ | 型 | 必須 | 説明 |
|-----------|-----|------|------|
| collection | string | Yes | コレクションのslug |
| id | string/number | No | ドキュメントID（単一削除時） |
| where | Where | No | 検索条件（一括削除時） |
| depth | number | No | リレーション展開の深さ |

### 2.2 出力仕様

#### 2.2.1 Create操作の戻り値
```typescript
{
  doc: Document,           // 作成されたドキュメント
  message: string,         // 操作結果メッセージ
  errors?: ValidationError[] // バリデーションエラー
}
```

#### 2.2.2 Find操作の戻り値
```typescript
{
  docs: Document[],        // ドキュメント配列
  totalDocs: number,       // 総件数
  limit: number,           // 取得件数上限
  totalPages: number,      // 総ページ数
  page: number,            // 現在ページ
  pagingCounter: number,   // ページングカウンター
  hasPrevPage: boolean,    // 前ページ有無
  hasNextPage: boolean,    // 次ページ有無
  prevPage: number | null, // 前ページ番号
  nextPage: number | null  // 次ページ番号
}
```

### 2.3 処理フロー

```
[Create操作]
1. beforeOperation フック実行
2. アクセス制御チェック
3. beforeValidate フック実行
4. フィールドバリデーション
5. beforeChange フック実行
6. データベースへの挿入
7. afterChange フック実行
8. afterRead フック実行
9. afterOperation フック実行
10. 結果を返却
```

```
[Find操作]
1. beforeOperation フック実行
2. アクセス制御チェック（whereへの追加条件）
3. データベースクエリ実行
4. afterRead フック実行（各ドキュメント）
5. afterOperation フック実行
6. 結果を返却
```

### 2.4 バリデーションルール
- required: 必須フィールドの検証
- minLength/maxLength: 文字列長の検証
- min/max: 数値範囲の検証
- unique: 一意性の検証
- カスタムvalidate関数による検証

### 2.5 エラーハンドリング
| エラーコード | 説明 | HTTPステータス |
|-------------|------|---------------|
| NotFound | ドキュメントが見つからない | 404 |
| Forbidden | アクセス権限がない | 403 |
| ValidationError | バリデーションエラー | 400 |
| LockedDocument | ドキュメントがロック中 | 423 |

---

## 3. データ設計

### 3.1 コレクション設定スキーマ
```typescript
interface CollectionConfig {
  slug: string;                    // コレクション識別子
  labels?: {
    singular?: string;             // 単数形ラベル
    plural?: string;               // 複数形ラベル
  };
  fields: Field[];                 // フィールド定義
  access?: {
    create?: AccessFunction;       // 作成権限
    read?: AccessFunction;         // 読取権限
    update?: AccessFunction;       // 更新権限
    delete?: AccessFunction;       // 削除権限
  };
  hooks?: {
    beforeOperation?: Hook[];
    beforeValidate?: Hook[];
    beforeChange?: Hook[];
    afterChange?: Hook[];
    afterRead?: Hook[];
    afterDelete?: Hook[];
    afterOperation?: Hook[];
  };
  admin?: {
    useAsTitle?: string;           // タイトルフィールド
    defaultColumns?: string[];     // デフォルト表示カラム
  };
  timestamps?: boolean;            // タイムスタンプ自動付与
  versions?: boolean | VersionConfig; // バージョン管理設定
  upload?: UploadConfig;           // アップロード設定
  auth?: AuthConfig;               // 認証設定
}
```

### 3.2 ドキュメントスキーマ
```typescript
interface Document {
  id: string | number;
  createdAt?: string;  // ISO8601形式
  updatedAt?: string;  // ISO8601形式
  [fieldName: string]: any;
}
```

---

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

### 4.1 推奨読解順序

1. **型定義の理解**
   - `/packages/payload/src/collections/config/types.ts` - CollectionConfig型の定義
   - **1-150行目**: 基本的なコレクション設定の型定義
   - **151-300行目**: アクセス制御とフックの型定義

2. **エントリーポイント**
   - `/packages/payload/src/collections/operations/` - 各CRUD操作のエントリーポイント

3. **Create操作の流れ**
   - `/packages/payload/src/collections/operations/create.ts`
   - **40-60行目**: 引数の展開とトランザクション初期化
   - **61-75行目**: beforeOperationフックの実行
   - **76-95行目**: アクセス制御のチェック
   - **96-150行目**: バリデーションとbeforeChangeフック
   - **151-200行目**: データベースへの挿入処理
   - **201-250行目**: afterChangeフックとバージョン保存

4. **Find操作の流れ**
   - `/packages/payload/src/collections/operations/find.ts`
   - **35-55行目**: クエリパラメータの正規化
   - **56-90行目**: アクセス制御によるwhere条件の追加
   - **91-130行目**: データベースクエリの実行
   - **131-180行目**: afterReadフックの実行

5. **DataLoaderの理解**
   - `/packages/payload/src/collections/dataloader.ts`
   - **1-30行目**: DataLoaderの初期化
   - **31-80行目**: バッチ処理によるN+1問題の解決

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

```
payload.create()
  |
  +-- buildBeforeOperation()
  |     +-- beforeOperation hooks
  |
  +-- executeAccess()
  |     +-- access.create()
  |
  +-- beforeValidate hooks
  |
  +-- validateFields()
  |     +-- field.validate()
  |
  +-- beforeChange hooks
  |
  +-- payload.db.create()
  |     +-- Database Adapter
  |
  +-- afterChange hooks
  |
  +-- saveVersion() [if versions enabled]
  |
  +-- afterRead hooks
  |
  +-- buildAfterOperation()
        +-- afterOperation hooks
```

### 4.3 データフロー図

```
[入力データ]
     |
     v
+----------------+
| beforeOperation|
+----------------+
     |
     v
+----------------+
| Access Control | --> [Forbidden Error]
+----------------+
     |
     v
+----------------+
| beforeValidate |
+----------------+
     |
     v
+----------------+
| Validation     | --> [ValidationError]
+----------------+
     |
     v
+----------------+
| beforeChange   |
+----------------+
     |
     v
+----------------+
| Database Layer |
+----------------+
     |
     v
+----------------+
| afterChange    |
+----------------+
     |
     v
+----------------+
| afterRead      |
+----------------+
     |
     v
+----------------+
| afterOperation |
+----------------+
     |
     v
[出力データ]
```

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

| ファイルパス | 種別 | 役割 |
|-------------|------|------|
| `/packages/payload/src/collections/config/types.ts` | 型定義 | コレクション設定の型定義 |
| `/packages/payload/src/collections/operations/create.ts` | 処理 | ドキュメント作成処理 |
| `/packages/payload/src/collections/operations/find.ts` | 処理 | ドキュメント検索処理 |
| `/packages/payload/src/collections/operations/findByID.ts` | 処理 | ID指定検索処理 |
| `/packages/payload/src/collections/operations/update.ts` | 処理 | ドキュメント更新処理 |
| `/packages/payload/src/collections/operations/delete.ts` | 処理 | ドキュメント削除処理 |
| `/packages/payload/src/collections/dataloader.ts` | ユーティリティ | バッチ読み込み最適化 |
| `/packages/payload/src/fields/hooks/afterRead/index.ts` | フック | afterReadフック処理 |
| `/packages/payload/src/fields/hooks/beforeChange/index.ts` | フック | beforeChangeフック処理 |

---

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

### 5.1 パフォーマンス考慮
- DataLoaderを使用してN+1問題を解決
- depth指定によるリレーション展開の制御
- ページネーションによる大量データの分割取得

### 5.2 セキュリティ考慮
- 全操作でアクセス制御を実行
- where条件によるドキュメントレベルのアクセス制御
- フィールドレベルのアクセス制御

### 5.3 拡張性考慮
- フックシステムによる処理のカスタマイズ
- カスタムバリデーションの追加
- データベースアダプターによる複数DBサポート

---

## 6. 変更履歴

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