# 機能設計書 8-トリガーノード

## 概要

本ドキュメントは、Giselleにおけるトリガーノード機能の設計を定義する。ワークフローの開始点を定義し、手動実行またはGitHubイベント（Issue作成、PRオープン等）で自動起動するためのオペレーションノードの型定義とデータ構造を規定する。

### 本機能の処理概要

トリガーノードは、ワークフローの実行開始点を定義するオペレーションノードである。手動トリガーまたはGitHubなどの外部サービスからのイベントによりワークフローを起動する。

**業務上の目的・背景**：Giselleのワークフローを自動実行するには、実行のきっかけとなるトリガーが必要である。本機能により、GitHubのIssue作成やPull Requestのオープンなど、様々なイベントをトリガーとしてワークフローを自動実行できる。これにより、開発プロセスの自動化やイベント駆動型のAIワークフローが実現可能となる。

**機能の利用シーン**：ワークフローエディタ画面でトリガーノードを追加・設定する時、GitHubリポジトリとの連携設定を行う時、トリガーの有効化・無効化を切り替える時などに利用される。

**主要な処理内容**：
1. トリガーノードの型定義（TriggerContent）
2. トリガープロバイダーの定義（GitHub等）
3. トリガー設定状態の管理（unconfigured/configured/reconfiguring）
4. フロートリガーIDによるトリガー設定の参照

**関連システム・外部連携**：trigger-registryパッケージによるトリガープロバイダー定義と連携。GitHub Appを通じたWebhook連携。

**権限による制御**：トリガー設定にはGitHub App連携とリポジトリへのアクセス権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 17 | ワークフローエディタ画面 | 補助機能 | ワークフローの開始点トリガーノードの追加・編集 |

## 機能種別

データ型定義 / ノード構造定義

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| type | "trigger" | Yes | ノードコンテンツ種別 | リテラル型 |
| provider | TriggerProvider | Yes | トリガープロバイダー（github等） | カスタムバリデーション |
| state | TriggerConfigurationState | Yes | トリガー設定状態 | discriminatedUnion |

### トリガー設定状態

| 状態 | 型 | 説明 |
|------|-----|------|
| unconfigured | TriggerUnconfiguredState | 未設定状態 |
| configured | TriggerConfiguredState | 設定完了状態（flowTriggerIdを含む） |
| reconfiguring | TriggerReconfiguringState | 再設定中状態（flowTriggerIdを含む） |

## 出力仕様

### 出力データ

トリガーノードは入力を持たず、トリガーイベントのデータを出力として提供する。

| 出力種別 | 説明 |
|---------|------|
| イベントデータ | トリガーイベントに含まれる情報（Issue内容、PR情報等） |

### 出力先

- ワークフロー内の後続ノード（接続経由）

## 処理フロー

### データ構造定義フロー

```
1. TriggerConfigurationState定義
   └─ TriggerUnconfiguredState（status: "unconfigured"）
   └─ TriggerConfiguredState（status: "configured", flowTriggerId）
   └─ TriggerReconfiguringState（status: "reconfiguring", flowTriggerId）

2. TriggerContent定義
   └─ type: "trigger"固定
   └─ provider: TriggerProvider（外部定義）
   └─ state: TriggerConfigurationState
```

### フローチャート

```mermaid
flowchart TD
    A[TriggerContent] --> B[type: "trigger"]
    A --> C[provider選択]
    C --> D[TriggerProvider]

    A --> E{state}
    E -->|unconfigured| F[未設定状態]
    E -->|configured| G[設定完了]
    E -->|reconfiguring| H[再設定中]

    G --> I[flowTriggerId参照]
    H --> I
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 状態遷移 | unconfigured → configured → reconfiguring → configured の遷移パターン | 常に適用 |
| BR-002 | flowTriggerId必須 | configured/reconfiguringではflowTriggerIdが必須 | 設定済み/再設定中の場合 |
| BR-003 | プロバイダー検証 | providerはisTriggerProvider関数で検証 | 常に適用 |

### 計算ロジック

特になし（型定義のため）

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

本機能は型定義のため、直接のデータベース操作は発生しない。トリガー設定はストレージに別途保存される。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| VALIDATION_ERROR | バリデーションエラー | Zodスキーマ検証失敗 | 入力データの確認 |
| INVALID_PROVIDER | プロバイダー不正 | 未対応のプロバイダー指定 | 対応プロバイダーを使用 |
| INVALID_STATE | 状態不正 | 不正な状態遷移 | 状態遷移ルールを確認 |

### リトライ仕様

型定義のため該当なし

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

型定義のため該当なし

## パフォーマンス要件

型定義のため該当なし

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

- flowTriggerIdはシステム内部のIDであり、外部からの推測を困難にする
- トリガー設定にはGitHub App連携の認証が必要

## 備考

- TriggerContentReferenceはノード参照時の軽量版として使用
- trigger-registryパッケージでサポートされるプロバイダーの詳細は別途定義

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | trigger.ts | `packages/protocol/src/node/operations/trigger.ts` | TriggerContent全体構造 |
| 1-2 | index.ts | `packages/protocol/src/trigger/index.ts` | TriggerId定義 |

**読解のコツ**: TriggerConfigurationStateの3つの状態と状態遷移を理解する。

#### Step 2: トリガー設定状態を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | trigger.ts | `packages/protocol/src/node/operations/trigger.ts` | 各状態の定義（8-23行目） |

**主要処理フロー**:
- **8-10行目**: TriggerUnconfiguredState（status: "unconfigured"のみ）
- **11-14行目**: TriggerConfiguredState（status: "configured" + flowTriggerId）
- **15-18行目**: TriggerReconfiguringState（status: "reconfiguring" + flowTriggerId）
- **19-23行目**: TriggerConfigurationState（discriminatedUnion）

#### Step 3: TriggerContentを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | trigger.ts | `packages/protocol/src/node/operations/trigger.ts` | TriggerContent定義（25-30行目） |

**主要処理フロー**:
- **26行目**: type: "trigger"固定
- **27行目**: provider: カスタムバリデーション（isTriggerProvider）
- **28行目**: state: TriggerConfigurationState

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

```
TriggerContent (trigger.ts)
    │
    ├─ type: z.literal("trigger")
    │
    ├─ provider: z.custom<TriggerProvider>
    │      └─ isTriggerProvider (trigger-registry)
    │
    └─ state: TriggerConfigurationState
           └─ z.discriminatedUnion("status", [...])
                  ├─ TriggerUnconfiguredState
                  ├─ TriggerConfiguredState
                  │      └─ flowTriggerId: TriggerId.schema
                  └─ TriggerReconfiguringState
                         └─ flowTriggerId: TriggerId.schema
```

### データフロー図

```
[ワークフローエディタ]              [プロトコル層]              [トリガー管理]

トリガー設定UI ───▶ TriggerContent
    │                     │
    │                     ├─ provider ───▶ トリガープロバイダー
    │                     │
    │                     └─ state ───▶ 設定状態管理
    │                            │
    │                            └─ flowTriggerId ───▶ トリガー設定参照
    │
    ▼
Workspace.nodes[] ───▶ ストレージ保存
                              │
                              ▼
                       外部イベント受信 ───▶ ワークフロー起動
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| trigger.ts | `packages/protocol/src/node/operations/trigger.ts` | ソース | TriggerContent定義 |
| operation-node.ts | `packages/protocol/src/node/operations/operation-node.ts` | ソース | TriggerNode型、isTriggerNode関数 |
| index.ts | `packages/protocol/src/trigger/index.ts` | ソース | TriggerId定義 |
| github.ts | `packages/trigger-registry/src/github.ts` | ソース | GitHubトリガーイベント定義 |
