# バッチ設計書 1-PR Scheduler

## 概要

本ドキュメントは、PR Schedulerバッチ（process-scheduled-issues.yml）の設計仕様を記載したものである。このバッチは、スケジュールされたIssueを自動的に処理し、PR作成をトリガーするためのラベル付与を行う定期実行バッチである。

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

**業務上の目的・背景**：開発チームでは、定期的に実行すべきタスク（scheduled-taskラベル付きIssue）を事前に登録し、適切なタイミングで自動的にPR作成プロセスを開始する必要がある。手動でのラベル付け替え作業を自動化することで、運用負荷を軽減し、タスク処理の漏れを防止する。

**バッチの実行タイミング**：毎日22:00 JST（UTC 13:00）に日曜日から木曜日の間で定期実行される。また、手動実行（workflow_dispatch）も可能である。

**主要な処理内容**：
1. GitHub App Tokenを生成してAPIアクセス権限を取得
2. リポジトリ内の`scheduled-task`ラベルが付いたオープンIssueを作成日時の昇順で取得
3. 各Issueに対して`claude-create-pr`ラベルを付与し、`scheduled-task`ラベルを削除
4. 1回の実行で最大5件まで処理（レート制限対策）
5. エラー発生時はIssueにコメントを追加して通知

**前後の処理との関連**：本バッチで`claude-create-pr`ラベルが付与されると、Claude PR Creator（claude-pr-creator.yml）がトリガーされ、AIによる自動PR作成が開始される。

**影響範囲**：GitHubリポジトリのIssue（ラベルの変更）、Claude PR Creatorワークフローのトリガー

## バッチ種別

イベントトリガー / ラベル管理

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 日次（日〜木） |
| 実行時刻 | 22:00 JST（UTC 13:00） |
| 実行曜日 | 日曜日〜木曜日 |
| 実行日 | - |
| トリガー | cron / 手動（workflow_dispatch） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| GitHub App設定 | LIAM_CODE_ASSISTANT_APP_IDとPRIVATE_KEYがSecretsに設定されていること |
| ラベル存在 | `scheduled-task`および`claude-create-pr`ラベルがリポジトリに存在すること |

### 実行可否判定

- スケジュール時刻（UTC 13:00、日〜木）に自動実行
- `scheduled-task`ラベル付きのオープンIssueが存在しない場合は処理をスキップ
- Pull Requestは処理対象外（issue.pull_requestプロパティで判定）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| - | - | - | - | 入力パラメータなし |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| GitHub Issues API | JSON | `scheduled-task`ラベル付きオープンIssue一覧 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| GitHub Issue Labels | API操作 | `claude-create-pr`ラベル付与、`scheduled-task`ラベル削除 |
| GitHub Issue Comments | API操作 | エラー発生時のコメント追加 |

### 出力ファイル仕様

ファイル出力なし（GitHub APIを通じた操作のみ）

## 処理フロー

### 処理シーケンス

```
1. GitHub App Token生成
   └─ actions/create-github-app-token@v2.1.4を使用
2. scheduled-taskラベル付きIssue取得
   └─ issues.listForRepoでstate:open、labels:scheduled-taskを指定
   └─ 作成日時昇順でソート
3. 各Issueの処理（最大5件）
   └─ PRでないことを確認（issue.pull_requestをチェック）
   └─ claude-create-prラベルを付与
   └─ 100ms待機（レート制限対策）
   └─ scheduled-taskラベルを削除
   └─ 200ms待機（レート制限対策）
4. 処理完了ログ出力
   └─ 処理件数をコンソールに出力
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[GitHub App Token生成]
    B --> C[scheduled-task Issue取得]
    C --> D{Issue存在?}
    D -->|なし| E[処理なしで終了]
    D -->|あり| F[Issue処理ループ開始]
    F --> G{PRか?}
    G -->|はい| H[スキップ]
    G -->|いいえ| I{処理上限5件到達?}
    I -->|はい| J[ループ終了]
    I -->|いいえ| K[claude-create-prラベル付与]
    K --> L[scheduled-taskラベル削除]
    L --> M{エラー発生?}
    M -->|はい| N[エラーコメント追加]
    M -->|いいえ| O[処理カウント増加]
    H --> P{次のIssue?}
    N --> P
    O --> P
    P -->|あり| F
    P -->|なし| J
    J --> Q[処理件数ログ出力]
    Q --> R[バッチ終了]
    E --> R
```

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

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

データベース操作なし（GitHub APIのみ使用）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ラベル操作エラー | ラベル付与/削除失敗 | エラーコメントをIssueに追加、処理継続 |
| - | API Rate Limit | GitHub APIレート制限超過 | 100-200ms遅延で軽減、次回実行で処理 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし（エラー時はスキップして継続） |
| リトライ間隔 | - |
| リトライ対象エラー | - |

### 障害時対応

- 個別Issue処理失敗：該当Issueにエラーコメントが追加される。次回実行時に再処理される。
- ワークフロー全体失敗：GitHub Actionsの実行ログを確認し、原因を特定して手動で再実行する。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | Issue単位 |
| コミットタイミング | 各API呼び出し時 |
| ロールバック条件 | なし（GitHub APIはトランザクション非対応） |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 最大5件/回 |
| 目標処理時間 | 10分以内（timeout-minutes: 10） |
| メモリ使用量上限 | GitHub Actions標準ランナー制限内 |

## 排他制御

- concurrencyグループ: `${{ github.workflow }}-${{ github.ref }}`
- cancel-in-progress: true（同時実行時は先行ジョブをキャンセル）

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | バッチ開始時 | "Processing scheduled issues..." |
| 進捗ログ | Issue処理時 | "Processing issue #N: タイトル"、ラベル操作完了メッセージ |
| 終了ログ | バッチ終了時 | "Processed N issues in this run" |
| エラーログ | エラー発生時 | "Failed to process issue #N: エラーメッセージ" |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 処理時間 | 10分 | GitHub Actionsタイムアウト |
| エラー件数 | - | Issueコメント |

## 備考

- 金曜日・土曜日は実行されない設計（週末の自動PR作成を避けるため）
- 1回の実行で最大5件までの制限により、急激な負荷集中を防止
- エラー発生時も他のIssue処理を継続するフェイルセーフ設計
