# 機能設計書 51-PRオープンイベント

## 概要

本ドキュメントは、GitHubでPull Request（PR）がオープンされたときにGiselleワークフローを自動起動するトリガーイベント機能について記述する。

### 本機能の処理概要

GitHubリポジトリでPull Requestが新規作成（オープン）されたときに、事前に設定されたGiselleワークフローを自動的に起動する機能である。これにより、PRの自動レビュー、自動ラベル付け、自動コメント投稿などの自動化処理が可能となる。

**業務上の目的・背景**：ソフトウェア開発において、Pull Requestは重要なコードレビュープロセスの起点である。PRが作成されるたびに手動でレビューを開始したり、特定のチェックを実行したりすることは非効率であり、見落としが発生する可能性がある。本機能により、PRオープン時に自動的にワークフローを起動することで、レビュープロセスの効率化と品質向上を実現する。

**機能の利用シーン**：
- PRが作成されたときに自動的にコードスタイルチェックを実行
- PRの内容に基づいて適切なラベルを自動付与
- PRの説明文が不足している場合に警告コメントを自動投稿
- AIによる自動コードレビューを実行

**主要な処理内容**：
1. GitHubからのWebhookイベント（pull_request.opened）を受信
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.openedイベント）

## 出力仕様

### 出力データ

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

### フローチャート

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

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-51-01 | イベント識別子 | イベントIDは`github.pull_request.opened`固定 | 常時 |
| BR-51-02 | 必須フィールド | title、number、diff、pullRequestUrlは必須 | 常時 |
| BR-51-03 | 本文オプション | bodyフィールドはオプション（空の場合あり） | 常時 |

### 計算ロジック

特になし

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

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

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

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

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

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

## パフォーマンス要件

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

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

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

## 備考

- イベントIDは`github.pull_request.opened`として一意に識別される
- 本イベントは条件設定（コールサインやラベル）を持たない

---

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

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

### 推奨読解順序

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

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

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

**読解のコツ**: Zodスキーマの`z.object()`で定義されたペイロード構造に注目。`.meta({ label: "..." })`はUIでの表示ラベルを指定している。

**主要処理フロー**:
- **180-193行目**: `githubPullRequestOpenedEvent`オブジェクト定義
  - `id`: イベント識別子（`github.pull_request.opened`）
  - `label`: UI表示用ラベル（`Pull Request Opened`）
  - `payload`: Zodスキーマによるペイロード定義

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | github.ts | `packages/protocol/src/trigger/github.ts` | GitHubEventDataの判別共用体定義を理解 |

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

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | github.ts | `packages/trigger-registry/src/github.ts` | githubEventsオブジェクトとヘルパー関数 |

**主要処理フロー**:
- **210-226行目**: `githubEvents`オブジェクト - 全イベントの集約
- **228行目**: `GitHubEventId`型定義
- **232-234行目**: `isGitHubEventId`型ガード関数

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

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

### データフロー図

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

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

ペイロード:              Zodスキーマ適用:                  トリガー出力:
- action: "opened"       - 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ハンドリング処理 |
