# 機能設計書：フィールドシステム

## 1. 機能概要

### 1.1 機能の目的
フィールドシステムは、Payload CMSにおけるデータスキーマを定義する中核機能である。テキスト、数値、リレーション、アップロードなど多様なフィールドタイプを提供し、コレクションおよびグローバルのデータ構造を柔軟に定義できる。

### 1.2 機能の範囲
- 多様なフィールドタイプの提供
- フィールドバリデーション
- フィールドレベルのアクセス制御
- フィールドフック処理
- 条件付き表示・必須制御
- ローカライゼーション対応

### 1.3 関連画面
| 画面ID | 画面名 | 関連操作 |
|--------|--------|----------|
| ADM-003 | ドキュメント作成 | フィールド入力 |
| ADM-004 | ドキュメント編集 | フィールド編集 |

---

## 2. 機能仕様

### 2.1 サポートされるフィールドタイプ

| フィールドタイプ | 説明 | データ型 |
|-----------------|------|----------|
| text | 単一行テキスト | string |
| textarea | 複数行テキスト | string |
| number | 数値 | number |
| email | メールアドレス | string |
| code | コードエディタ | string |
| json | JSONデータ | object |
| richText | リッチテキスト | object (Lexical/Slate) |
| date | 日付・時刻 | string (ISO8601) |
| checkbox | チェックボックス | boolean |
| select | セレクトボックス | string / string[] |
| radio | ラジオボタン | string |
| point | 地理座標 | [number, number] |
| upload | ファイルアップロード | string (relation) |
| relationship | リレーション | string / string[] |
| array | 配列 | object[] |
| blocks | ブロック | object[] |
| group | グループ | object |
| row | 行レイアウト | - (レイアウト用) |
| collapsible | 折りたたみ | - (レイアウト用) |
| tabs | タブ | - (レイアウト用) |
| join | ジョイン | object[] (仮想) |

### 2.2 共通フィールドオプション

```typescript
interface FieldBase {
  name: string;                    // フィールド名（必須）
  label?: string | object;         // 表示ラベル
  required?: boolean;              // 必須フラグ
  unique?: boolean;                // 一意制約
  index?: boolean;                 // インデックス作成
  hidden?: boolean;                // 管理画面で非表示
  localized?: boolean;             // ローカライズ対応

  // アクセス制御
  access?: {
    create?: AccessFunction;
    read?: AccessFunction;
    update?: AccessFunction;
  };

  // フック
  hooks?: {
    beforeValidate?: FieldHook[];
    beforeChange?: FieldHook[];
    afterChange?: FieldHook[];
    afterRead?: FieldHook[];
  };

  // バリデーション
  validate?: ValidateFunction;

  // 条件制御
  admin?: {
    condition?: ConditionFunction;
    description?: string;
    readOnly?: boolean;
    disabled?: boolean;
    components?: {
      Field?: Component;
      Cell?: Component;
      Filter?: Component;
    };
  };

  // デフォルト値
  defaultValue?: any | DefaultValueFunction;
}
```

### 2.3 フィールドタイプ別の追加オプション

#### 2.3.1 Text / Textarea
```typescript
{
  type: 'text' | 'textarea';
  minLength?: number;
  maxLength?: number;
  hasMany?: boolean;  // 複数値許可
}
```

#### 2.3.2 Number
```typescript
{
  type: 'number';
  min?: number;
  max?: number;
  hasMany?: boolean;
}
```

#### 2.3.3 Select / Radio
```typescript
{
  type: 'select' | 'radio';
  options: Array<{
    label: string;
    value: string;
  }>;
  hasMany?: boolean;  // selectのみ
}
```

#### 2.3.4 Relationship
```typescript
{
  type: 'relationship';
  relationTo: string | string[];  // 関連コレクション
  hasMany?: boolean;
  filterOptions?: FilterOptions;
  maxDepth?: number;
}
```

#### 2.3.5 Array
```typescript
{
  type: 'array';
  fields: Field[];
  minRows?: number;
  maxRows?: number;
}
```

#### 2.3.6 Blocks
```typescript
{
  type: 'blocks';
  blocks: Block[];
  minRows?: number;
  maxRows?: number;
}
```

### 2.4 バリデーションルール

| ルール | 適用フィールド | 説明 |
|--------|---------------|------|
| required | 全フィールド | 値の存在チェック |
| minLength | text, textarea | 最小文字数 |
| maxLength | text, textarea | 最大文字数 |
| min | number | 最小値 |
| max | number | 最大値 |
| minRows | array, blocks | 最小行数 |
| maxRows | array, blocks | 最大行数 |
| unique | 全フィールド | 一意性チェック |
| validate | 全フィールド | カスタムバリデーション |

### 2.5 処理フロー

```
[フィールド値の保存フロー]
1. beforeValidate フック実行
2. requiredバリデーション
3. タイプ別バリデーション
4. カスタムバリデーション
5. beforeChange フック実行
6. 値の変換・正規化
7. データベースへの保存
8. afterChange フック実行
```

```
[フィールド値の読み取りフロー]
1. データベースからの取得
2. afterRead フック実行
3. アクセス制御によるフィルタリング
4. リレーション展開（depth指定時）
5. 値の返却
```

---

## 3. データ設計

### 3.1 フィールド定義スキーマ
```typescript
type Field =
  | TextField
  | TextareaField
  | NumberField
  | EmailField
  | CodeField
  | JSONField
  | RichTextField
  | DateField
  | CheckboxField
  | SelectField
  | RadioField
  | PointField
  | UploadField
  | RelationshipField
  | ArrayField
  | BlocksField
  | GroupField
  | RowField
  | CollapsibleField
  | TabsField
  | JoinField;
```

### 3.2 フィールド値のストレージ形式

| フィールドタイプ | MongoDB | PostgreSQL |
|-----------------|---------|------------|
| text | String | VARCHAR/TEXT |
| number | Number | INTEGER/DECIMAL |
| date | Date | TIMESTAMP |
| relationship | ObjectId | INTEGER (FK) |
| array | Array | JSONB / 別テーブル |
| blocks | Array | JSONB |

---

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

### 4.1 推奨読解順序

1. **型定義の理解**
   - `/packages/payload/src/fields/config/types.ts`
   - **1-100行目**: Field基底型とFieldBase定義
   - **101-200行目**: 各フィールドタイプの定義
   - **201-300行目**: FieldHook、ValidateFunction等のユーティリティ型

2. **フィールドバリデーション**
   - `/packages/payload/src/fields/validations.ts`
   - 各フィールドタイプごとのバリデーション関数

3. **フィールドフック処理**
   - `/packages/payload/src/fields/hooks/beforeChange/index.ts`
   - `/packages/payload/src/fields/hooks/afterRead/index.ts`
   - フックの実行順序とデータ変換処理

4. **フィールドのサニタイズ**
   - `/packages/payload/src/fields/config/sanitize.ts`
   - フィールド定義の正規化処理

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

```
validateFields()
  |
  +-- traverseFields()
  |     |
  |     +-- validateField() [各フィールド]
  |           |
  |           +-- field.validate() [カスタム]
  |           |
  |           +-- requiredValidation()
  |           |
  |           +-- typeValidation()
  |                 |
  |                 +-- text: minLength/maxLength
  |                 +-- number: min/max
  |                 +-- array: minRows/maxRows
  |                 ...
  |
  +-- ValidationError [エラー時]
```

```
beforeChange hooks
  |
  +-- traverseFields()
        |
        +-- fieldHook.beforeChange() [各フィールド]
              |
              +-- 値の変換
              +-- 関連データの処理
              +-- ファイルの処理 (upload)
```

### 4.3 データフロー図

```
[入力値]
     |
     v
+------------------+
| beforeValidate   |
| フック           |
+------------------+
     |
     v
+------------------+
| required         |
| チェック         |
+------------------+
     |
     v
+------------------+
| タイプ別         |
| バリデーション   |
+------------------+
     |
     v
+------------------+
| カスタム         |
| バリデーション   |
+------------------+
     |
     v
+------------------+
| beforeChange     |
| フック           |
+------------------+
     |
     v
+------------------+
| 値の正規化       |
+------------------+
     |
     v
[保存値]
```

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

| ファイルパス | 種別 | 役割 |
|-------------|------|------|
| `/packages/payload/src/fields/config/types.ts` | 型定義 | フィールド型定義 |
| `/packages/payload/src/fields/validations.ts` | バリデーション | バリデーション関数 |
| `/packages/payload/src/fields/hooks/beforeChange/index.ts` | フック | beforeChangeフック処理 |
| `/packages/payload/src/fields/hooks/afterRead/index.ts` | フック | afterReadフック処理 |
| `/packages/payload/src/fields/config/sanitize.ts` | ユーティリティ | フィールド定義の正規化 |
| `/packages/payload/src/fields/traverseFields.ts` | ユーティリティ | フィールドの再帰処理 |

---

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

### 5.1 パフォーマンス考慮
- 深いネスト（array内のarray等）のパフォーマンス影響
- リレーション展開（depth）によるN+1問題をDataLoaderで解決

### 5.2 セキュリティ考慮
- フィールドレベルのアクセス制御
- hiddenフィールドのAPI応答からの除外
- ファイルアップロードのMIMEタイプ検証

### 5.3 拡張性考慮
- カスタムフィールドタイプの追加
- カスタムバリデーション関数
- カスタムフックによる処理の拡張

---

## 6. 変更履歴

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