# 機能設計書 52-PRレビュー準備完了イベント

## 概要

本ドキュメントは、GitHubでPull Request（PR）がレビュー準備完了状態になったときにGiselleワークフローを自動起動するトリガーイベント機能について記述する。

### 本機能の処理概要

GitHubリポジトリでPull Requestがドラフト状態から「Ready for Review」状態に変更されたときに、事前に設定されたGiselleワークフローを自動的に起動する機能である。ドラフトPRは作業中であり、レビュー準備が整った時点で初めてレビューワークフローを開始することで、不要な処理を防ぎ効率的なワークフロー運用が可能となる。

**業務上の目的・背景**：GitHubのドラフトPR機能を活用するチームでは、PRのレビュー準備が整った段階で初めてレビュープロセスを開始したい場合がある。ドラフト状態のPRに対してレビューワークフローを実行すると、作業途中のコードがレビューされてしまい非効率である。本機能により、レビュー準備完了時にのみワークフローを起動し、適切なタイミングでのレビュー開始を実現する。

**機能の利用シーン**：
- ドラフトPRがレビュー準備完了になったときにレビュアーに通知
- レビュー準備完了PRに対してAI自動レビューを実行
- レビュー準備完了時にCIパイプラインの追加チェックを起動
- レビューチェックリストの自動投稿

**主要な処理内容**：
1. GitHubからのWebhookイベント（pull_request.ready_for_review）を受信
2. イベントペイロードからPR情報（タイトル、本文、番号、Diff、URL）を抽出
3. 抽出したデータをワークフローの入力パラメータとして設定
4. 対応するGiselleワークフローを起動

**関連システム・外部連携**：GitHub API（Webhook経由）

**権限による制御**：GitHub Appのインストール権限とリポジトリアクセス権限が必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 17 | ワークフローエディタ画面 | 主画面 | トリガーノードの設定でPRレビュー準備完了イベントを選択 |

## 機能種別

イベントトリガー / データ連携

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| title | string | Yes | Pull Requestのタイトル | 空文字不可 |
| body | string | No | Pull Requestの本文 | - |
| number | number | Yes | Pull Request番号 | 正の整数 |
| diff | string | Yes | Pull Requestの差分（Diff形式） | 空文字不可 |
| pullRequestUrl | string | Yes | Pull RequestのURL | URL形式 |

### 入力データソース

GitHubからのWebhookペイロード（pull_request.ready_for_reviewイベント）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| title | string | Pull Requestのタイトル |
| body | string | Pull Requestの本文（オプション） |
| number | number | Pull Request番号 |
| diff | string | Pull Requestの差分 |
| pullRequestUrl | string | Pull RequestのURL |

### 出力先

Giselleワークフローのトリガーノード出力として後続ノードに渡される

## 処理フロー

### 処理シーケンス

```
1. GitHubがWebhookイベントを送信
   └─ pull_request.ready_for_reviewイベントが発生時に自動送信
2. Giselleがイベントを受信
   └─ handleGitHubWebhookV2関数でイベントを処理
3. イベントタイプを判定
   └─ github.pull_request.ready_for_reviewであることを確認
4. ペイロードからデータを抽出
   └─ Zodスキーマに基づいてバリデーション・パース
5. ワークフローを起動
   └─ トリガーノードの出力として後続処理に渡す
```

### フローチャート

```mermaid
flowchart TD
    A[GitHub PR Ready for Review] --> B[Webhook送信]
    B --> C{イベントタイプ判定}
    C -->|ready_for_review| D[ペイロード抽出]
    C -->|その他| E[処理スキップ]
    D --> F[Zodバリデーション]
    F -->|成功| G[ワークフロー起動]
    F -->|失敗| H[エラーログ出力]
    G --> I[後続ノード実行]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-52-01 | イベント識別子 | イベントIDは`github.pull_request.ready_for_review`固定 | 常時 |
| BR-52-02 | 必須フィールド | title、number、diff、pullRequestUrlは必須 | 常時 |
| BR-52-03 | 本文オプション | bodyフィールドはオプション（空の場合あり） | 常時 |
| BR-52-04 | ドラフト解除時のみ | ドラフトPRがレビュー準備完了に変更されたときのみ発火 | 常時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| イベント定義 | - | 参照（メモリ） | イベント定義はコード内で静的に定義 |

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

本機能はデータベース操作を直接行わない。イベント定義はソースコード内で静的に管理される。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| VALIDATION_ERROR | バリデーションエラー | ペイロードが不正な形式 | ログ出力後、処理をスキップ |
| WEBHOOK_SIGNATURE_ERROR | 認証エラー | Webhook署名検証失敗 | リクエストを拒否 |

### リトライ仕様

GitHubのWebhook仕様に従い、失敗時はGitHub側で自動リトライが行われる

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

本機能単体ではトランザクション管理は不要（イベント受信・変換のみ）

## パフォーマンス要件

- イベント受信から処理開始まで: 100ms以内
- ペイロードパース処理: 10ms以内

## セキュリティ考慮事項

- Webhook署名検証によりリクエストの正当性を確認
- GitHub Appの適切な権限設定が必要
- ペイロードに含まれる機密情報（トークン等）は含まれない設計

## 備考

- イベントIDは`github.pull_request.ready_for_review`として一意に識別される
- PRオープンイベント（No.51）と同じペイロード構造を持つ
- 本イベントは条件設定（コールサインやラベル）を持たない

---

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

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

まず、イベントのペイロード構造を定義するZodスキーマを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | github.ts | `packages/trigger-registry/src/github.ts` | githubPullRequestReadyForReviewEventオブジェクトの構造を理解 |

**読解のコツ**: Zodスキーマの`z.object()`で定義されたペイロード構造に注目。PRオープンイベントと同一構造であることを確認。

**主要処理フロー**:
- **195-208行目**: `githubPullRequestReadyForReviewEvent`オブジェクト定義
  - `id`: イベント識別子（`github.pull_request.ready_for_review`）
  - `label`: UI表示用ラベル（`Pull Request Ready for Review`）
  - `payload`: Zodスキーマによるペイロード定義（PRオープンイベントと同一構造）

#### Step 2: プロトコル層の統合を理解する

トリガーレジストリで定義されたイベントがプロトコル層でどのように統合されるかを確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | github.ts | `packages/protocol/src/trigger/github.ts` | GitHubEventPullRequestReadyForReviewDataの定義 |

**主要処理フロー**:
- **58-60行目**: `GitHubEventPullRequestReadyForReviewData`の定義
- **84-97行目**: `GitHubEventData`として他のイベントと統合

#### Step 3: イベントレジストリの構造を理解する

全GitHubイベントがどのように管理されているかを確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | github.ts | `packages/trigger-registry/src/github.ts` | githubEventsオブジェクトへの登録 |

**主要処理フロー**:
- **224-225行目**: `githubPullRequestReadyForReviewEvent`がgithubEventsに登録

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

```
GitHubからのWebhook
    │
    ├─ handleGitHubWebhookV2 (packages/giselle/src/github)
    │      │
    │      └─ イベントタイプ判定
    │             │
    │             └─ githubPullRequestReadyForReviewEvent.payload.parse()
    │
    └─ ワークフロー起動
           └─ トリガーノード出力設定
```

### データフロー図

```
[入力]                         [処理]                           [出力]

GitHub Webhook         ───▶ handleGitHubWebhookV2    ───▶ ワークフロー入力
(Ready for Review)           │                              パラメータ
                             ├─ イベントタイプ判定
                             ├─ ペイロードパース
                             └─ バリデーション

ペイロード:                   Zodスキーマ適用:                  トリガー出力:
- action: "ready_for_review"  - title: string                   - title
- pull_request:               - body?: string                   - body
  - title                    - number: number                  - number
  - body                     - diff: string                    - diff
  - number                   - pullRequestUrl: string          - pullRequestUrl
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| github.ts | `packages/trigger-registry/src/github.ts` | ソース | GitHubイベント定義（PRレビュー準備完了イベント含む） |
| github.ts | `packages/protocol/src/trigger/github.ts` | ソース | プロトコル層でのGitHubイベント統合 |
| handle-webhook-v2.ts | `packages/giselle/src/github/handle-webhook-v2.ts` | ソース | Webhookハンドリング処理 |
