# 機能設計書 16-GitHubノード

## 概要

本ドキュメントは、Giselleワークフローエンジンにおける GitHubノード（GitHubNode）の機能設計を記述する。GitHubノードは、GitHubリポジトリ関連データ（Issue、Issueコメント等）を保持し、他のノードへ提供するための変数ノードである。

### 本機能の処理概要

GitHubノードは、ワークフロー内でGitHubオブジェクト（Issue、Issueコメント等）への参照を管理する機能である。GitHubオブジェクトのURL、オーナー、リポジトリ名、タイプ、IDを保持し、接続された後続ノードへ入力として提供する。

**業務上の目的・背景**：GitHubとの連携ワークフローにおいて、Issue情報やコメント情報を参照してAI処理を行うケースが多い。GitHubノードは、そのようなGitHubオブジェクトへの参照を管理し、トリガーイベントからの入力データを保持・伝播する役割を担う。

**機能の利用シーン**：
- GitHubトリガーで受け取ったIssue情報をワークフローで利用する場合
- Issue内容をAIで分析して自動応答する場合
- 複数のGitHubオブジェクトを参照するワークフローを構築する場合

**主要な処理内容**：
1. GitHubオブジェクト参照（URL、owner、repo、type、id）の保持
2. 複数オブジェクト参照の配列管理
3. 出力ポートを通じた後続ノードへのデータ提供

**関連システム・外部連携**：
- GitHubトリガーイベント（No.41-52）からの入力
- GitHubアクション（No.53-59）への連携
- GitHub API

**権限による制御**：特になし（ワークスペース編集権限に依存）

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 17 | ワークフローエディタ画面 | 主画面 | GitHubノードの追加・編集 |

## 機能種別

データ格納 / 外部参照管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| type | "github" | Yes | ノードコンテンツタイプ | リテラル値 |
| objectReferences | GitHubObjectReference[] | Yes | GitHubオブジェクト参照配列 | 配列形式 |

### GitHubObjectReference構造

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|-----|------|
| url | string (URL) | Yes | GitHubオブジェクトのURL |
| owner | string | Yes | リポジトリオーナー名 |
| repo | string | Yes | リポジトリ名 |
| type | GitHubObjectType | Yes | オブジェクトタイプ |
| id | string | Yes | オブジェクトID |

### GitHubObjectType

| 値 | 説明 |
|----|------|
| issue | GitHub Issue |
| issueComment | GitHub Issueコメント |

### 入力データソース

- **GitHubトリガーイベント**: Webhook経由で受信したイベントデータ
- **手動設定**: UIからのGitHubオブジェクト参照追加

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| outputs | Output[] | 出力ポート配列（1要素） |
| outputs[0].id | OutputId | 出力ポートID |
| outputs[0].label | "Output" | 表示ラベル |
| outputs[0].accessor | "text" | アクセサー名 |

### 出力先

- 接続された後続ノードへのGitHubオブジェクト参照提供
- テキスト生成ノードへの入力（Issue内容等）

## 処理フロー

### 処理シーケンス

```
1. ノード生成（createGitHubNode）
   └─ 空のobjectReferences配列で初期化
   └─ 出力ポート（accessor: "text"）を生成

2. オブジェクト参照追加
   └─ URL、owner、repo、type、idを設定
   └─ objectReferences配列に追加

3. ワークフロー実行時
   └─ GitHubトリガーからの入力値をobjectReferencesに設定
   └─ 接続されたノードがオブジェクト参照を利用
```

### フローチャート

```mermaid
flowchart TD
    A[ノード追加] --> B[空objectReferencesで初期化]
    B --> C[出力ポート生成]
    C --> D{オブジェクト参照追加}
    D -->|手動設定| E[URLからオブジェクト情報抽出]
    D -->|トリガー入力| F[トリガーイベントから設定]
    E --> G[objectReferences配列に追加]
    F --> G
    G --> H[ワークスペース保存]
    H --> D
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | URL検証 | objectReference.urlは有効なURL形式であること | オブジェクト参照追加時 |
| BR-002 | タイプ制限 | GitHubObjectTypeはissue/issueCommentのみ | オブジェクト参照追加時 |
| BR-003 | 複数参照対応 | 1つのノードで複数のGitHubオブジェクトを参照可能 | objectReferences配列管理 |

### 計算ロジック

特になし（参照管理ノードのため）

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | 本ノード単体ではDB操作なし |

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

GitHubノード単体でのDB操作はない。ワークスペース更新機能と連携して動作する。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | - | 特になし |

### リトライ仕様

本機能はリトライ機構を持たない。

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

本ノード単体でのトランザクション制御はない。

## パフォーマンス要件

特になし（参照管理ノードのため）

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

- GitHubオブジェクトへのアクセスはGitHub連携設定に依存
- プライベートリポジトリへのアクセスにはGitHub Appインストールが必要

## 備考

- 現在サポートされているGitHubObjectTypeはissueとissueCommentの2種類
- 将来的にPull Request等の他のオブジェクトタイプが追加される可能性あり

---

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

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

### 推奨読解順序

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

まず、GitHubノードのスキーマ定義を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | github.ts | `packages/protocol/src/node/variables/github.ts` | GitHubContent、GitHubObjectType、GitHubObjectReferenceのスキーマ定義 |
| 1-2 | index.ts | `packages/protocol/src/node/variables/index.ts` | GitHubNode型、isGitHubNode判定関数 |

**読解のコツ**: GitHubObjectReferenceはURL、owner、repo、type、idの5つのプロパティを持つシンプルな構造。

#### Step 2: ノード生成ファクトリを理解する

ノードがどのように生成されるかを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | node-factories.ts | `packages/node-registry/src/node-factories.ts` | githubVariableFactoryImplの実装 |

**主要処理フロー**:
- **549-576行目**: githubVariableFactoryImplのcreate/clone実装
- **1007-1010行目**: createGitHubNode関数のエクスポート

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

```
createGitHubNode (node-factories.ts)
    │
    └─ GitHubNode生成
           ├─ id: NodeId.generate()
           ├─ type: "variable"
           ├─ content.type: "github"
           ├─ content.objectReferences: []
           ├─ inputs: []
           └─ outputs: [{accessor: "text"}]
```

### データフロー図

```
[ノード生成]                    [トリガーイベント]

createGitHubNode ──▶ 空GitHubNode    GitHubイベント受信
       │                                    │
       ▼                                    ▼
objectReferences: [] ◀──────── WebhookデータからobjectReference生成
       │                                    │
       ▼                                    ▼
[ワークフロー実行]                   objectReferences設定
       │                                    │
       ▼                                    ▼
接続ノードから参照 ◀────────────────────────┘
       │
       ▼
Issue/コメント内容取得
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| github.ts | `packages/protocol/src/node/variables/github.ts` | ソース | GitHubContentスキーマ定義 |
| index.ts | `packages/protocol/src/node/variables/index.ts` | ソース | GitHubNode型、isGitHubNode関数 |
| node-factories.ts | `packages/node-registry/src/node-factories.ts` | ソース | ノード生成ファクトリ |
| handle-webhook-v2.ts | `packages/giselle/src/github/handle-webhook-v2.ts` | ソース | GitHubイベント処理 |
