# 機能設計書 33-トリガー設定

## 概要

本ドキュメントは、Giselleワークフローエンジンにおける「トリガー設定」機能の設計を記述する。本機能は、ワークフローの開始条件（トリガー）を設定し、手動実行またはGitHubイベントによる自動起動を構成するAPIを提供する。

### 本機能の処理概要

本機能は、ワークフロー内のトリガーノードに対して、起動条件（GitHubイベントまたは手動パラメータ）を設定し、ストレージに永続化する。GitHubトリガーの場合は、リポジトリ連携インデックスの作成も同時に行う。

**業務上の目的・背景**：ワークフローを特定の条件で自動起動させたり、パラメータ付きで手動実行可能にするために、トリガーの設定が必要となる。GitHubのIssue作成やPull Requestオープンなどのイベントに連動した自動化を実現する。

**機能の利用シーン**：
- ワークフローエディタでトリガーノードの起動条件を設定する場合
- GitHubリポジトリと連携してイベント駆動のワークフローを構成する場合
- 手動実行用のパラメータ定義を行う場合

**主要な処理内容**：
1. トリガー設定情報（ConfigureTriggerInput）を受け取る
2. 新しいTriggerId（fltg-xxx形式）を生成
3. ワークスペースデータを取得
4. トリガーデータをストレージに保存
5. GitHubトリガーの場合はリポジトリ連携インデックスを追加
6. トリガーノードの状態を「configured」に更新
7. ワークスペースを保存

**関連システム・外部連携**：
- GiselleStorageを介したファイルストレージとの連携
- GitHub連携インデックスの更新

**権限による制御**：ワークスペースへの編集権限を持つユーザーのみがトリガー設定を実行可能

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 17 | ワークフローエディタ画面 | 主画面 | ワークフローのトリガー設定処理 |

## 機能種別

データ作成（INSERT操作）/ 更新（UPDATE操作）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| context | GiselleContext | Yes | Giselle実行コンテキスト | - |
| trigger | ConfigureTriggerInput | Yes | トリガー設定情報（idを除くTrigger型） | Zodスキーマ検証 |

#### ConfigureTriggerInput詳細

| フィールド | 型 | 必須 | 説明 |
|-----------|-----|-----|------|
| workspaceId | WorkspaceId | Yes | ワークスペースID |
| nodeId | NodeId | Yes | トリガーノードID |
| enable | boolean | No | 有効/無効（デフォルト: true） |
| configuration | GitHubEventConfiguration \| ManualTrigger | Yes | トリガー種別固有の設定 |

### 入力データソース

- API呼び出しによるトリガー設定情報

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| triggerId | TriggerId | 生成されたトリガーID（fltg-xxx形式） |

### 出力先

- ストレージ: `flow-triggers/{triggerId}.json`
- ストレージ: ワークスペースファイル（ノード状態更新）
- GitHub連携インデックス（GitHubトリガーの場合）

## 処理フロー

### 処理シーケンス

```
1. TriggerIdを生成
   └─ TriggerId.generate()でfltg-xxx形式のID生成

2. 並列処理の実行
   ├─ ワークスペースデータの取得
   ├─ トリガーデータの保存（setTrigger）
   └─ GitHubトリガーの場合：リポジトリ連携インデックス追加

3. ワークスペース内のトリガーノード状態を更新
   └─ status: "configured"、flowTriggerId: 生成したID

4. 更新されたワークスペースを保存

5. TriggerIdを返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[TriggerId生成]
    B --> C[並列処理開始]
    C --> D[ワークスペース取得]
    C --> E[トリガーデータ保存]
    C --> F{GitHubトリガー?}
    F -->|Yes| G[リポジトリ連携インデックス追加]
    F -->|No| H[スキップ]
    D --> I[並列処理完了待ち]
    E --> I
    G --> I
    H --> I
    I --> J[トリガーノード状態更新]
    J --> K[ワークスペース保存]
    K --> L[TriggerId返却]
    L --> M[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-33-001 | トリガーID形式 | トリガーIDは`fltg-`プレフィックス付きのUUID形式 | 常時 |
| BR-33-002 | プロバイダー種別 | configurationのproviderは`github`または`manual` | 常時 |
| BR-33-003 | ノード状態更新 | トリガー設定後、ノードのstateはconfiguredに変更 | 常時 |
| BR-33-004 | 連携インデックス | GitHubトリガーの場合のみリポジトリ連携インデックスを作成 | provider === "github" |

### 計算ロジック

該当なし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ワークスペース取得 | ストレージ | SELECT | ワークスペースデータの読み込み |
| トリガー保存 | ストレージ | INSERT | flow-triggers/{id}.jsonの作成 |
| 連携インデックス追加 | ストレージ | INSERT/UPDATE | GitHubリポジトリ連携インデックスの更新 |
| ワークスペース更新 | ストレージ | UPDATE | ワークスペースファイルの更新 |

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

#### ストレージ（flow-triggers/{triggerId}.json）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | 全フィールド | Trigger型データ | Zodスキーマで検証 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ワークスペース不在 | 指定ワークスペースが存在しない | エラーをスロー |
| - | ノード不在 | 指定ノードIDがワークスペース内に存在しない | 更新処理をスキップ |
| - | 型不一致 | ノードがトリガーノードでない | 更新処理をスキップ |

### リトライ仕様

該当なし

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

- Promise.allによる並列処理で一貫性を確保
- エラー発生時は部分的にデータが保存される可能性あり

## パフォーマンス要件

- レスポンス時間：300ms以内

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

- GiselleContextを通じてアクセス制御
- GitHubのinstallationIdなど認証情報の適切な管理

## 備考

- トリガーIDの生成には`createIdGenerator("fltg")`を使用
- discriminated union（provider: "github" | "manual"）で設定種別を判別

---

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

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

### 推奨読解順序

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

まず、Trigger型とその設定種別を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts | `packages/protocol/src/trigger/index.ts` | Trigger型、TriggerId、discriminated union構造を理解 |
| 1-2 | github.ts | `packages/protocol/src/trigger/github.ts` | GitHubEventConfiguration型を理解 |
| 1-3 | manual.ts | `packages/protocol/src/trigger/manual.ts` | ManualTrigger型を理解 |

**読解のコツ**: configurationフィールドはproviderで判別されるdiscriminated union。"github"と"manual"の2種類。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | configure-trigger.ts | `packages/giselle/src/triggers/configure-trigger.ts` | 公開API関数の全体フロー |

**主要処理フロー**:
1. **13-14行目**: ConfigureTriggerInputスキーマ定義（idを除くTrigger）
2. **20行目**: TriggerId.generate()で新規ID生成
3. **21-40行目**: Promise.allで並列処理（ワークスペース取得、トリガー保存、連携インデックス追加）
4. **41-61行目**: ワークスペース内のトリガーノード状態を更新
5. **62行目**: TriggerIdを返却

#### Step 3: ユーティリティ層を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | utils.ts | `packages/giselle/src/triggers/utils.ts` | setTrigger関数（9-23行目） |
| 3-2 | utils.ts | `packages/giselle/src/integrations/utils.ts` | addGitHubRepositoryIntegrationIndex関数 |

**主要処理フロー（setTrigger）**:
- **5-7行目**: triggerPath関数でストレージパス生成（`flow-triggers/{triggerId}.json`）
- **16-21行目**: storage.setJson()でトリガーデータを保存

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

```
configureTrigger (configure-trigger.ts)
    │
    ├─ TriggerId.generate()
    │
    ├─ Promise.all
    │      │
    │      ├─ getWorkspace (workspaces/utils.ts)
    │      │
    │      ├─ setTrigger (triggers/utils.ts)
    │      │      │
    │      │      ├─ triggerPath()
    │      │      │
    │      │      └─ storage.setJson()
    │      │
    │      └─ addGitHubRepositoryIntegrationIndex (integrations/utils.ts)
    │             └─ [GitHubトリガーの場合のみ]
    │
    └─ setWorkspace (workspaces/utils.ts)
           └─ ノード状態更新 → 保存
```

### データフロー図

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

ConfigureTriggerInput ───▶ TriggerId.generate() ───▶ triggerId
        │
        ▼
   並列処理 ─────────────▶ getWorkspace() ───▶ workspace
        │
        ├─────────────────▶ setTrigger() ───▶ flow-triggers/{id}.json
        │
        └─────────────────▶ addGitHubRepositoryIntegrationIndex()
                                   │
                                   ▼
                           連携インデックス更新
        │
        ▼
   ノード状態更新 ───────▶ setWorkspace() ───▶ ワークスペース保存
        │
        ▼
   TriggerId返却
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| configure-trigger.ts | `packages/giselle/src/triggers/configure-trigger.ts` | ソース | 公開API関数 |
| utils.ts | `packages/giselle/src/triggers/utils.ts` | ソース | setTrigger、getTrigger実装 |
| index.ts | `packages/protocol/src/trigger/index.ts` | ソース | Trigger型、TriggerId定義 |
| github.ts | `packages/protocol/src/trigger/github.ts` | ソース | GitHubEventConfiguration型 |
| manual.ts | `packages/protocol/src/trigger/manual.ts` | ソース | ManualTrigger型 |
| utils.ts | `packages/giselle/src/integrations/utils.ts` | ソース | addGitHubRepositoryIntegrationIndex |
| utils.ts | `packages/giselle/src/workspaces/utils.ts` | ソース | getWorkspace、setWorkspace |
