# 機能設計書 43-Issueコメント作成イベント

## 概要

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

### 本機能の処理概要

GitHubでIssueにコメントが追加されたことをWebhookイベントとして受信し、特定のコールサイン（呼び出しキーワード）が含まれる場合にワークフローを自動実行する機能である。

**業務上の目的・背景**：Issueへのコメントを通じてAIワークフローを起動することで、対話型の自動応答システムを構築できる。ユーザーは特定のコールサインを使ってAIに質問したり、タスクを依頼したりできる。これにより、Issue上でのコミュニケーション効率が向上し、開発者の負担軽減につながる。

**機能の利用シーン**：Issueにコメントで「@giselle-bot 〜してください」などのコールサインを含めることで、AIが自動的に応答を生成する場面で利用される。例えば、バグ報告Issueに「@giselle-bot この問題の原因を調査してください」とコメントすると、AIがコード分析を行い結果をコメントとして返信するワークフローを構築できる。

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

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

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

## 関連画面

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

## 機能種別

イベント駆動処理 / Webhook処理 / データ連携 / 条件分岐処理

## 入力仕様

### 入力パラメータ

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

### 入力データソース

- GitHub Webhook（issue_comment.createdイベント）
- ペイロードに含まれるIssueデータ（issue.number、issue.title、issue.body）
- ペイロードに含まれるコメントデータ（comment.body）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| issueNumber | generated-text | Issue番号（文字列として出力） |
| issueTitle | generated-text | Issueのタイトル |
| issueBody | generated-text | Issueの本文（空の場合は空文字列） |
| body | generated-text | コメント本文（コールサイン部分を除いた内容） |

### 出力先

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

## 処理フロー

### 処理シーケンス

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

### フローチャート

```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[コールサイン抽出]
    G --> H{コールサイン一致?}
    H -->|No| Z
    H -->|Yes| I[EYESリアクション追加]
    I --> J[タスク作成・開始]
    J --> K[ペイロード解決]
    K --> L[ワークフロー実行]
    L --> M[進捗通知]
    M --> N[完了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-43-01 | イベント種別照合 | Webhookイベントがissue_comment.createdかつトリガー設定がgithub.issue_comment.createdの場合のみ処理を実行 | 常時 |
| BR-43-02 | コールサイン照合 | コメント内のコールサインがトリガー設定のconditions.callsignと一致する場合のみ処理を実行 | 常時 |
| BR-43-03 | リアクション追加 | 処理開始時にコメントにEYESリアクションを追加して処理中であることを示す | トリガーが有効な場合 |
| BR-43-04 | コールサイン除去 | 出力のbodyフィールドにはコールサイン部分を除いたコメント内容を設定 | 常時 |
| BR-43-05 | 進捗コメント | shouldPostInProgressCommentがtrueの場合、処理進捗をコメントとして投稿 | 設定に基づく |

### 計算ロジック

- コールサイン解析: `parseCommand(comment.body)` でコールサインと内容を分離
- コールサイン形式: コメント先頭の`/callsign`形式を検出

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| トリガー設定取得 | 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-43-01 | 認証エラー | GitHub認証情報が未設定 | integrationConfigsのgithub.authV2を確認 |
| E-43-02 | トリガー未設定 | リポジトリに対応するトリガーが存在しない | ワークフローエディタでトリガーを設定 |
| E-43-03 | 署名検証失敗 | Webhookシークレットが不一致 | Webhookシークレットの再設定 |
| E-43-04 | コールサイン不一致 | コメントに設定されたコールサインが含まれない | 正しいコールサインを使用 |

### リトライ仕様

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

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

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

## パフォーマンス要件

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

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

- Webhookシークレットによる署名検証必須
- GitHub App認証（Installation Token）による安全なAPI呼び出し
- プライベートキーの安全な管理（環境変数経由）
- コールサインによるアクセス制御（不正な起動を防止）

## 備考

- Issue本文（issueBody）はオプショナルで、空の場合は空文字列として処理
- コメント本文（body）はコールサイン部分を除去した内容が出力される
- Pull Requestへのコメントは別イベント（github.pull_request_comment.created）で処理

---

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

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

### 推奨読解順序

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

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

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

**読解のコツ**: Issueコメントイベントはissue情報とcomment情報の両方を含む。bodyフィールドはコメント本文だが、コールサイン除去後の内容が設定される点に注意。

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

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

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

**主要処理フロー**:
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` | handleIssueCommentCreated関数（201-227行目）、コールサイン照合ロジック |
| 3-2 | event-handlers.ts | `packages/giselle/src/github/event-handlers.ts` | processEvent関数（478-813行目）、タスク作成とコールバック処理 |

**主要処理フロー**:
- **204-209行目**: Webhookイベントとトリガー設定のイベント種別照合
- **216行目**: parseCommandでコールサイン抽出
- **217-224行目**: conditions.callsignとの照合
- **226行目**: リアクションNodeIdとしてcomment.node_idを返す

#### Step 4: コールサイン解析を理解する

コメントからコールサインを抽出する処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | utils.ts | `packages/giselle/src/github/utils.ts` | parseCommand関数、コールサイン形式の解析 |

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

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

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

**主要処理フロー**:
- **244-249行目**: イベント種別とトリガー設定の確認
- **251-257行目**: コールサインの検証
- **264-269行目**: bodyフィールドの出力生成（command.content: コールサイン除去後の内容）
- **279-287行目**: issueNumberフィールドの出力生成

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

```
handleGitHubWebhookV2 (handle-webhook-v2.ts)
    │
    ├─ handleWebhook (github-tool)
    │      └─ Webhook署名検証
    │
    └─ process (handle-webhook-v2.ts:125-192)
           │
           ├─ getGitHubRepositoryIntegrationIndex
           │      └─ リポジトリ連携情報取得
           │
           └─ processEvent (event-handlers.ts:478-813)
                  │
                  ├─ handleIssueCommentCreated (event-handlers.ts:201-227)
                  │      │
                  │      ├─ parseCommand (utils.ts)
                  │      │      └─ コールサイン抽出
                  │      │
                  │      └─ コールサイン照合
                  │
                  ├─ addReaction
                  │      └─ EYESリアクション追加
                  │
                  └─ createAndStartTask
                         │
                         └─ resolveTrigger (resolve-trigger.ts)
                                │
                                └─ resolveIssueCommentTrigger (trigger-utils.ts:240-304)
                                       └─ ペイロード解決
```

### データフロー図

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

GitHub Webhook ───────▶ handleGitHubWebhookV2 ───────▶ Giselle Task
(issue_comment.created)      │                           │
      │                      │                           │
      ▼                      ▼                           ▼
┌─────────────┐      ┌─────────────────┐       ┌────────────────────┐
│ issue.number│      │ processEvent    │       │ outputId: issueNumber │
│ issue.title │      │ handleIssueComment │    │ outputId: issueTitle │
│ issue.body  │  ──▶ │ Created         │  ──▶ │ outputId: issueBody │
│ comment.body│      │ parseCommand    │       │ outputId: body     │
│ (callsign)  │      │ resolveTrigger  │       │ (コールサイン除去後)│
└─────────────┘      └─────────────────┘       └────────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| 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` | ソース | イベントハンドラー群 |
| utils.ts | `packages/giselle/src/github/utils.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` | ソース | トリガーレジストリエクスポート |
