# バッチ設計書 4-schedulePublish

## 概要

本ドキュメントは、Payloadのコンテンツ管理における予約公開タスク「schedulePublish」の設計仕様を定義する。このタスクは、指定日時にドキュメントやグローバルの公開・非公開を自動実行する責務を担う。

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

schedulePublishタスクは、コレクションドキュメントまたはグローバルデータの公開状態（_status）を指定日時に自動的に変更するジョブキュータスクである。

**業務上の目的・背景**：コンテンツ管理システムにおいて、マーケティングキャンペーンの開始、ニュースリリースの公開、イベント情報の掲載など、特定の日時にコンテンツを公開または非公開にする要件は頻繁に発生する。schedulePublishタスクは、この予約公開機能を提供し、コンテンツ運用の効率化と正確なタイミングでの公開を実現する。

**バッチの実行タイミング**：ジョブキューに登録されたwaitUntil時刻に到達後、runJobsバッチによって実行される。通常はコンテンツ編集時にユーザーが公開予定日時を設定し、その日時にジョブが実行される。

**主要な処理内容**：
1. ジョブ入力から公開/非公開タイプ、対象ドキュメント/グローバル情報を取得
2. ユーザー情報の復元（ジョブにユーザーIDが含まれている場合）
3. ロケール固有の公開設定の処理（publishSpecificLocale）
4. ドキュメントまたはグローバルの_statusフィールドを更新
5. 処理完了

**前後の処理との関連**：Admin UIでユーザーが公開予定を設定すると、schedulePublishタスクがキューに追加される。ドキュメント削除時やスケジュール変更時には、deleteScheduledPublishJobsによって既存の予約ジョブが削除される。

**影響範囲**：バージョン管理が有効なコレクションのドキュメント、およびグローバルデータの_statusフィールド。

## バッチ種別

コンテンツ管理処理（予約公開/非公開）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（予約日時に到達時） |
| 実行時刻 | waitUntilに設定された日時 |
| 実行曜日 | 予約設定に依存 |
| 実行日 | 予約設定に依存 |
| トリガー | ジョブキュー（runJobs経由） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| バージョン管理有効 | 対象コレクション/グローバルでversionsが有効であること |
| ジョブキュー有効化 | Payload設定でjobs設定が有効であること |
| waitUntil到達 | ジョブのwaitUntil時刻を経過していること |

### 実行可否判定

runJobsの標準的な実行可否判定に従う（completedAt未設定、hasError=false、processing=false、waitUntil条件充足）。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| type | 'publish' \| 'unpublish' | No | 'publish' | 公開または非公開 |
| locale | string | No | - | 特定ロケールのみ公開する場合 |
| doc | { value: ID, relationTo: string } | No | - | 対象ドキュメント（コレクション） |
| global | string | No | - | 対象グローバルのslug |
| user | ID | No | - | 操作実行ユーザーID |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| payload-jobs.input | JSON | ジョブ入力データ |
| adminUserSlug | 設定 | 管理者ユーザーコレクションslug |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 対象コレクション | DB | _statusフィールドの更新 |
| 対象グローバル | DB | _statusフィールドの更新 |

### 出力ファイル仕様

ファイル出力なし（データベース更新のみ）

## 処理フロー

### 処理シーケンス

```
1. 入力データの解析
   └─ type、locale、doc、global、userを取得
2. _statusの決定
   └─ type='publish'または未指定時は'published'、'unpublish'時は'draft'
3. ユーザー情報の復元（userが指定されている場合）
   └─ findByIDでユーザードキュメントを取得
4. ロケール設定の処理
   └─ localeが指定されている場合、localization設定と照合
5. ドキュメント更新（docが指定されている場合）
   └─ payload.updateで_statusを更新
6. グローバル更新（globalが指定されている場合）
   └─ payload.updateGlobalで_statusを更新
7. 処理完了
   └─ 空のoutputオブジェクトを返却
```

### フローチャート

```mermaid
flowchart TD
    A[タスク開始] --> B[入力データ解析]
    B --> C[_status決定]
    C --> D{user指定あり?}
    D -->|Yes| E[ユーザー情報取得]
    D -->|No| F{locale指定あり?}
    E --> F
    F -->|Yes| G[ロケール検証]
    F -->|No| H{doc指定あり?}
    G --> H
    H -->|Yes| I[ドキュメント更新]
    H -->|No| J{global指定あり?}
    I --> J
    J -->|Yes| K[グローバル更新]
    J -->|No| L[処理完了]
    K --> L
    L --> M[タスク終了]
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ユーザー取得 | adminUserSlug | SELECT | ユーザー情報の取得 |
| ドキュメント更新 | 対象コレクション | UPDATE | _statusフィールドの更新 |
| グローバル更新 | 対象グローバル | UPDATE | _statusフィールドの更新 |

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

#### 対象コレクション/グローバル

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | _status | 'published' または 'draft' | typeに基づく |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | NotFoundError | 対象ドキュメント/グローバルが存在しない | ジョブ削除または再作成 |
| - | AccessError | 更新権限がない（user未指定でoverrideAccess=false） | ユーザー権限の確認 |

### リトライ仕様

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

### 障害時対応

1. ジョブログでエラー内容を確認
2. 対象ドキュメント/グローバルの存在確認
3. 必要に応じて手動で_statusを更新

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 単一ドキュメント/グローバル更新 |
| コミットタイミング | 更新完了時 |
| ロールバック条件 | 更新処理中のエラー発生時 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1件/タスク実行 |
| 目標処理時間 | 数秒以内 |
| メモリ使用量上限 | depth=0により最小限 |

## 排他制御

- runJobsの標準的な排他制御に従う（processingフラグ）
- ドキュメント更新時のPayload標準のロック機構に依存

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| - | - | デフォルトではタスク固有のログ出力なし |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 失敗ジョブ数 | 設定による | 運用チーム |
| 予約公開遅延 | 設定による | 運用チーム |

## 備考

- user指定がない場合はoverrideAccess=trueで実行される
- user指定がある場合はそのユーザーの権限でアクセス制御が適用される
- publishSpecificLocaleオプションにより、特定ロケールのみを公開することが可能
- バージョン管理が無効なコレクションでは_statusフィールドが存在しないため使用不可
- inputSchemaにより、Admin UIでのジョブ入力フォームが自動生成される
