# 機能設計書 41-Issue作成イベント

## 概要

本ドキュメントは、GitHubリポジトリでIssueが作成されたときにGiselleワークフローを自動起動するトリガーイベント機能の設計を記述する。

### 本機能の処理概要

GitHubでIssueが新規作成されたことをWebhookイベントとして受信し、設定されたワークフローを自動実行する機能である。

**業務上の目的・背景**：GitHubでのIssue管理において、Issue作成時に自動的にAIワークフローを起動することで、Issueの自動分類、自動応答、関連情報の収集など、開発プロセスの効率化を実現する。手動でのワークフロー起動を不要にし、リアルタイムな対応を可能にする。

**機能の利用シーン**：新しいIssueが作成された際に、AIによる自動トリアージ、ラベル提案、類似Issue検索、自動返信コメントの生成などを行う場面で利用される。例えば、バグ報告Issueが作成された際に自動的にログ収集の案内コメントを投稿するワークフローを構築できる。

**主要な処理内容**：
1. GitHubからのWebhook（issues.opened）を受信
2. リポジトリノードIDに基づいてトリガー設定を検索
3. イベント種別（github.issue.created）との一致を確認
4. Issueのタイトル、本文、番号をペイロードとして抽出
5. ワークフロータスクを作成・開始
6. 処理進捗をGitHubコメントとして投稿（オプション）

**関連システム・外部連携**：GitHub API（Webhook受信、リアクション追加、コメント投稿）、Giselle Storage（トリガー設定の永続化）

**権限による制御**：GitHub Appのインストール権限が必要。リポジトリへのread/write権限（issues、comments）が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 17 | ワークフローエディタ画面 | 主画面 | トリガーノードの追加・設定、GitHubイベント種別の選択 |
| 28 | インテグレーション設定画面 | 参照画面 | GitHubリポジトリ連携の管理 |

## 機能種別

イベント駆動処理 / Webhook処理 / データ連携

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| issueNumber | number | Yes | Issue番号 | 正の整数 |
| title | string | Yes | Issueのタイトル | 空文字列不可 |
| body | string | No | Issueの本文 | - |

### 入力データソース

- GitHub Webhook（issues.openedイベント）
- ペイロードに含まれるIssueデータ（issue.number、issue.title、issue.body）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| issueNumber | generated-text | Issue番号（文字列として出力） |
| title | generated-text | Issueのタイトル |
| body | generated-text | Issueの本文（空の場合は空文字列） |

### 出力先

- ワークフロー内の次のノードへの入力として接続
- トリガーノードの各出力ポートから接続先ノードへデータを伝播

## 処理フロー

### 処理シーケンス

```
1. Webhook受信
   └─ handleGitHubWebhookV2でHTTPリクエストを受信
2. イベント検証
   └─ Webhookシークレットによる署名検証
3. リポジトリ連携確認
   └─ repository.node_idからトリガー設定を検索
4. トリガー設定取得
   └─ flowTriggerIdからトリガーデータを取得
5. イベント種別照合
   └─ handleIssueOpenedでイベント種別を確認
6. リアクション追加
   └─ IssueにEYESリアクションを追加
7. タスク作成・開始
   └─ createAndStartTaskでワークフロー実行
8. ペイロード解決
   └─ resolveTriggerでIssueデータを出力に変換
9. 進捗通知（オプション）
   └─ 処理進捗をコメントとして投稿
```

### フローチャート

```mermaid
flowchart TD
    A[Webhook受信] --> B{署名検証}
    B -->|失敗| Z[処理終了]
    B -->|成功| C[リポジトリ連携確認]
    C --> D{トリガー設定存在?}
    D -->|No| Z
    D -->|Yes| E[トリガー設定取得]
    E --> F{イベント種別一致?}
    F -->|No| Z
    F -->|Yes| G[EYESリアクション追加]
    G --> H[タスク作成・開始]
    H --> I[ペイロード解決]
    I --> J[ワークフロー実行]
    J --> K[進捗通知]
    K --> L[完了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-41-01 | イベント種別照合 | Webhookイベントがissues.openedかつトリガー設定がgithub.issue.createdの場合のみ処理を実行 | 常時 |
| BR-41-02 | リアクション追加 | 処理開始時にIssueにEYESリアクションを追加して処理中であることを示す | トリガーが有効な場合 |
| BR-41-03 | 進捗コメント | shouldPostInProgressCommentがtrueの場合、処理進捗をコメントとして投稿 | 設定に基づく |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| トリガー設定取得 | Storage（JSON） | SELECT | flow-triggers/{triggerId}.jsonからトリガー設定を取得 |
| リポジトリ連携確認 | Storage（JSON） | SELECT | github-integration-indexes/{repositoryNodeId}.jsonから連携情報を取得 |

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

#### flow-triggers/{triggerId}.json

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | id, workspaceId, nodeId, configuration | triggerId一致 | トリガー設定全体を取得 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| E-41-01 | 認証エラー | GitHub認証情報が未設定 | integrationConfigsのgithub.authV2を確認 |
| E-41-02 | トリガー未設定 | リポジトリに対応するトリガーが存在しない | ワークフローエディタでトリガーを設定 |
| E-41-03 | 署名検証失敗 | Webhookシークレットが不一致 | Webhookシークレットの再設定 |

### リトライ仕様

- Webhook処理自体にリトライ機構はなし
- GitHub側のWebhook再送機能に依存（最大3回、指数バックオフ）

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

- 各処理ステップは独立して実行
- タスク作成・生成処理はStorage操作として個別にコミット
- エラー発生時は該当トリガーの処理のみスキップし、他のトリガーは継続処理

## パフォーマンス要件

- Webhook応答: 10秒以内（GitHub推奨）
- ペイロード解決: 1秒以内
- 複数トリガー並列処理: Promise.allによる並列実行

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

- Webhookシークレットによる署名検証必須
- GitHub App認証（Installation Token）による安全なAPI呼び出し
- プライベートキーの安全な管理（環境変数経由）

## 備考

- Issue本文（body）はオプショナルで、空の場合は空文字列として処理
- 同一リポジトリに複数のトリガーが設定されている場合、すべて並列実行

---

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

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

### 推奨読解順序

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

まず、Issue作成イベントのペイロード定義とトリガー設定の型を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | github.ts | `packages/trigger-registry/src/github.ts` | githubIssueCreatedEventの定義（19-30行目）、ペイロードスキーマ（issueNumber, title, body） |
| 1-2 | trigger.ts | `packages/protocol/src/node/operations/trigger.ts` | TriggerContentの型定義、トリガー状態の管理 |

**読解のコツ**: Zodスキーマの`.meta()`はUIラベル表示用のメタデータ。`z.coerce.number()`は文字列から数値への自動変換を示す。

#### Step 2: エントリーポイントを理解する

Webhook受信からイベント処理への流れを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | handle-webhook-v2.ts | `packages/giselle/src/github/handle-webhook-v2.ts` | handleGitHubWebhookV2関数（39-93行目）、サポートイベント一覧（25-37行目） |

**主要処理フロー**:
1. **46-49行目**: GitHub認証情報の取得と検証
2. **50-75行目**: dispatch関数の定義（イベント処理のメインロジック）
3. **88-92行目**: handleWebhookでWebhook署名検証とイベントディスパッチ

#### Step 3: イベントハンドラーを理解する

Issue作成イベントの具体的な処理ロジックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | event-handlers.ts | `packages/giselle/src/github/event-handlers.ts` | handleIssueOpened関数（165-181行目）、イベント種別の照合とリアクションNodeId取得 |
| 3-2 | event-handlers.ts | `packages/giselle/src/github/event-handlers.ts` | processEvent関数（478-813行目）、タスク作成とコールバック処理 |

**主要処理フロー**:
- **168-173行目**: Webhookイベントとトリガー設定のイベント種別照合
- **175-180行目**: Issue存在確認とリアクションNodeId取得
- **517-523行目**: EYESリアクション追加
- **562-806行目**: タスク作成・開始とコールバック設定

#### Step 4: ペイロード解決を理解する

Issueデータをワークフロー出力に変換する処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | trigger-utils.ts | `packages/giselle/src/github/trigger-utils.ts` | resolveIssueCreatedTrigger関数（38-81行目）、ペイロード各フィールドの処理 |
| 4-2 | resolve-trigger.ts | `packages/giselle/src/triggers/resolve-trigger.ts` | resolveTrigger関数（15-193行目）、トリガー解決のメインロジック |

**主要処理フロー**:
- **40-44行目**: イベント種別の確認（issues.openedかつgithub.issue.created）
- **45-79行目**: ペイロードフィールド（title, body, issueNumber）の解決
- **51-55行目**: titleフィールドの出力生成
- **60-64行目**: bodyフィールドの出力生成（nullの場合は空文字列）
- **69-73行目**: issueNumberフィールドの出力生成（文字列変換）

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

```
handleGitHubWebhookV2 (handle-webhook-v2.ts)
    │
    ├─ handleWebhook (github-tool)
    │      └─ Webhook署名検証
    │
    └─ process (handle-webhook-v2.ts:125-192)
           │
           ├─ getGitHubRepositoryIntegrationIndex
           │      └─ リポジトリ連携情報取得
           │
           └─ processEvent (event-handlers.ts:478-813)
                  │
                  ├─ handleIssueOpened (event-handlers.ts:165-181)
                  │      └─ イベント種別照合
                  │
                  ├─ addReaction
                  │      └─ EYESリアクション追加
                  │
                  └─ createAndStartTask
                         │
                         └─ resolveTrigger (resolve-trigger.ts)
                                │
                                └─ resolveIssueCreatedTrigger (trigger-utils.ts:38-81)
                                       └─ ペイロード解決
```

### データフロー図

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

GitHub Webhook ───────▶ handleGitHubWebhookV2 ───────▶ Giselle Task
(issues.opened)              │                           │
      │                      │                           │
      ▼                      ▼                           ▼
┌─────────────┐      ┌─────────────────┐       ┌────────────────────┐
│ issue.number│      │ processEvent    │       │ outputId: issueNumber │
│ issue.title │  ──▶ │ handleIssueOpened│  ──▶ │ outputId: title    │
│ issue.body  │      │ resolveTrigger  │       │ outputId: body     │
└─────────────┘      └─────────────────┘       └────────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| github.ts | `packages/trigger-registry/src/github.ts` | ソース | GitHubイベント定義（ペイロードスキーマ） |
| handle-webhook-v2.ts | `packages/giselle/src/github/handle-webhook-v2.ts` | ソース | Webhook受信エントリーポイント |
| event-handlers.ts | `packages/giselle/src/github/event-handlers.ts` | ソース | イベントハンドラー群 |
| trigger-utils.ts | `packages/giselle/src/github/trigger-utils.ts` | ソース | トリガーペイロード解決 |
| resolve-trigger.ts | `packages/giselle/src/triggers/resolve-trigger.ts` | ソース | トリガー解決メインロジック |
| utils.ts | `packages/giselle/src/triggers/utils.ts` | ソース | トリガー設定の読み書き |
| trigger.ts | `packages/protocol/src/node/operations/trigger.ts` | ソース | トリガーノード型定義 |
| index.ts | `packages/trigger-registry/src/index.ts` | ソース | トリガーレジストリエクスポート |
