# バッチ設計書 10-createCollectionExport

## 概要

本ドキュメントは、Payloadのインポート/エクスポートプラグインにおけるコレクションエクスポートタスク「createCollectionExport」の設計仕様を定義する。このタスクは、コレクションデータをCSV/JSON形式でバッチエクスポートする責務を担う。

### 本バッチの処理概要

createCollectionExportタスクは、指定されたコレクションのドキュメントをCSVまたはJSON形式でファイルにエクスポートするジョブキュータスクである。ページネーションに対応し、大量のデータを効率的に処理できる。

**業務上の目的・背景**：コンテンツ管理において、データのバックアップ、外部システムへのデータ連携、データ分析用のエクスポート、移行作業など、コレクションデータを外部ファイルとして出力する要件は頻繁に発生する。createCollectionExportタスクは、これらの要件に対応する汎用的なエクスポート機能を提供する。

**バッチの実行タイミング**：Admin UIからのエクスポート操作時、または直接ジョブキューにキューイングされた時。runJobsバッチによって実行される。

**主要な処理内容**：
1. ジョブ入力からエクスポート設定を取得（コレクション、形式、フィルター等）
2. ユーザー情報の復元（アクセス制御用）
3. バッチプロセッサによるドキュメントの分割取得
4. CSV/JSON形式への変換（flattenObject、フィールド変換）
5. 無効フィールドのフィルタリング
6. エクスポートファイルの生成・保存
7. ストリーミングエクスポート（download=true時）

**前後の処理との関連**：Admin UIのエクスポートダイアログから呼び出される。exportBatchProcessorと連携してバッチ単位での処理を行う。

**影響範囲**：エクスポートコレクション（ファイル保存）、対象コレクション（読み取りのみ）。

## バッチ種別

データエクスポート処理（バッチファイル生成）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（ユーザー操作時） |
| 実行時刻 | ジョブキュー実行時 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | ジョブキュー（Admin UI経由） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| プラグイン有効化 | plugin-import-exportが有効であること |
| ジョブキュー有効化 | Payload設定でjobs設定が有効であること |
| ユーザー認証 | エクスポート実行ユーザーが認証されていること |

### 実行可否判定

runJobsの標準的な実行可否判定に従う。ユーザーのコレクション読み取り権限によりエクスポート可能なドキュメントが制限される。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| id | string | Yes | - | エクスポートドキュメントID |
| name | string | Yes | - | 出力ファイル名（拡張子なし） |
| collectionSlug | string | Yes | - | エクスポート対象コレクションslug |
| exportCollection | string | Yes | - | エクスポートファイル保存先コレクション |
| format | 'csv' \| 'json' | Yes | - | 出力形式 |
| batchSize | number | No | 100 | バッチあたりの処理件数 |
| drafts | 'yes' \| 'no' | No | 'no' | ドラフトを含めるか |
| fields | string[] | No | - | エクスポートするフィールド（省略時は全フィールド） |
| limit | number | No | - | エクスポート件数上限 |
| locale | string | No | - | 対象ロケール（'all'で全ロケール） |
| maxLimit | number | No | - | プラグイン設定による最大件数 |
| page | number | No | 1 | 開始ページ |
| sort | string | No | - | ソート順 |
| userCollection | string | No | - | ユーザーコレクション |
| userID | string | No | - | 実行ユーザーID |
| where | object | No | {} | フィルター条件 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| 対象コレクション | DB | エクスポート対象のドキュメント |
| プラグイン設定 | 設定 | エクスポート設定（disabledFields等） |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| エクスポートコレクション | DB/ファイル | 生成されたCSV/JSONファイル |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | `{name}-{collectionSlug}.{format}` |
| 出力先 | エクスポートコレクション（アップロードコレクション） |
| 文字コード | UTF-8（CSV: BOM付き） |
| 区切り文字 | カンマ（CSV） |

## 処理フロー

### 処理シーケンス

```
1. ジョブ入力の解析
   └─ エクスポート設定、ユーザー情報の取得
2. ユーザー情報の復元
   └─ userID/userCollectionからユーザードキュメントを取得
3. エクスポート設定の構築
   └─ where条件、draft設定、ロケール設定
4. バッチプロセッサの作成
   └─ createExportBatchProcessor
5. ドキュメントの取得と変換
   └─ payload.findで分割取得、flattenObjectで平坦化
6. 無効フィールドのフィルタリング
   └─ disabledFieldsに基づくフィルタリング
7. CSV/JSONへの変換
   └─ csv-stringifyまたはJSON.stringify
8. ファイルの保存
   └─ payload.updateでエクスポートドキュメントを更新
```

### フローチャート

```mermaid
flowchart TD
    A[タスク開始] --> B{入力データあり?}
    B -->|No| C[エラーログ出力]
    C --> D[空のoutput返却]
    B -->|Yes| E[ユーザー情報復元]
    E --> F[エクスポート設定構築]
    F --> G{download?}
    G -->|Yes| H[ストリーミングエクスポート]
    G -->|No| I[バッチプロセッサ作成]
    I --> J[ドキュメント取得ループ]
    J --> K[flattenObject変換]
    K --> L[無効フィールドフィルタ]
    L --> M{次のバッチあり?}
    M -->|Yes| J
    M -->|No| N{CSV?}
    N -->|Yes| O[CSV生成]
    N -->|No| P[JSON生成]
    O --> Q[ファイル保存]
    P --> Q
    Q --> R[タスク完了]
    H --> R
```

## データベース操作仕様

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ユーザー取得 | userCollection | SELECT | ユーザー情報の取得 |
| ドキュメント取得 | 対象コレクション | SELECT | エクスポート対象の取得 |
| ファイル保存 | エクスポートコレクション | UPDATE | 生成ファイルの保存 |

### テーブル別操作詳細

#### 対象コレクション

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | * | where条件、_status条件 | バッチ単位で取得 |

#### エクスポートコレクション

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | file | 生成されたCSV/JSONファイル | overrideAccess=true |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | APIError | コレクションが存在しない | コレクションslugの確認 |
| - | APIError | ユーザー認証が必要 | ユーザー情報の確認 |
| - | アクセス拒否 | 読み取り権限がない | 権限設定の確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | タスク設定による（デフォルト動作） |
| リトライ間隔 | タスク設定による |
| リトライ対象エラー | 一時的なエラー（DB接続エラー等） |

### 障害時対応

1. ジョブログでエラー内容を確認
2. コレクション設定、ユーザー権限を確認
3. 必要に応じてエクスポート設定を修正して再実行

## トランザクション仕様

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | ファイル保存時（単一更新） |
| コミットタイミング | ファイル保存完了時 |
| ロールバック条件 | 保存処理中のエラー発生時 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | maxLimitまたはlimitによる制限 |
| 目標処理時間 | データ量に依存 |
| メモリ使用量上限 | batchSizeで制御（デフォルト100件/バッチ） |

## 排他制御

- runJobsの標準的な排他制御に従う（processingフラグ）
- 同一エクスポートドキュメントへの同時アクセスはファイル上書きとなる

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| エラーログ | 入力なし時 | `No input provided to createCollectionExport task` |
| デバッグログ | 各処理ステップ | debug=true時のみ詳細ログ |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| エクスポート失敗 | 設定による | 運用チーム |
| 処理時間 | 設定による | 運用チーム |

## 備考

- **バッチ処理**：batchSizeで指定された件数ごとにドキュメントを取得・処理
- **ストリーミング**：download=true時はReadableストリームで直接レスポンス
- **フィールドフィルタリング**：disabledFieldsでエクスポートから除外するフィールドを指定可能
- **ロケール対応**：locale='all'で全ロケールのデータをエクスポート
- **CSV形式**：BOM付きUTF-8、カンマ区切り、csv-stringifyライブラリ使用
- **JSON形式**：配列形式、改行区切り
- **アクセス制御**：ユーザーの読み取り権限に基づいてエクスポート対象を制限
- **maxLimit**：プラグイン設定で最大エクスポート件数を制限可能
- inputSchemaによりAdmin UIでのジョブ入力フォームが自動生成される
